Nucleator CLI Reference

DESCRIPTION

This quick start introduction provides a walk-through of minimal steps to take to create your first Nucleator Cage and Stackset in a new AWS Account.

See Nucleator User’s Guide for a more in-depth introductions and Nucleator CLI Reference for command usage.

STEP 0 - PREREQUISITES

You will need to install on your local machine:

  • Python 2.7x

  • Python setup tools (pip)

  • Python developer tools (required for Ansible pre-requisites)

  • Git

To install:

sudo apt-get install python2.7 python-pip python-dev git

STEP 1 - INSTALL NUCLEATOR

Do this:

# (If your python installation does not require root access to install, remove "sudo" from the next two commands)

cd /tmp && git clone --recursive --depth 1 -b nucleator_distribution git://github.com/47lining/ansible.git && cd ansible && sudo python setup.py install

sudo pip install --upgrade git+git://github.com/47lining/nucleator-core.git

nucleator init

STEP 2 - FORK THE PUBLIC nucleator-core-siteconfig GITHUB REPOSITORY

For your first use of Nucleator, this quickstart recommends that you use a public siteconfig. Once you’ve seen how Nucleator Cages and Stacksets work, you can create a private siteconfig repository and provide Nucleator with a distribution key to access it. (For more information on setting up a github account see https://help.github.com/articles/set-up-git/ )

  1. log into github and navigate to https://github.com/47lining/nucleator-core-siteconfig

  2. Fork your own copy of this repository into your github account by clicking the "fork" button in the upper right

  3. Note the clone https URL for your personal siteconfig repository

  4. create a local clone: 

    cd <place_where_you_create_git_clones>
git clone <clone_url_noted_above>

STEP 3 - UPDATE STACKSET SOURCES TO USE YOUR PERSONAL SITECONFIG

Edit the Stackset sources list in ~/.nucleator/sources.yml and change the siteconfig stanza to include the <clone_url_noted_above>. Use the git:// protocol so authentication is not required (just replace the https:// in the https clone url with git://). After an initial pass through the quickstart, you can read the User’s Guide to learn more about how to specify a private repository in sources.yml.

Do this:

cd ~/.nucleator
nano sources.yml # modify to include siteconfig below
# siteconfig - Nucleator customer- and cage- specific configuration
- src: git+git://github.com/<your_github_account>/nucleator-core-siteconfig.git
  version: master
  name: siteconfig

STEP 4 - SIGN UP FOR NEW AWS ACCOUNT

You may be able to use an existing AWS Account with Nucleator, but we suggest creating a new one. Nucleator makes it easy to manage AWS Resources across AWS Account boundaries, and AWS Accounts serve as very useful containers and boundaries for AWS Resources

  1. To create a new AWS Account, visit the AWS Console: https://console.aws.amazon.com/

  2. Choose "I am a new user" to create a new AWS Account

  3. If you are visiting the console using your AWS Console shortcut link for an existing account, you will need to choose the small link "Sign-in using root account credentials" beneath the Sign In button to get to the "Sign In or Create an AWS Account" Page

  4. Complete the Account Signup process using the conventions described below

    Account Name: <youraccountname>-<yourcustomername>

    Account Email: <youraccountname>.accounts.aws.<yourcustomername>@<customer_domain.com> # recommended convention

    Console Shortcut: https://<youraccountname>-<yourcustomername>.signin.aws.amazon.com/console

STEP 5 - PERFORM MINIMAL CONFIGURATION IN NEW AWS ACCOUNT

Using the AWS Console, perform the following minimal steps within your AWS Account

  1. Create a new IAM User in the new AWS Account. Name the user: NucleatorUser

    Note: This user is used as a Prinicipal in trust policies estabished by Nucleator. It needs to be spelled correctly for the role provisioning process described later to succeed.

  2. During the creation of the user, generate an Access Key for the user and be sure to download this creditional before closing the "successful completion" screen. Retain the downloaded IAM Credentials for NucleatorUser. You will need to use these during the configuration process for Nucleator later. You will not be able to reaccess this Access Key information later.

  3. Create a new group called NucleatorBootstrapGroup.

  4. Add a User Policy to NucleatorBootstrapGroup by expanding the "Inline Policies" section of the group description screen. Select a custom policy and copy and paste the policy listed below; name the policy NucleatorGroupPolicy and apply it. 

        {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "NucleatorUserMinimalAccess",
                "Effect": "Allow",
                "Action": [
                    "iam:CreateRole",
                    "iam:DeleteRolePolicy",
                    "iam:GetRole",
                    "iam:GetRolePolicy",
                    "iam:ListRolePolicies",
                    "iam:PutRolePolicy",
                    "iam:UpdateAssumeRolePolicy",
                    "ec2:DescribeRegions",
                    "ec2:DescribeAvailabilityZones"
                ],
                "Resource": "*"
            }
        ]
    }
