Skip to content
Automation for standing up Gen3 commons on AWS, GCP, Azure, and on-prem
HCL Shell Python Makefile JavaScript Ruby Other
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
Chef Chore/dashboard (#973) Sep 5, 2019
Docker chore(jenkins): update to latest (2.192) version (#967) Aug 29, 2019
Jenkins refactor(configs): mv kube-setup-* to gen3/bin May 8, 2018
ansible Chore/rds module (#987) Sep 19, 2019
apis_configs chore(deprecate-signpost): add indexclient env vars/config (#887) Jun 17, 2019
doc Fix/reports sort (#989) Sep 19, 2019
files Fix/reports sort (#989) Sep 19, 2019
flavors Fix/netpolicy (#872) Jun 12, 2019
gen3 Chore/dboard web (#984) Sep 17, 2019
kube Fixed secret string in (#964) Sep 20, 2019
.gitignore Chore/dboard web (#984) Sep 17, 2019
CSOC_DETAILS_v1.svg Adding updated CSOC diag (#691) Feb 19, 2019 Adding updated CSOC diag (#691) Feb 19, 2019
CSOC_networkdiag_V1.png Add files via upload Jul 25, 2018
Jenkinsfile Feat/sec alarms (#978) Sep 16, 2019
LICENSE feat(license): add apache license Jul 20, 2017
NOTICE feat(license): add apache license Jul 20, 2017 chore(README): reference to CSOC free (#890) Jun 18, 2019
network-diag.svg Chore/network diag (#694) Feb 20, 2019
package-lock.json Chore/dboard web (#984) Sep 17, 2019
package.json Chore/dboard web (#984) Sep 17, 2019 feat(pr_template) (#561) Oct 30, 2018


This code supports automation of several PlanX processes:

  • ./tf_files - terraform infrastructure automation - for creating resources in the cloud like databuckets, networks, databases, and kubernetes clusters
  • ./kube - kubernetes automation - for deploying services, configuration, secrets, and jobs to a kubernetes cluster
  • ./Docker - image automation - for building various Docker images including Jenkins and devterm
  • ./Jenkins - Jenkins pipelines - for automating workflows like backing up the Jenkins server, testing the cloud-automation repo, and continuously deploying to the QA environments
  • ./gen3 - user friendly tools to simplify workflows with the ./kube kubernetes and ./tf_files terraform automation - more details
  • ./doc - gen3 help docs

The repository also interacts closely with the images and [cdis-manifest]

Table of contents

Independent Setup

There are a couple of ways you can build up a commons. The one we call CSOC free and the other attached to a CSOC account.

CSOC stands for Commons Services Operations Center, which is a term used internally to refer to our centralized operation center for multiple commons. Visit for more information.

For third party installs, the CSOC free is recommended. Commons attached to a CSOC account would be justified when managing multiple commons, where keeping up with daily tasks may become a little cumbersome.

For setup instructions, please visit



Most of our interaction with CDIS AWS accounts occur via the central CDIS CSOC account. This page describes the CSOC architecture

New account flow

  • Create an csoc_adminvm role in the new account with a trust relationship that allows the CSOC account to create roles that can assume the csoc_adminvm role in the new account:
  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::433568766270:root"
      "Action": "sts:AssumeRole",
      "Condition": {}
  • Create a new admin-vm in the CSOC. An administrator logs into an account's admin-vm to interact with the account's AWS API and kubernetes clusters:
    • connect to the CSOC VPN (requires multi-factor authentication)
    • ssh to the adminvm Contact CDIS ops team to request access to the CSOC VPN, and to add your ssh public key to the appropriate adminvm.

New adminVM

Admin VMs are used to communicate against the remote account from the CSOC account.

  1. SSH into CSOC master VM
Host csoc
   ServerAliveInterval 120
   User ubuntu
   ForwardAgent yes
  1. Access the cloud-automation folder and update if necessary:
$ cd cloud-automation
$ git checkout master
$ git pull
  1. Invoke gen3 to use the utilityVM module
$ gen3 workon csoc <name of account>_utilityvm
  1. Make the necessary changes to the config.tfvars
$ gen3 cd
$ cat config.tfvars
bootstrap_path = "cloud-automation/flavors/adminvm/"
bootstrap_script = ""
vm_name = "cdistest_admin"
vm_hostname = "cdistest_admin"
vpc_cidr_list = ["", "", "", "", "", "", ""]
extra_vars = ["account_id=707767160287"]
environment = "cdistest"
instance_type = "t2.micro"
aws_account_id = "707767160287"

Generally speaking, the bootstrap_path and bootstrap_script vars shouldn't need any change unless you want to use a custom one. Variables explanation:

  • vm_name: self explanatory.
  • vm_hostname: hostname to be used by the VM, usually the same as the name. But you could use a domain if you wanted to.
  • vpc_cidr_list: CIDRs where the VM would have egress access.
  • extra_vars: variables that will be used by bootstrap_script. For the above example, we are telling it to use the remote account ID, in which case will be used to set up awscli /home/ubuntu/.aws/config.
  • environment: for tagging purposes.
  • instance_type: the size of the VM.
  • aws_account_id: the remote account ID that this VM will have access to.
  1. Apply the module against AWS
$ gen3 tfplan

Check that it looks good and it'll do what you are expecting it to do.

$ gen3 tfapply

The output should show you the new VM's IP. Please make sure to update when it's done.

New commons flow

The CDIS ops team follows this flow to create a new commons.

  • Before creating a new commons, you must bring up the logging portion in the CSOC account. To achieve this, ssh into the CSOC master VM.
$ gen3 workon csoc <name of account>_logging
$ gen3 cd
$ sed -i 's/NUMERIC-ID/<account-id>/g' config.tfvar
$ gen3 tfplan
$ gen3 tfapply
  • Login to the adminvm, if this is a brand new account that requires a new adminVM, please see previous step.
  • Create a user account for the commons. There is one admin-vm per AWS account. We create one user on an account's admin-vm for each commons VPC under the account. Note that an adminvm acquires credentials to interact with the AWS API via the EC2 metadata service. For example, user accounts on the cdistest admin-vm have the following configuration:
$ cat ~/.aws/config
output = json
region = us-east-1
role_arn = arn:aws:iam::707767160287:role/csoc_adminvm
credential_source = Ec2InstanceMetadata

[profile cdistest]
output = json
region = us-east-1
role_arn = arn:aws:iam::707767160287:role/csoc_adminvm
credential_source = Ec2InstanceMetadata
  • Login to the commons account - ex: ssh commons@account-admin-vm.csoc
  • Run terraform to bring up a VPC to host the commons:
$ gen3 workon <account-profile> <commons-name>
$ gen3 cd
$ configure VPC CIDR in `config.tfvars`
$ gen3 tfplan
$ gen3 tfapply
  • Copy the commons config files to the home directory: cp {VPC_NAME}_output ~/{VPC_NAME}_output
  • Run kube-aws (via the kube-up command)
cd ~/{VPC_NAME}_output
  • Bring up the commons
source ~/.bashrc
edit ~/{VPC_NAME}/00configmap.yaml
edit ~/{VPC_NAME}_output/creds.json
gen3 roll all

Network Diagram

The following diagram intends to illustrate the network and basic communications between CSOC and a commons account.


Prerequisites for Commons

Google OAUTH credentials

We register each commons (going forward) as an OAuth client of the cdis-test project under the GCP domain (organization). Contact the CDIS ops team to request a Google client-id and secret for a new commons to support "Login with Google".

  • Create a Google project with the project name you want to use.
  • Enable the Google+ API after you create your project, the link above should take you there after project creation.
  • Click "Create Credentials" choose the "Google+ API", then choose "Web server" as API from, and choose "User data" as the data being accessed.
  • For the "Authorized JavaScript Origins" enter just the hostname like
  • For the "Authorized redirect URIs" enter hostname + '/user/login/google/login/' so for example
  • Download your credentials with contain the client_id and client_secret.

Configure certificate for your domain

For AWS, use the certificate manager to either import the certs or request admin for the domain to allow AWS to generate certs. The domain should match the hostname you configured in Google or the parent domain name.

Using the automated scripts

We have two automation scripts:

  • gen3 supports our terraform-based infrastructure automation
  • [g3k]

Create customized AMI

The latest versions of the customized ubuntu 16.04 AMI's required by the terraform automation are published as public images under the AWS cdis-test account. Build new AMIs using images.

You can’t perform that action at this time.