Configuration file best practices
Landing Zone Accelerator on AWS aims to abstract away most aspects of managing its underlying infrastructure as code (IaC) templates from the user. This is facilitated through the use of its configuration files to define your landing zone environment. However, it is important to keep some common IaC best practices in mind when modifying your configuration to avoid pipeline failure scenarios.
Manage accelerator resources strictly through configuration
Introducing manual, out-of-band changes to accelerator-managed resources in your environment can cause unexpected pipeline failures or resource updates to occur when you release updates using your Core pipeline. CDK and CloudFormation don’t keep a record of these out-of-band changes, which leads to drift between the solution-generated template and actual resource configuration state. For this reason, we recommend managing changes to your landing zone resources strictly through the solution configuration files. For features and configurations that aren’t supported by the solution, we recommend using custom stacks in the customizations-config.yaml file or externally-managed IaC to manage those updates.
Understanding the name property
Several configuration objects throughout the solution configuration files make use of the name property. This property has two important uses:
-
It allows you to logically name and reference a configuration item in other configuration items. This allows you to easily build relationships between separate configuration items if there are dependencies between them.
-
It is used to generate unique logical IDs for resources in the solution CDK application when it is synthesizing the underlying CloudFormation templates.
Important
Use caution when modifying the
nameproperty of any configuration item. In doing so, any other configuration items that reference thatnamevalue must also be updated. Additionally, changing anameproperty value is treated as a resource replacement operation when the Core pipeline runs. Assess downstream dependencies before performing this action.
Managing resource create, update, and delete actions
This solution’s resource orchestration follows the same create, update, and delete workflow as standard CloudFormation templates. These actions are defined in How does AWS CloudFormation work? in the AWS CloudFormation User Guide. This section provides specifics related to translating these behaviors to accelerator configuration file modifications.
Adding a net new configuration block to an accelerator configuration file causes a new resource to be created in the defined AWS Regions and target accounts or OUs. For the configuration items that use the
deploymentTargets property, your configured resources will be automatically replicated to every Region configured under the
enabledRegions property of the global-config.yaml file. You can explicitly remove target accounts and Regions for deploymentTargets by using the excludedAccounts and excludedRegions properties, respectively.
If you modify or remove a property value of an existing configuration item, an update of the previously deployed resource will occur. Specific update behaviors and constraints are dependent on the underlying resource that is being updated. Before you make updates, we recommend reviewing the configuration reference in the Services, Features, and Configuration References section
Removing a configuration block from your configuration results in resource deletion. Please be aware that removing a configuration block prior to removing a resource’s downstream dependencies may result in a dependency error during resource deletion.
Downstream resource dependencies
This solution uses a stack layering strategy for building your landing zone environment. This means that resources provisioned in later stages of the Core pipeline might depend on resources created in earlier stages. When updating the solution configuration files, consider downstream resource dependencies. For additional information about strategizing your resource updates, see Managing resource dependencies.
Existing resources in your environment
If you want to migrate an existing landing zone to use Landing Zone Accelerator on AWS, you might have conflicts between your existing resources and your configured resources in the solution configuration files. See the details in Working with existing landing zones for more information.
