Skip to main content

Decide on Regional Naming Scheme

We need to decide how we’ll handle DR if that’s a requirement. It has far-reaching implications on naming conventions and is not an easily reversible decision.

Our current best practice is to use the following convention:

FieldDescriptionExample
namespaceSomething short that uniquely identifies your organization. This relates to Decide on Namespace Abbreviationcpco

eg
tenant
environment
(aka abbreviated region)
Environment indicates which AWS region the resource is in, using one of 2 sets of abbreviations. We use gbl for resources that are not specific to any region, such as IAM Roles.

You have a choice of 2 sets of abbreviations: fixed or short.

The fixed abbreviations are

- exactly 3 letters


- short and consistent so lists stay aligned on semantic boundaries


- The drawback is that AWS regions, have collisions when algorithmically reduced to 3 letters, so some regions (particularly in Asia) have non-obvious abbreviations


The short abbreviations are

- 4 or more letters


- easier to understand


- usually identical to the prefix AWS uses for Availability Zone IDs in the region


- The drawback is that there is 1 or more additional characters which can lead closer to max character restraints (e.g. target groups have a max of 32 characters)


We recommend using the short abbreviations, which more closely canonical zone ids by AWS.

See AWS Region Codes for the full breakdown.
AWS region code → fixed abbreviation (3 letter) → short abbreviation (4 letter+)

us-east-1ue1use1

us-west-2uw2usw1

eu-west-3ew3euw3

ap-south-1as0aps1

af-south-1fs1afs1

cn-north-1nn0cnn1

us-gov-west-1gw1usgw1
stage
(aka account)
The stage is where the resources operate. Our convention is to isolate every stage in a dedicated AWS member account (aka flavor), which is why we frequently call accounts stages.prod, at, network

These field names correspond to the variable inputs of the terraform-null-label (https://github.com/cloudposse/terraform-null-label) used throughout all Cloud Posse terraform modules. Usage of this convention ensures consistency and reduces the likelihood of resource name collisions while maintaining human legibility.

Using this convention, resource names look like this: {namespace}-{tenant}-{environment}-{stage}-{name}-{attributes}

Here are some more examples to help understand the relationships.

InputsOutputs

namespace: acme
environment: ue2 # us-east-2
stage: automation
name: eks-cluster
acme-ue2-automation-eks-cluster

namespace: acme
environment: gbl
stage: dev
name: eks-cluster
attributes: ["test"]
acme-gbl-dev-eks-cluster-test

namespace: acme
tenant: vkng
environment: ue2 # us-east-2
stage: automation
name: eks-cluster
acme-vkng-ue2-automation-eks-cluster

Also, see the corresponding design decision for the Decide on Hostname Scheme for Service Discovery as this will be impacted by whatever is chosen.