Skip to main content

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 KeyDescription
NginStackOpsDeploymentFormatVersionMandatory, string, must always be '2022-09-07', for format identification
AccountAccessRoleArnsMandatory, array of 2 or 3 string arrays: branch, account alias (optional), IAM role
StacksMandatory, array of 3 - 8 string arrays
ParameterValuesOptional, array of 4 - 8 string arrays
DescriptionOptional, string
LinkOutputsToParametersOptional, true or false, for automated dependencies
AutomaticInjectionOptional, true or false, for injecting run time deployment parameters
AutomaticallyExecuteChangeSetsOptional, comma separated strings of branch names
PauseBeforeDependentsOptional, true or false, pause before executing ChangeSets that have dependencies
CommenceDeployAtUtcOptional, string, for scheduled deployments
tip

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:

  1. Branch Name: Specifies the Git branch that this RoleArn will be used for. Watch this part of the overview video for further explanation.
  2. 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]
info

Each RoleArn must be unique. Use one role for each AWS Account in the deployment.

tip

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:

  1. Region: AWS Region for the Stack
  2. Name: AWS Stack name
  3. Template: Path of the CloudFormation template file
  4. 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:

  1. Stack with Dependent Parameter: String containing stackname if unique, or a string of the format region:stackname
  2. Dependent Parameter Key: String containing the key of the dependent parameter
  3. Stack with Output: String as per 1. above
  4. Output Key: String containing the key of the output
info

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:

  1. Stack with Parameter for Injection: String containing stackname, or a string of the format region:stackname
  2. Parameter Key for Injection: String containing the key of the parameter to have its value injected
  3. Injection: String literal indicating what to inject - valid values are:
  • ChangSetTimeString
  • DeploymentBranch
  • S3BucketWithTemplateFiles
  • DeploymentUUID
info

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