Skip to content

Install

Jump to bottom
Sajeer N edited this page Oct 28, 2019 · 23 revisions

PacBot Installer

Overview

This page describes the steps to install PacBot. PacBot is built to be deployed in AWS mostly using managed services. There are 3 major components in PacBot.

PacBot Rule Engine                  : CloudWatch Rules, Lambda, AWS Batch, AWS ElasticSearch

PacBot Web Application (UI & APIs)  : AWS ECS, Fargate, AWS ElasticSearch, RDS

PacBot Inventory Collector          : Cloudwatch Rules, AWS Batch, AWS ElasticSearch, RDS

List of AWS resources that will be created by the installer.

List of AWS resources that will be created by the installer.

  • IAM Roles
  • IAM Policies
  • S3 Bucket
  • RDS
    • MySQL 5.6.X
  • Elasticsearch Service
    • Elasticsearch version 5.5
  • Batch
    • Compute environments, Job Definitions and Job Queues
  • Elastic Container Registry
    • Repositories - for batch job, API and UI
  • Elastic Container Service - AWS Fargate
    • Clusters - for APIs, UI and Batch
    • Task Definitions - for APIs and UI
  • Lambda Functions
    • SubmitBatchJob and SubmitRuleJob
  • CloudWatch Rules

Steps to Install

This python installer script will launch the above listed AWS resources and configure them as required for the PacBot application. This will also build the application from the source code. The built JARs and Angular app are then deployed in AWS ECS.

Prerequisites

PacBot installer is developed using Python and Terraform. For the installer to run, you will need to have below listed dependencies installed correctly.

  • Software Dependencies:
  1. Python supported version is 3.4 or above and Following python packages are required.
    • docker-py (1.10)]
    • python-terraform (0.10)
    • boto3 (1.9)
  2. Install the latest version of Terraform from https://learn.hashicorp.com/terraform/getting-started/install.html
  3. Install node version 8.15.0 or higher
  4. Install npm version 6.4.1 or higher
  5. Install the following npm packages
    • Install Angular-CLI version 7.1.4 or higher
    • Install bower version 1.8.4 or higher
  6. Install java version openjdk1.8
  7. Install mvn(Maven) version 3.0 or higher
  8. Install docker version 18.06 or higher
  9. Install MySQL version 15.1 or higher

  • AWS IAM Permission Installer would need an IAM account to launch and configure the AWS resources. To keep it simple you can create an IAM account with full access to above listed AWS service or temporarily assign Poweruser/Administrator permission. After the installation, you can remove the IAM account.

  • Make sure that docker service is running during the installation time.

  • The installer box or machine from where the installation is happening should be on the same VPC or should be able to connect to MySQL DB

System Setup To Run Installer

  1. Installer System:
    Recommended to use Amazon Linux / CentOS 7 / Ubuntu
  1. System Configurations:
    Recommended instance type: t2.medium (Minimum 4GB memory)
    VPC: Same as where PacBot is desired to be installed. This is required for installer script to connect to MySQL DB
  1. Install Git
    sudo yum install git
  1. Install Pip & required modules
    sudo yum install -y epel-release python3-pip
    sudo pip3 install -r requirements.txt
  1. Install other dependencies
     sudo yum -y install java-1.8.0-openjdk docker maven unzip mysql
     sudo systemctl start docker
  1. To install terraform, download the latest version
     wget https://releases.hashicorp.com/terraform/0.11.11/terraform_0.11.11_linux_amd64.zip
     unzip terraform_0.11.11_linux_amd64.zip
     mv terraform /usr/bin/
  1. To install UI build dependencies, please click here

Install and Deploy PacBot

  1. Clone the repo
    git clone [email protected]:tmobile/pacbot.git

  1. Go to pacbot-installer directory

  2. Create settings/local.py file by copying from settings/default.local.py

  3. Update settings/local.py file with the required values - Mandaory Changes

   VPC ID
   VPC CIDR
   SUBNET IDS (2 Subnets are required. Both the subnets should not be in the same AZ.)
  1. Run the installer. (Go grab a coffee now :), it would take a while to provision the AWS resources)
    sudo python3 manager.py install
  1. Installation logs will be available in logs directory
    tail -f logs/debug.log -> To see the debug log
    tail -f logs/error.log -> To see the error log
    tail -f logs/terraform_install.log -> To see Terraform Installation log
    tail -f logs/terraform_destroy.log -> To see Terraform Destroy log

Once the installation is complete, go to the PacBot ELB URL to access the web application. Use the default credentials

Redeploy

Once you have installed the application and later if any update occurs then you would be able to redeploy it without any change in endpoints and URL. Please follow the below steps to redeploy the applications

  1. Go to pacbot source code and pull the latest changes
    git pull --rebase

  1. Go to pacbot-installer directory

  2. Run the below command to redeploy the application

    sudo python3 manager.py redeploy

Recommendation & Health Notification installation

Note that the above 'redeploy' command is the mechanism to install the new Recommendation and Health Notification features.

Uninstall


sudo python3 manager.py destroy

'destroy' will terminate all the AWS resources created during the installation.

Troubleshooting

Installation issues will be mostly around permissions and dependencies required by the installer. Please make sure all the dependencies are installed correctly before installing PacBot.

