Prepare AWS Account - Use Nucleator to Automatically Create Prerequisite AWS Resources in Account

Ask Nucleator to prepare your AWS Account consistent with best practices and create resources needed to manage Cages and Stacksets.

When a new AWS Account is created, only the minimum IAM configuration is manually created, so that Nucleator can take the initial actions required to provision Nucleator IAM Roles within the Account.

Now that Nucleator Roles are in place, you can request that Nucleator setup your Account so that several account-level best-practice AWS services are enabled and so that account-level AWS resources that will be required by Nucleator Cages and Stacksets are in place for their use. Establishing these resources once, at the Account level, simplifies the downstream use and operations of Cages and Stacksets.

Setup your AWS Account

Icon

After you have provisioned Nucleator Roles within your AWS Account:

nucleator account setup --account <account_friendly_name> --customer <customer_name>

Even if you are only working with a single AWS Account, Nucleator assumes the Nucleator Roles that have been provisioned within your account, obtaining temporary security credentials that are required to operate within your Account. The NucleatorUser IAM user that was manually created is trusted to initiate assumption of the required Nucleator Roles so that you can continue to work locally to create the required initial Cages and Stacksets. Later, you will set up Nucleator to run within AWS using an IAM Instance Profile that allows it to assume the required Nucleator Roles.

nucleator account setup takes the following actions within your Account:

account-setup Cloudformation Stack. Nucleator launches a CloudFormation template that is dynamically generated to create the remainder of the AWS resources described in this list. The CloudFormation template is named account-setup-<account_name>>-<<customer_name>>. You can inspect the "resources" tab of the the resulting CloudFormation stack to see exactly which resources resulted from account setup.
Nucleator Template S3 Bucket and Hosted Zones for each defined Cage. Nucleator create additional prerequisite resources within the AWS Account that need to be in place for downstream operations of Nucleator Cages and Stacksets. These include:
1. An S3 Bucket where Nucleator's CloudFormation templates will be placed. One such Bucket is created per AWS Account, in the region that you have specified for bootstrap_region for the specified Account in the customer configuration file for the Customer that you have specified (us-west-2 by default). The template bucket is named nucleator-{{account_name}}-{{customer_domain}}-{{hash}}. If customer_domain has any dots, they are replaced by hyphens. For example: Nucleator-test1-47lining.com-ow76xk becomes Nucleator-test1-47lining-com-ow76xk
2. A Route53 Hosted Zone corresponding to each of the Cages that will reside within the Account. The Cage definitions are drawn from the customer configuration file for the Customer that you have specified. Each Cage, when created, will use its corresponding Hosted Zone for DNS resolution through the top-level customer_domain specified in the same customer configuration file.
Cloudtrail. Nucleator creates an S3 bucket with the required policy, and enables Cloudtrail in the Region specified as the bootstrap_region for this Account within your Nucleator configuration.
Detailed Billing. Nucleator creates an S3 bucket with the required policy to support detailed billing. After this is done, you will still need to log into your Account using root account credentials, enable detailed billing within the account and select the Nucleator Tag keys to be included in detailed billing reports.

Advanced Topic: <account_name>-<customer_domain> unique hashes

Icon

To allow deletion and recreation of the account-setup Cloudformation stack without waiting for the eventual consistency latency associated with deleting an S3 bucket and waiting for that bucket to become available again, Nucleator adds a unique (with high probability) hash to the names of S3 bucket resources within the Cloudformation stack. The unique name is determined upon the first invocation of nucleator account setup, and is stored in ~/.nucleator/nucleator-<account_name>-<customer_domain> (with any dots in customer_domain replaced by hyphens). If this file exists, its contents including the unique hash are used as the suffix for all S3 buckets created within the Cloudformation Stack.

During normal Nucleator operations, you should not remove or alter the contents of this unique hash file. Doing so will lead to regeneration of a different unique hash, and an attempt to update the bucket names within the resulting Cloudformation stack.

Should you ever need to completely delete all Nucleator resources within your Account, then wish to re-initiate the account setup process, you should remove the unique hash file for the desired Account and Customer from your ~/.nucleator directory. This is common when testing Nucleator functionality. Failure to remove the unique hash file across deletion and re-provisioning of the account-setup Cloudformation stack will result in an attempt to recreate S3 buckets with the same names. This can often fail because the bucket names are not yet available for re-use.

Next: Prepare AWS Account - Set Up DNS for Cages Defined Within Your Account