d. Add NucleatorUser to NucleatorBootstrapGroup by clicking the Add Users to Group button from the group description screen. Select NucleatorUser and click Add Users.

STEP 6 - CREATE INITIAL CONFIG FOR CUSTOMER, ACCOUNT AND CAGE

You can either perform this step manually or use the Nucleator Setup Wizard.

We recommend starting with the wizard, as it produces files that will help you to understand the structure of the config files described below.

To use the wizard

  1. In your local clone of your personal fork of nucleator-core-siteconfig, navigate to directory ansible/roles/siteconfig/vars/.

  2. invoke the wizard: 

    nucleator setup wizard

To perform steps manually

  1. In your local clone of your personal fork of nucleator-core-siteconfig, navigate to directory ansible/roles/siteconfig/vars/, and copy the {customer}.yml customer configuration templates to a customer configuration file based on your customer name. For example, if your customer name is quickstart, then the customer configuration file would be named quickstart.yml

  2. Open the file and make the following changes:

    • Set the customer domain to the desired DNS subdomain that you’d like to use for this customer. For example nucle8r.io, or somedepartment.mycompany.com

    • Inside the Cage names section, set the friendly account name, region, and owner of each Cage. Note: There must be one Cage named build to work as a starting point for Nucleator

    • Inside the aws_accounts section, set the Account number and Region for each account associated with the customer

    • Nucleator can work with multiple AWS Accounts for each Customer. These are specified in aws_accounts in the customer config. Each specified AWS Account includes the following fields

      • Friendly account_name - this is a name for the Account that is readable by humans. It is used elsewhere in Nucleator config and in Jenkins pulldowns that are set up by Nucleator, where choices among AWS Accounts must occur

      • account_number - this is the unique twelve-digit Account number provided by AWS for this AWS Account. The account number can be found by selecting the "Support" | "Support Center" pulldown from your AWS console. Your Account number will appear at the upper right of the Support Center page

      • bootstrap_region - this is the AWS Region where Nucleator will create Amazon resources within this Account that it needs to support the creation of Cages and Stacksets

    • map_region_plus_redundant_zone_number_to_vpc_valid_az - Region to Availability Zone Mapping that specifies which AZ’s are valid for provisioning VPC subnets within the Account. This can be set by going to the AWS console → VPCs → Subnets → Create Subnet → and grabbing the first two list items of the Availability Zone dropdown. Note: Will need to change the Region in the top right of the AWS console to grab the Availability Zones for the different Regions

  3. Copy the {customer}-{cage}.yml file for each Cage specified in your customer configuration file. For example, when done there should be a file for each Cage named something like mycustomer-build.yml

  4. In your ~/.nucleator directory, copy the {customer}-credentials.yml to use your Customer name

  5. Open the file and fill in the aws_access_key_id and aws_secret_access_key for each account in the specified customer. These values are the saved values that were presented when NucleatorUser was created

NOTE

On Accounts that pre-date AWS' introduction of VPCs it is possible that the setup wizard may choose availability zones (AZ) in the <customer>.yml siteconfig file that are not VPC-capable. If this occurs Nucleator cage provision will fail. Please reference the Troubleshooting Tips for more details on this issue and how to address it.

STEP 7 - GENERATE AND PROVIDE CAGE-SPECIFIC SELF-SIGNED SSL CERTIFICATES

  1. decide on a password to use to protect the private keys and certificates that you will generate in the steps below. Enter this password as the value for the pkcs12_bundle_password key in your customer credentials file at ~/.nucleator/<customer>-credentials.yml

  2. In your local clone of your personal fork of nucleator-core-siteconfig, navigate to directory ansible/roles/siteconfig/vars/.

  3. Run the following command by filling in the variables: 

    ./make-certificate-bundle <customer_name> <cage_name> <customer_domain> <pkcs12_bundle_password>

  4. Repeat for all cages. Use the customer_name, customer_domain and each cage_name that you specified during STEP 6. Use the pkcs12_bundle_password that you specified in STEP 7.a.