Adding New AWS Accounts to PacBot to Monitor

  1. IAM Role Changes The account where PacBot is installed is called base account. The accounts that are monitored by PacBot is called client account.

    • Client Account Change: Create an IAM role named pacbot_ro and attach ReadOnlyAccess, AmazonGuardDutyReadOnlyAccess & AWSSupportAccess policies. Allow pacbot_ro from the base account to assume this role. Sample trust configuration for pacbot_ro role is here

      {
  "Version":"2012-10-17",
  "Statement":[
    {"Effect":"Allow",
    "Principal":{
      "AWS":["arn:aws:iam::Base_Account_ID:role/pacbot_ro"]
      },
      "Action":"sts:AssumeRole"
      }]
  }

    • Base Account Change: Fetch client account pacbot_ro role arn and update / add pacbot_ro policy which is associated with pacbot_ro role in Base account. Sample pacbot_ro policy,

      {
  "Version":"2012-10-17",
  "Statement":[
    {"Sid":"",
    "Effect":"Allow",
    "Action":"sts:AssumeRole",
    "Resource":["arn:aws:iam::Client_Account_ID_1:role/pacbot_ro","arn:aws:iam::Client_Account_ID_2:role/pacbot_ro"]
    }]
}

  2. Cloudwatch Rule Changes

  • Update "accountinfo" value (in Constant (JSON text) of cloudwatch rule) with new client account ids in cloudwatch rule named "AWS-Data-Collector". Sample configuration is {"encrypt":false,"value":"Base_Account_ID,Client_Account_ID_1,Client_Account_ID_2","key":"accountinfo"} 
New AWS account management page with features to add remove accounts is being developed. Watch out this section for the updates.
Till then you have to configure it manually

How to setup SSL?

You can secure PacBot by enabling SSL. To enable this you have to follow the below steps Configure the below variables in local.py

  • Set ALB_PROTOCOL to HTTPS
  • Set SSL_CERTIFICATE_ARN with the ARN obtained from ACM
  • Set PACBOT_DOMAIN if you have any else remove it.

Example 1: With self signed AWS internal URL

  ALB_PROTOCOL = "HTTPS" 
  SSL_CERTIFICATE_ARN = "arn:aws:acm:us-east-1:account_id:certificate/54d327ce-5f17-4a3a-9cb3-77dc10fa8371"
  PACBOT_DOMAIN = ""

Example 2: With external domain

  ALB_PROTOCOL = "HTTPS" 
  SSL_CERTIFICATE_ARN = "arn:aws:acm:us-east-1:account_id:certificate/54d327ce-5f17-4a3a-9cb3-77dc10fa8371"
  PACBOT_DOMAIN = "pacbot.com"

After making the above changes, you can run install command if you are installing for first time or redeploy command if you already installed PacBot

Configure SSL with AWS internal URL

If you don't have any domain for PacBot and want to use AWS internal URL with https, follow the below steps

  1. Create a self signed certificate for the internal URL
  2. Upload it in AWS ACM (Certificate Manager) and copy ARN of that certificate
  3. Update local.py to have the ALB_PROTOCOL=HTTPS and SSL_CERTIFICATE_ARN=< copied-arn-value >
  4. Run sudo python manager.py install if you are installing for first time or sudo python manager.py redeploy if you already installed PacBot
  5. Refer Example 1

Configure SSL for specific domain

  1. Create a domain for PacBot
  2. Obtain SSL certificate for the domain Or Create a self signed certificate
  3. Upload it in AWS ACM (Certificate Manager) and copy ARN of that certificate
  4. Update local.py to have the
  • ALB_PROTOCOL=HTTPS,
  • SSL_CERTIFICATE_ARN=< copied-arn-value >
  • PACBOT_DOMAIN=< created-domain-name >
  1. Run sudo python manager.py install if you are installing for first time or sudo python manager.py redeploy if you already installed PacBot
  2. Refer Example 2

How to scale up PacBot infrastructure ?

PacBot is capable to monitor thousands of accounts for compliance. As more and more accounts are onboarded to PacBot for monitoring, the infrastructure has to be scaled to support the increased data volume. Any performance issues that follow may entail to upgrade the underlying resources.

Upgrade RDS instance

PacBot default instance type for RDS-MySQL is db.t2.medium, but there is a provision to upgrade it if you need higher instance type. To upgrade RDS follow the below steps

  1. Go to local.py file
  2. Set RDS_INSTANCE_TYPE to a type you require.
RDS_INSTANCE_TYPE = "db.t2.large"
  1. Run the command, sudo python3 manager.py upgrade to upgrade the server instance type

Upgrade Elasticsearch instance

PacBot default instance type for Elasticsearch cluster is m4.large.elasticsearch, but there is a provision to upgrade it if you need higher instance type. To upgrade Elasticsearch follow the below steps

  1. Go to local.py file
  2. Set ES_INSTANCE_TYPE to an instance type you require.
ES_INSTANCE_TYPE = "m4.xlarge.elasticsearch"
  1. Run the command, sudo python3 manager.py upgrade to upgrade the server instance typ

Limitations:

  • Current version supports only AWS stack.
  • AWS Fargate is not available in all AWS regions. Please visit AWS Region Table for more information on AWS regions and services.
Clone this wiki locally