Using the CloudFormation Console with Nucleator

The CloudFormation Console provides a wealth of useful information about the status and outcomes of Nucleator commands that can be helpful in tracking progress as well as in troubleshooting.

Using the CloudFormation Console to Track Progress of Nucleator Commands

Most Nucleator Stacksets execute one or more CloudFormation templates, which result in the creation of one or more CloudFormation stacks in AWS. The AWS CloudFormation Web console can be helpful in understanding what resources a Stackset is provisioning, the current progress / status of those resources and troubleshooting in the event that Stackset provisioning fails.

To view the AWS CloudFormation console, log onto your AWS account, click the cube icon in the upper left and then click on the "CloudFormation" link on the resulting page.

CloudFormation stacks created via Nucleator are given unique names that include the Nucleator Stackset name, Cage name and customer name to provide for easy identification in the CloudFormation console. To see the status of any given CloudFormation stack, click on the stack in the listing at the top of the console and click the "Overview" tab at the bottom of the screen. For successfully provisioned stacks, you should see a status of "CREATE_COMPLETE" or "UPDATE_COMPLETE". For stacks in the process of being provisioned, you will see "CREATE_IN_PROGRESS".

Stacks that fail to be provisioned properly will have a status of "CREATE_FAILED". To find more information on the cause of the failure, click on the "Events" tab at the bottom of the console. The Events tab will provide a detailed list of the resources CloudFormation tried to create as a part of the stack, with individual status and messaging for each resource. If a stack failed to be provisioned properly, one or more of the resources outlined in the Events tab will have a status of "CREATE_FAILED" and an associated error message that may be helpful in understanding the failure.

CloudFormation stack provisioning failures can have many causes, but the following are the most common failure modes and steps for remediation:

Insufficient permissions - Nucleator assumes a specific IAM Role before it runs CloudFormation templates. The particular IAM Role that is assumed depends on the specific Stackset. Nucleator roles and permissions are defined in the role-specification.yml file included with a given Stackset. The nucleator-core-beanstalk Stackset, for example, defines a BeanstalkProvisioner IAM role that specifies the minimum set of AWS permissions required to provision a new Elastic Beanstalk instance. If you see "insufficient permissions" errors in your CloudFormation Event tab, chances are that the IAM Role that is being used to run the CloudFormation stack is missing one or more required AWS permissions. Missing permissions can be added to the relevant role specification in the role-specification.yml of the Stackset in question. You should run "nucleator account rolespec provision" after making any changes to role-specification.yml files to ensure that permission changes are propagated to AWS.

Service or resource limits - Amazon Web Services defines per-account limits for many types of resources. For example a single account may have only a certain number of Elastic IPs, VPCs, S3 buckets, etc. If a CloudFormation stack tries to provision an AWS resource that would put the account over its limit for that type of resource, that resource will appear in the CloudFormation Events tab with a "CREATE_FAILED" status and a message indicating which resource limit prevented the resource from being created. You can use the AWS Support Center in your AWS account console to request a service limit increase for most services and resource types if you hit this type of error.