Naming Conventions for AWS CDK Resources

Decision

We adopt the following conventions for AWS CDK resource names:

Resource ID:

We aim to modularize not only our application code but also the infrastructure code. We use custom AWS CDK constructs within a stack to organize our infrastructure into (sub)domains, e.g.: "SendSupplierFiles" and "Suppliers" custom constructs where "SendSupplierFiles" consists of the resources to send campaign files to the printers and "Suppliers" contains the resources for the /suppliers CRUD API.

AWS automatically prefixes the actual resource IDs with the parent ID so that resources can be identified easily when following this convention.

Typically, we use the resource type as the ID; for example, 'Queue' for an AWS Queue. However, if you have two or more resources of the same type, please provide a specific use case as the ID for each resource.

Resource naming:

Resource names must begin with a letter, consist only of ASCII letters, digits, and hyphens, and must not end with a hyphen or contain two consecutive hyphens.

We don't give a name to a resource unless it's required by AWS CDK constructs. However, for certain resources, such as RestApi (API Gateway) we need to provide a name.

If name is required, our goal is to ensure that resource names are clear, easily readable, and searchable in the AWS console. For example, to name an API Gateway for the SendSupplier stack in the production environment (stage), follow this format: {Stack}{Stage}{Resource} -> SendSupplierProductionAPI.

For more detailed information on specific resource naming policies, please refer to the AWS documentation.

Problems

Multiple teams are working on various parts of our infrastructure, creating resources.

We must avoid conflicts, such as resources sharing the same name but serving different purposes. For example, an API Gateway could be named 'API-Production' for different teams. Otherwise, one team might inadvertently delete another team's resources. Therefore, it should be easy to identify and locate the correct resources.

Since AWS lacks an official naming convention, it's our responsibility to establish a clear strategy. This can be achieved by implementing a fixed convention for the stage and stack IDs.

Context

AWS resource names must be unique across all active stacks. If a name isn't specified, AWS CDK (CloudFormation) generates a unique physical ID to name the resource. For example, CloudFormation might name an Amazon S3 bucket with the following physical ID: stack123123123123-s3bucket-abcdefghijk1.

But for the resources like restApi and others, We currently follow multiple different approaches across the different projects to name AWS CDK resources. Without clearly defined guidelines, maintaining consistency in resource names poses a challenge.

This absence of standardization could result in resources sharing identical names but serving different purposes, potentially leading to one team unintentionally deleting resources owned by another team.

Options

The following options for AWS resource naming conventions were considered:

  1. We considered an option in which we always provide custom names for resources versus an automatic name given by AWS.
  2. Modularizing the code by breaking it into subdomains using custom constructs and assigning a resource type, such as 'Queue', as an ID, as opposed to having all resources into a single stack file, each with an ID reflecting its use case, for instance, 'SendSupplierProductionAPI'.
  3. Experiment with different orders of Resource, Stack, and Stage. For example, {Stage}{Stack}{Resource}, {Resource}{Stage}{Stack}, etc.
  4. Increase the utilization of AWS custom tags.

Reasoning

After extensive discussion and consideration of other options in a meeting, we reached a conclusion to adopt and implement this naming convention.

This convention enhances readability and grouping by clearly indicating the associated project, the corresponding stage, and the purpose of each resource. Consequently, it facilitates easier navigation and searchability within the AWS console.

Consequences

How do we implement this change?

Each team will internally assess the possibility of updating existing resource IDs and names, considering factors such as time, effort (including the need to destroy, recreate, and configure), and resource implications. However, when creating new resources, teams will adhere to the agreed-upon naming conventions.

Additionally, with certain updates to the AWS CDK version, some resources may no longer require custom names. In such instances, teams can also choose to implement these changes.

Currently, the only resource requiring a custom name is API Gateway, while state machines no longer require one. To address this, we may develop a custom AWS CDK construct in the future, offering default configurations.

Who will implement the change?

Everyone within the product team will adhere to these conventions when working with AWS CDK.

How do we teach this change?

Collect or Enable team will host a workshop during one of the upcoming Learning Fridays.

What could go wrong?

In the future, if we choose to change this naming convention, or if AWS introduces new, potentially more strict guidelines, then we may need to recreate and reconfigure all infrastructure created using AWS-CDK. This could be a hassle and may require more time.

What do we do if something goes wrong?

If an issue arises during deployment, a specific team should revert to the previous version to ensure normal operations or workflow. Concurrently, they should resolve all deployment-related issues while adhering to the new guidelines.

What is still unclear?

How should we handle cases in which resources are unable to adopt these conventions, or when the resource's name exceeds the supported limit for letter size?

Related ADRs