Working with Deployments
StackOps deployments are a collection of AWS Stacks that are managed together. Stacks may be distributed across multiple accounts and regions.
Infrastructure code files for a StackOps deployment include:
- One deployment file in either Yaml or Json,
- At least one AWS CloudFormation template file, and
- Optional AWS CloudFormation parameter files, all stored on the same Git branch.
Example of a Simple Deployment File
A simple deployment with one Stack could be:
NginStackOpsDeploymentFormatVersion: '2022-09-07'
Description: A simple deployment with a single stack.
AccountAccessRoleArns:
- [ main, arn:aws:iam::123456789012:role/iac-mgt ]
Stacks:
- [ ap-southeast-2, example-stack, templates\sysparam.yaml]
Anatomy of a Deployment
A StackOps deployment file has ten keys as specified below.
StackOps Deployment File Key | Description |
---|---|
NginStackOpsDeploymentFormatVersion | Mandatory, string, must always be '2022-09-07', for format identification |
AccountAccessRoleArns | Mandatory, array of 2 or 3 string arrays: branch, account alias (optional), IAM role |
Stacks | Mandatory, array of 3 - 8 string arrays |
ParameterValues | Optional, array of 4 - 8 string arrays |
Description | Optional, string |
LinkOutputsToParameters | Optional, true or false, for automated dependencies |
AutomaticInjection | Optional, true or false, for injecting run time deployment parameters |
AutomaticallyExecuteChangeSets | Optional, comma separated strings of branch names |
PauseBeforeDependents | Optional, true or false, pause before executing ChangeSets that have dependencies |
CommenceDeployAtUtc | Optional, string, for scheduled deployments |
The AccountAccessRoleArns, Stacks, and ParameterValues keys are all arrays of arrays. Nesting arrays within arrays allows for easy copying of lines and aligning values vertically, facilitating readability and comparison. This structure is particularly helpful when working with multiple accounts and stacks, as it makes it easy to spot differences between them (see the full example below).
AccountAccessRoleArns
Required: An array of two or three comma separated strings that specify IAM roles to be assumed for CloudFormation operations during deployment:
- Branch Name: Specifies the Git branch that this RoleArn will be used for. Watch this part of the overview video for further explanation.
- RoleArn: The IAM RoleArn that will be assumed by the logged-in user's temporary credentials to execute CloudFormation operations (e.g., CreateChangeSet, ExecuteChangeSet).
An example of this key is:
AccountAccessRoleArns:
# Branch AWS RoleArn for access
- [dev, arn:aws:iam::123456789012:role/iac-mgt]
- [prod, arn:aws:iam::223456789012:role/iac-mgt]
Each RoleArn must be unique. Use one role for each AWS Account in the deployment.
Where do all the roles come from?
For StackOps installations that allow login by Principals from the master account
(ie an "Enterprise Installation" of StackOps), the OrganizationAccountAccessRole
role can be used which
is automatically created by AWS Organizations. The "Enterprise Installation" can then be used to create additional
StackOps installations along with the roles needed for deployment.
See Additional Installations for more information.
Stacks
Required: An array of 4 - 8 string arrays that specify deployment Stacks:
- Region: AWS Region for the Stack
- Name: AWS Stack name
- Template: Path of the CloudFormation template file
- Parameters: Optional path of the CloudFormation parameter file
An example of the Stacks key is:
Stacks:
# AWS Region Stack Name Template path Parameter file path
- [ ap-southeast-2, app-logging, lib/logging.yaml, ]
- [ ap-southeast-2, app-db, lib/dynamodb.yaml, ddb-params.yaml, ]
- [ ap-southeast-2, app-lmbda, lmbda-and-apigw.yaml, lmbda-apigw-params.yml ]
- [ eu-west-2, app-lmbda, lmbda-and-apigw.yaml, lmbda-apigw-params.yml ]
- [ us-west-1, app-lmbda, lmbda-and-apigw.yaml, lmbda-apigw-params.yml ]
ParameterValues
Optional: An array of 4 or 3 string arrays that specify deployment parameters. There are two line formats.
Dependency Line Format - 4 Strings : specifies a dependency between an output of a stack and a parameter of another stack:
- Stack with Dependent Parameter: String containing
stackname
if unique, or a string of the formatregion:stackname
- Dependent Parameter Key: String containing the key of the dependent parameter
- Stack with Output: String as per
1.
above - Output Key: String containing the key of the output
Dependencies don't have to be specified when Output Keys and Parameter Keys have the same name. Use
LinkOutputsToParameters
to enable automatic dependency resolution as detailed here.
Injected Parameter Line Format - 3 Strings : specifies a stack parameter that has its value injected when creating the ChangeSet:
- Stack with Parameter for Injection: String containing
stackname
, or a string of the formatregion:stackname
- Parameter Key for Injection: String containing the key of the parameter to have its value injected
- Injection: String literal indicating what to inject - valid values are:
ChangSetTimeString
DeploymentBranch
S3BucketWithTemplateFiles
DeploymentUUID
Parameter values specified here take precedence over template defaults and parameter file settings.
An example of this key is:
ParameterValues:
# Stack Parameter Key gets value from -> Stack Output Key
- [ app-lmbda, ddb-access-role, app-db, access-role ]
- [ app-lmbda, ddb-arn, app-db, arn ]
- [ ap-southeast-2:app-db, cw-log-grp, ap-southeast-2:app-logging, arn ]
# Stack Parameter Key gets a StackOps -> injected value when AWS ChangeSet is created
- [ app-lmbda, chg-set-utc, ChangSetTimeString ]
- [ app-logging, dep-id, DeploymentUUID ]
- [ app-lmbda, template-bucket, S3BucketWithTemplateFiles ]
Description
Optional: String to describe the deployment.
LinkOutputsToParameters
Optional: Boolean value to enable or disable automatic dependency resolution for Stacks with un-resolved parameters.
Automated dependency resolution only occurs for parameters that don't have a value set by:
- injection in the deployment file, or
- parameter file value, or
- template file default value.
Stack parameters without a value automatically resolve to the value of an output in another stack where parameter key equals output key.
When there are multiple stacks with the same output key matching a dependent parameter key, precedence is:
- firstly to a stack within the same region,
- secondly to a stack within the same account, and
- lastly to a stack within the deployment.
When there is no unique match between parameter and output, an error message is provided.
AutomaticInjection
Optional: Boolean value to enable or disable automatic parameter value injection for Stacks with parameter keys of:
ChangSetTimeString
DeploymentBranch
S3BucketWithTemplateFiles
DeploymentUUID
Parameter values are injected when the ChangeSet is created.
AutomaticallyExecuteChangeSets
Optional: String of comma separated branch names. Commits made to specified branches have ChangeSets executed automatically after they have been created.
PauseBeforeDependents
Optional: Boolean value determines whether deployment is paused before executing Stacks that have dependencies. Pausing allows for inspection of resolved values before proceeding with the deployment.
Complete Deployment File Sample
NginStackOpsDeploymentFormatVersion: '2022-09-07'
Description: Description of the deployment
AccountAccessRoleArns:
# Branch AWS RoleArn for access
- [dev, arn:aws:iam::123456789012:role/OrganizationAccountAccessRole] # 'dev' deployment of 3 AWS Stacks specified below
- [prod, arn:aws:iam::123456789014:role/OrganizationAccountAccessRole] # 'prod' deployment of 3 AWS Stacks specified below
Stacks:
# AWS Region Stack Name Template path Parameter file path
- [ap-southeast-2, app-db, lib/dynamodb.yaml, ddb-params.yaml ] # alignment spacing is ignored
- [ap-southeast-2, app-lmbda, lmbda-and-apigw.yaml, lmbda-apigw-params.yml ]
- [ap-southeast-2, app-logging, lib/logging.yaml ] # no parameter file, template defaults are used
#
LinkOutputsToParameters: true # optional, create dependencies between Stacks by linking Parameter Keys to Output Keys of the same name
PauseBeforeDependents: true # optional, Pause before executing ChangeSets that have dependencies
AutomaticallyExecuteChangeSets: 'dev' # optional, automatically execute change sets after they have been created for branch names (csv)
AutomaticInjection: true # optional, inject values in deployment templates for ChangSetTimeString, DeploymentBranch, DeploymentUUID and S3BucketWithTemplateFiles parameter keys