STEP 8 - COMMIT YOUR SITECONFIG UPDATES

Whenever siteconfig files are generated and/or updated, you must commit them to your github repository so that Nucleator will be able to use them. While still in you local clone you can review the config file changes that the wizard has made, or that you have manually made:

git status
git diff

Add, commit and push your updated configuration:

git add --all :/
git commit -m "updated config with customer <a>, account <b> and cage <c>"
git push

STEP 9 - NUCLEATOR UPDATE

Do this:

nucleator update

Nucleator update pulls current copies of all Stacksets that you have chosen to be part of your Nucleator installation. You should run nucleator update whenever:

  • you add Stacksets to your selected sources

  • you change the version of a Stackset you are using

  • you modify a Stackset without changing the Stackset version, and you want Nucleator to see those changes

STEP 10 - PROVISION NUCLEATOR ROLES IN YOUR ACCOUNT

Nucleator needs to establish some attributes in your account like iam roles in order to execute correctly. To do this run:

    nucleator account rolespec provision --customer <yourcustomername> --account <youraccountname>

    # to ensure all the roles were created successfully
    nucleator account rolespec validate --customer <yourcustomername> --account <youraccountname>

STEP 11 - ACCOUNT SETUP

Next Nucleator needs to set up specific account resources for proper operation such as creating s3 buckets. To do this run:

PYTHONUNBUFFERED=1 nucleator account setup --customer <yourcustomername> --account <youraccountname> | tee /tmp/account_setup.out

STEP 12 - DNS SETUP

More detailed instructions on DNS set-up are in the User’s Guide section entitled Prepare AWS Account - Set Up DNS for Cages Defined within your Account You will need an externally resolvable Subdomain to which you have authority to add Nameserver records.

For each Cage that you have defined for your Customer:

  1. In the AWS console go to Route53 → Hosted Zones and select the hosted zone created by account setup for the current Cage. "Go to Record Sets".

  2. Copy the Name Servers of the Hosted Zone by selecting its single NS record, and selecting and copying the four nameservers from the pane on the right.

  3. Go to the system that you use to maintain authoritative NS records for the customer_domain that you specified during step 6.

    • Add a single NS record with the name of the current Cage and a value that specifies the four nameservers copied above.

      For example, for customer_domain somedepartment.mycompany.com and Cage build, you will create an NS record build.somedepartment.mycompany.com with a value that specifies the four nameservers copied above.

  4. Verify that the DNS updates have propagated 

    dig +short NS build.somedepartment.mycompany.com

STEP 13 - PROVISION AND CONFIGURE CAGE

You can now provision and configure your first Nucleator Cage:

PYTHONUNBUFFERED=1 nucleator cage provision --customer <yourcustomername> --cage build | tee /tmp/cage_provision.out
PYTHONUNBUFFERED=1 nucleator cage configure --customer <yourcustomername> --cage build | tee /tmp/cage_configure.out

Note that it can take a few minutes for cage resources to be provisioned and become available. You can use the CloudFormation AWS console to see the current status and progress of provisioning while these commands are running.

STEP 14 - CREATE A BUILDER STACKSET

Nucleator supports several Stacksets that can be created within a cage. The Builder Stackset provides a user interface for creating additional Stacksets. To do this run:

PYTHONUNBUFFERED=1 nucleator builder provision --customer <yourcustomername> --cage build | tee /tmp/builder_provision.out
PYTHONUNBUFFERED=1 nucleator builder configure --customer <yourcustomername> --cage build | tee /tmp/builder_configure.out

Note that it can take some time for builder resources to be provisioned and become available. You can use the CloudFormation AWS console to see the current status and progress of provisioning while these commands are running.

Once complete the Nucleator user interface can be accessed at https://nucleator-ui.<cage>.<customer_domain>. Initial login credentials are available in ~/.nucleator/<customer>-credential.yml.

SUMMARY

You should now have a configured Cage and Builder Stackset. To provision other Stacksets such as Beanstalk or Redshift, see the documentation for those specific commands. You can also re-run step 12 with any Cage that has been configured in step 6 to provision more Cages.

SEE ALSO

The Nucleator User’s Guide, Nucleator Glossary

NUCLEATOR

Part of the nucleator(1) suite

Installation Documentation Releases License Community