Include Additional Customers, Accounts and Cages in your siteconfig

Extend your siteconfig

Customer-specific configurations are maintained in ~/.nucleator/siteconfig/

~/.nucleator/siteconfig/
    <customer_name>.yml # nucleator customer config for customer <customer_name>
	{customer}.yml # Customer configuration template 

Specify Customer Domain and AWS Accounts for this Customer

To configure Nucleator to work with a new Customer, copy and modify the {customer}.yml template file to include Customer- and Account-specific information.  Name the config file  {{customer_name}}.yml where customer_name is the name that you would like Nucleator to use for this customer.

If a customer config already exists for this Customer, just add the Account-specific information for the new Account to the customer's existing {{customer_name}}.yml config file.

Within the Customer configuration template, each part of the config where Customer- or Account-specific information needs to be entered is marked with a "TODO" comment that describes the required information, for example:

customer_domain: "somedomain.com" # TODO update domain name


aws_accounts:

  # TODO: add an account specification block for each new AWS Account for this customer
  test1: # TODO: update the human-readable "Friendly Name" of this Account.

    account_number: 123456789012 # TODO: enter Account Number for this AWS Account

You can review a completed sample for an example customer at ~/.nucleator/siteconfig/example.yml

When you create a new AWS Account that you want Nucleator to be able to use, you must tell Nucleator about some essential Account information.  

aws_accounts:
  
# TODO: add an account specification block for each AWS Account for this customer
  test1: # TODO: update the human-readable "Friendly Name" of this Account.


    account_number: 123456789012 # TODO: enter Account Number for this AWS Account

    bootstrap_region: us-west-2 # TODO: select region to use for Account-level
                                #       resources supporting best practices
                                #       (e.g. detailed billing)
 
    map_region_plus_redundant_zone_number_to_vpc_valid_az:
      # TODO: update AZ1 and AZ2 for each region to match the first two AZ's
      # capable of hosting VPC subnets in the new account.  This allows
      # Nucleator to create redundant subnets and subnet groups for
      # high-availability deployment topologies.  Note that the specific AZ's
      # available for use within VPCs may vary by Account and Region, especially
      # for Regions where AWS has a strong pre-VPC footprint like us-east-1.
      # Do not assume that the available AZs will be the same as for previous
      # Accounts.
      us-west-2:
        AZ1: us-west-2a
        AZ2: us-west-2b
      us-east-1:
        AZ1: us-east-1a
        AZ2: us-east-1c
      eu-west-1:
        AZ1: eu-west-1a
        AZ2: eu-west-1b 

The Region to AZ mapping is a mapping ("map_region_plus_redundant_zone_number_to_vpc_valid_az") that specifies which AZ's are valid for provisioning VPC subnets within the Account.  This information varies from Account to Account, so you need to add this info for each new AWS Account that you create.  The AZ's which are valid for provisioning VPC subnets can be determined by:

• selecting each AWS Region supported by Nucleator from the AWS Management Console in turn (Region pulldown in top nav bar, select each of "US East (N. Virginia)", "US West (Oregon)" and "EU(Ireland)". 
• Then take note of the first two subnets that are offered for VPC subnet creation (VPC Service → Subnets → Create Subnet → Availability Zone pulldown)
• Enter the noted subnets into the mapping for the corresponding AWS Region within this AWS Account's specification in the customer config.

Specify Cages for this Customer and map each to an AWS Account and Region

The Customer configuration template is pre-configured with a useful sample of Cage names that Nucleator is aware of for this Customer.  You can update the defined Cage names to suit this Customer's specific needs.  Nucleator uses these to create a an AWS Hosted Zone for each cage as part of the automated account setup process, providing a means for consistent internal- or external DNS resolution for resources provisioned within each Cage.  Nucleator will refuse to provision a Cage until you add it here.  You can always extend the list to define additional Cages later.

In the Customer configuration template, each Cage is mapped to a specified AWS Account and AWS Region where you would like this Cage to reside when it is provisioned by Nucleator.  Nucleator currently ubiquitously supports regions where AWS supports CloudWatch logging, currently us-east-1 (Northern VA), us-west-2 (Oregon) and eu-west-1 (Ireland).  For each of these Regions, Nucleator is aware of current values for useful AMIs and other needed values that vary on a per-region basis.

The owner values provided for each Cage are propagated by Nucleator and applied to an "Owner" tag that is applied to AWS Resources provisioned within each Cage.

Adjust these values and the set of Cage names based on the Customer's requirements: 

# A Cage is a set of managed AWS infrastructure that exists for a particular purpose.
# Cages can be maintained across one or more customer-specific AWS Accounts.

# TODO: modify cage names for this customer.  Consider starting with just build.
cage_names:

  # The AWS Acccount that hosts the build cage acts
  # as the source account in cross-account builds
  build:
    account: test1
    region: us-west-2
	owner: exampleUser
  ci:
    account: test1
    region: us-west-2
	owner: exampleUser
  stage:
    account: test2
    region: us-west-2
	owner: exampleRole
  prod:
    account: test2
    region: us-west-2
	owner: exampleRole

Specify Configuration Parameters for each of this Customer's Cages

For each Cage defined in the Customer configuration file, you will need to copy and update the {customer}-{cage}.yml file, also in the siteconfig directory.  These files provide configuration details for each Cage.  In each of the new files, you will need to update the values for these fields:

network_toplogy:
first8: 172
second8: 32

These variables define the IP address space used by the AWS VPC within this Cage.  Typically each Cage will consume address space within those ranges specified by RFC 1918 - Address Allocation for Private Internets.

To make things simple, the network_topology relies on two convenience variables:

• • first8 – Specifies the value for the first eight bits of the CIDR for the VPC that will be provisioned for this cage.  The value specified in the default Cage configuration is 172.  If you use the 10.* address space for your networks, you can make that update here.
  • second8 – Specifies the value for the second eight bits of the CIDR for the VPC that will be provisioned for this cage.  The value specified in the default Cage configuration is 32, so as to not conflict with the default AWS VPC and allow for easy incrementing to accomodate additional Cages.

You should update these values so that the IP Address of each of your cages in non-overlapping.  This will allow each of the provisioned VPC's to be consolidated into a single address space via VPN, if needed in the future.  In most cases simply incrementing the value specified for second8 for each Cage that you add is sufficient.

Nucleator Cages default to allocating a /16 CIDR, i.e. 172.32.*.*, 172.33.*.* etc.

Enter Customer -Specific Account Credentials

Customer credentials are maintained in ~/.nucleator/ in files named {customer}-credentials.yml, for example:

~/.nucleator/
    47lining-credentials.yml
    othercustomer-credentials.yml 

The nucleator init command creates a template for a new customer in {customer}-credentials.yml in the above directory.

Nucleator supports the use of multiple AWS Accounts per customer, and provides convenience facilities to help you to set up each of these accounts.  The customer credentials file enables you to provide Nucleator with IAM credentials for each account used by a customer.  Nucleator uses these credentials to provision IAM Roles within the Account (see below), after which the credentials are no longer required.  IAM User credentials should not be maintained in git, this is why customer credentials are provided in a distinct file in ~/.nucleator, rather than in the siteconfig.

Create a customer credentials file for your first Nucleator customer by copying the template, and modify that file to include the account-specific information for each account the customer has.  Name the config file  {{customer_name}}-credentials.yml where customer_name is the name that you would like Nucleator to use for this customer.  There should be access and secret keys for each Account named in the configuration step above:

aws_account_access_keys:
 
  test1: # TODO - provide credentials for each AWS Account for which you would like Nucleator to assist with account setup
 
    aws_access_key_id: <provide IAM User credentials: access key ID>
    aws_secret_access_key: <provide IAM User credentials: secret access key>

Note: the credentials above are not valid.  You need to replace them with values from your own Account.

Summary

Here's a summary of the Customer- and Account-specific information that Nucleator needs to be in place:

Next: Provide SSL Certificates for Your Defined Customers and Cages