I've been meaning to make this guide, having worked at a SAAS from the very get-go, I've now got to live with some good and some bad decisions. It's been very hard to pinpoint why the naming conventions have lead to complexity. And overtime I realized that with engineering, you often make decisions based on the tradeoffs, but ultimately you do optimize for something. If you don't figure out what that something should be, you end having a solution which is not optimized for the problem you are trying to solve.

Living with a SAAS for many years now start to finish, what I ended up finding that these conventions are more important than I initially thought, and have ramifications in many different areas:

These areas can all be condensed into the following guiding principals

Guiding Principles

1. Naming Consistency Principle​

Definition:
A given resource should have the same name in every environment—whether it’s dev, prod, or any other. For example, a resource called user-service should be named user-service in all environments, rather than user-service-dev or user-service-prod. Environment must be represented by namespace isolation, not naming convention.

Why it matters:
Consistent resource names dramatically simplify the process of grouping, querying, and managing deployment instances across various tools and platforms. It helps reduce cognitive load and operational complexity, especially as your infrastructure grows.

2. Naming Stability Principle​

Definition:
Prioritize naming conventions that minimize how often resource names need to change over the lifetime of your systems. Choose prefixes or structures for your names that are unlikely to require revision as your organization and requirements evolve.

Why it matters:
Stable naming reduces refactoring, lowers risk of errors, and leads to smoother automation and scaling. The fewer changes needed, the more reliable and maintainable your environment will be in the long run. You'll also find that following this principal results in a better security posture, more on that later.

Segregation Strategy

Segregation needs to be done in a strategic way. Resources segregated differently can lead to drastically different outcomes. Following a consistent pattern for Segregation and Naming Conventions can lead ot many different benefits:

• To avoid naming collisions
• To reduce complexity by not adding unnecessary naming conventions to resources.
• To make it easy to group resources across environments together. This is useful in filtering duplicates for security findings, as having different names for the same resources adds complexity to the queries needed
• Easier to automate as resources are easier to target across different environments as they are named in a predictable way.
• Within an environment, segregating services and organizations sharing an environment increases your security posture, as the prefixes can be used to scope access to resources and create access boundaries

Account Segregation​

How you segregate your account will determine your name space, and therefore will affect your naming conventions. When creating accounts, modern patters would be to have 1 per region and environment, but there may be cases where you take a different approach again because of other factors related to: (*Cost&, Compliance, Security, etc). But do challenge this decision if you do not segregate, as there is now especially strong multi-account support in Cloud Providers such as AWS.

In general the more you segregate, the less likely you'll have naming collisions.

Prefixing​

Segregation Hierarchy​

Prefix Structure​

Structuring your names correctly is key to the success of your naming conventions.

If your config store is NOT located in the same namespace as the resource, you will have to have {env} in your naming conventions. It's challenging where to put {env}, as there are tradeoffs Also note if your config store is NOT in the same {region}, then you will need to have {region} in your naming conventions.

Segment Definitions​

Segment Order​

It is sometimes said:

Good architecture makes change easy. Bad architecture makes change hard.

Therefore in this decision we should optimize for making Change Easy, which would dictate the

stability should decrease left to right in a prefix

• Changing leftmost segments causes the greatest disruption.
• Renaming service only affects its subtree.

Therefore it makes sense the order of the segments should be the most stable to the least stable:

Segment Stability​

Fully Qualified Examples​

Delimiters​

Now that we have segments, and their order, we need to decide on the delimiters to use. Here are some possible candidates evaluated over different resource types. You'll see that the - is most supported. _ is a strong candidate but fails when it comes to host names and S3 bucket names.

Possible Candidates for Delimiters:

There are different types of delimiters. Sometimes we are representing differences between the different segments of the prefix, other times we are representing differences between the different words with the same segment. Therefore we need a delimiter for each case. As - is the only supported delimiter for all resource types, including another is not ideal because it will reduce the resources types which can follow that convention. Instead the -- is used to delimit between the different segments of the prefix, and a - is used to delimit between the different words with the same segment.

• Often 1 is not possible as a name (for example IAC solutions such as AWS Cloudformation)
• - is preferred over _ as it is more URL friendly (can appear in the host name where as underscore cannot).
• -- whilst this doesn't look the most pleasing to the eye, it is more URL friendly and distinguishes between the hierarchial delimiters and word delimiters.
• other tools will not use -- as a delimiter, so using it as a delimiter in the prefix for a key will not be compatible with other tools.

Native Delimiters​

Full example:

1. /{org}/{domain}/{service}/{key} => /acme/payments/checkout-api/stripe-webhook-secret
2. {org}--{domain}--{service}--{key} => acme--payments--checkout-api--stripe-webhook-secret

Rational for Convention​

Every prefix is a meaningful operational boundary​

Account-segregated (preferred) — config store:

Account-segregated — data storage with partition (e.g. S3 log data):

Non-account-segregated — env and region included:

Segment Definitions​

Region​

The region identifies the physical or logical infrastructure region where the deployment instance resides.

Examples:

• ap-southeast-2
• us-east-1
• eu-west-1

Org​

The org identifies the top-level organizational boundary. Which department owns the resource.

Domain​

• Encodes business capability rather than org structure — capabilities are far more stable than teams or products over time
• Well understood in modern engineering culture thanks to DDD, Team Topologies, and microservices discourse
• Naturally guides correct usage — engineers intuitively know whether something belongs to payments or identity
• Aligns with how most mature orgs already think about their architecture, even if they don't use the word

Service​

The service represents the concrete deployable unit. This is the actual runtime component which is typically the primary identity engineers interact with..

Examples:

• checkout-api
• auth-service
• webhook-worker
• billing-scheduler

Deployment Units could be in the form of:

• Lambda function
• Microservice

Key​

The key identifies a specific configuration value, secret, resource, or parameter belonging to a service. Represents the exact value being referenced. Everything to the left provides context.

• Created
• Deleted
• Renamed
• Rotated

Tagging (Suggestions)​

Tagging Env​

Many would argue that you need to tag every resource with what environment it lives in. I would argue that if you are segregating environments by accounts, then tags are redundant. Tagging resources would then violate the DRY Do Not Repeat Yourself principle, and add to overhead in needing more unnecessary tagging policies. Whilst it's fairly easy to tag resources you manage, sometimes tools or other entities manage resources in your account and it can be problematic to tag them.

Account itself is a stronger way (than tagging) to group resources across an environment together, as an Account is an actual container for resources, and not just a label. It's easier to make mistakes and not tag a resource for some amount of time, cause cost allocation calculations to be incorrect, whereas usage by Account is always accurate.

If there is some other need to tag resources, such as for security or compliance or because of a tool or service you are using. Then have the Account the source of truth and perform batch tagging as needed. This will reduce the Maintainability.

Concrete Examples:

For the naming convention we don't want to have the {env} and {region} because of the Naming Consistency Principle. But because of uniqueness constraints within a namespace this is not always possible. See uniqueness constraints below:

Uniqueness Constraints​

Concrete Example​

Following Native Hierarchies

Many systems have their own built-in hierarchical constructs — path delimiters, subdomain delegation, namespace scoping. When a system already provides a hierarchy, map your naming segments onto it rather than encoding structure into flat compound names.

If the system provides a hierarchy, use it. Don't fight it.

The same logical segments ({org}, {env}, {domain}, {service}, {key}) apply regardless of the system — only the direction, delimiter, and order may differ. Mapping onto native hierarchies preserves the system's built-in ability to filter, delegate, and scope by prefix or level.

Why Use Native Hierarchies?​

Native hierarchies provide critical operational benefits that flat compound names cannot:

1. Prefix Filtering & Querying - Systems like S3, SSM, and CloudWatch Logs support prefix-based queries, enabling you to fetch all resources for an org, domain, or service in a single operation
2. Permission Scoping - IAM and other RBAC systems can grant access via path prefixes, enabling least-privilege access without listing every resource
3. Console Organization - AWS console and CLI tools can drill-down and organize resources hierarchically, improving usability
4. Operational Boundaries - Each prefix level becomes a meaningful operational boundary for automation, monitoring, and access control

Priority Decision: Native Hierarchy vs. Compound Naming​

When naming a resource, follow this priority:

1. Does the service support native hierarchy? → Use the native hierarchy with its delimiter (/, ., :, etc.)
2. No native hierarchy? → Use compound kebab-case with -- segment delimiters and - word delimiters

Example - CloudWatch Metrics (Critical Pattern):

CloudWatch Metrics have THREE naming components, each serving a distinct purpose:

❌ WRONG: Encoding service in namespace → Namespace: acme/payments/checkout-api, Metric: request-count

• Problem: Cannot query across services ("show me high CPU for ALL services in payments")
• You'd need separate queries for each service

✅ RIGHT: Service as a dimension → Namespace: acme/payments, Dimension: service=checkout-api, Metric: request-count

• Env handling (account-segregated, RECOMMENDED): Each account's metrics are naturally isolated; no env dimension needed
  • Prod account metrics: acme/payments namespace, service=checkout-api dimension
  • Dev account metrics: acme/payments namespace, service=checkout-api dimension
  • Permission boundary = AWS account; queries automatically scoped by account access
• Env handling (if NOT account-segregated): Add env dimension for isolation
  • Both environments in same account: service=checkout-api,env=prod vs service=checkout-api,env=dev
  • But you must manage IAM permissions to prevent cross-env visibility
• Result: Maximize query utility (cross-service queries) while maintaining permission boundaries

Services with Native Hierarchies​

DNS​

DNS naming is a special case where the hierarchy is reversed compared to prefix-based naming conventions.

Prefix-based systems grow left → right:

/{org}/{domain}/{service}

DNS grows right → left:

{service}.{env}.{org}.com

Both represent the same logical hierarchy in opposite directions.

Core Principle​

DNS names must preserve the same logical hierarchy as prefixes, but in reverse order.

Hierarchy equivalence:

Environment Inclusion​

Environment appears in DNS between the service and the org:

{service}.{env}.{org}.com

Each environment account is delegated its own subdomain of the apex domain:

checkout-api.prod.acme.com   (prod account owns prod.acme.com)
checkout-api.dev.acme.com    (dev account owns dev.acme.com)

The apex domain (acme.com) is managed in a central network or DNS account. Each environment account is delegated a subdomain (prod.acme.com, dev.acme.com), giving that account full ownership and autonomy over its DNS records. This mirrors how account segregation provides namespace isolation — the subdomain is the account's namespace in DNS.

Any new service deployed into an account is automatically under that account's subdomain, with no coordination required at the apex level.

Alternative (apex zone per account, no env in DNS):

checkout-api.payments.acme.com

Same name exists independently in each environment account. Env isolation is provided entirely by the account boundary with no qualifier in the URL.

Route53 Hosted Zone Strategy​

Preferred:

The apex domain (acme.com) is managed in a central account. Each environment account is delegated its own subdomain via NS record delegation:

prod.acme.com   (prod account)
dev.acme.com    (dev account)
uat.acme.com    (uat account)

Services are then addressed as {service}.{env}.{org}.com:

checkout-api.prod.acme.com

Each account has full autonomy over its subdomain. Adding a new service or record requires no changes to the central apex zone. The apex zone only needs to be updated when a new environment account is onboarded.

Alternative (apex zone per account):

acme.com

Environment isolation is provided entirely by the account boundary. No env qualifier appears in DNS.

Summary​

DNS is not an exception to the naming convention — it is the same hierarchy represented in reverse due to DNS delegation design.

AWS SSM Parameter Store​

SSM Parameter Store uses / as a native path delimiter and supports GetParametersByPath to fetch all parameters under a given prefix. Use it directly as the segment delimiter — it is the hierarchical naming convention with no translation required.

/{org}/{domain}/{service}/{key}
/acme/payments/checkout-api/stripe-webhook-secret

Every prefix is a valid, queryable operational boundary:

If the Parameter Store is not account-segregated by environment, add {env} after {org}:

/{org}/{env}/{domain}/{service}/{key}
/acme/prod/payments/checkout-api/stripe-webhook-secret

AWS S3 Object Keys​

S3 object keys use / as a logical prefix delimiter. ListObjectsV2 accepts a Prefix parameter, making it efficient to list or process objects scoped to any segment boundary.

For most resources (e.g. application artefacts, backups), the standard hierarchy applies:

{org}/{domain}/{service}/{key}
acme/payments/checkout-api/schema-v3.sql

When storing high-volume data such as logs or events — where output is continuous and needs to be queried or processed in discrete chunks — add {partition} before {key}:

{org}/{domain}/{service}/{partition}/{key}
acme/payments/checkout-api/2024/01/15/14/transactions-00001.json

In this context {key} is the filename — the same segment, just a different form. {partition} groups many such {key} values into a queryable set.

{partition} is the only segment permitted to contain internal hierarchical delimiters. This allows a partition to span multiple levels of granularity within a single logical segment — for example, time-series log data is commonly partitioned as {year}/{month}/{day}/{hour}. Every sub-level of the partition remains a valid prefix boundary. All other segments must be flat.

Prefix boundaries remain meaningful at every level, including within the partition itself:

AWS IAM Paths​

IAM roles, users, groups, and policies support an optional /path/ prefix that can be used to organise resources and scope access via IAM policy conditions (iam:ResourceTag or path-based conditions).

/{org}/{domain}/{service}/
/acme/payments/checkout-api/

A policy granting cross-service access to everything under payments:

"Resource": "arn:aws:iam::*:role/acme/payments/*"

Container Image Registries​

Container registries such as ECR, Docker Hub, and GHCR use a {registry}/{namespace}/{image}:{tag} structure. Map org and domain onto the namespace hierarchy, with the image tag serving as {key}:

{registry}/{org}/{domain}/{service}:{key}

The : is the native delimiter for the tag in image references — the same role / plays in path hierarchies. {key} here is the image tag (e.g. 1.2.3): the final identifier that specifies exactly which artifact is being pulled.

Examples:

{key} encodes the version, not the environment. Environment is determined by which account pulls and runs the image, not by the image reference itself.

Cross cutting secrets/config

Logical Name vs Physical Name

Logical Name: checkout-api

Physical Deployment Instance: Account: prod Region: ap-southeast-2 Name: checkout-api

Fully Qualified Identity: ap-southeast-2/prod/checkout-api

Name remains constant. Namespace varies.

Deployment Instance

A Deployment Instance is a concrete runtime instantiation of a logical resource within a specific namespace.

Example:

Logical Resource: checkout-api

Deployment Instances:

• Account: dev → checkout-api
• Account: prod → checkout-api
• Account: uat → checkout-api

All share the same logical name but exist in different namespaces.

Quick reference guide for naming AWS resources following the Derrops conventions. All examples assume account-segregated environments (preferred approach).

Core Format: {org}--{domain}--{service}--{key} (compound kebab-case with -- segment delimiters)

Template Variables Reference​

Before using this cheatsheet, understand what each placeholder means:

Summary Table - All Services​

⚠️ Critical: Native Hierarchy Detection​

Many services support their own native hierarchical constructs. Always check if a service has native hierarchy support BEFORE applying -- segment delimiters. Using native hierarchies enables:

• Prefix filtering and querying
• Permission scoping via path-based policies
• Better operational organization
• Automatic drill-down capabilities in console

Example: CloudWatch metrics require careful structure:

• Namespace uses / for org/domain ONLY (e.g., acme/payments) ← USE THIS FOR HIERARCHY
• Dimensions include service={service} (e.g., service=checkout-api); env via account boundary ← USE THIS FOR CROSS-SERVICE QUERIES
• Metric names use - for words only (e.g., request-count, error-rate) ← Use this for specifics

Why? This enables meaningful queries like "all services in payments domain with high CPU" by filtering the service dimension, not namespaces. Each account's metrics are naturally isolated, maintaining permission boundaries while maximizing query utility!

Delimiter Decision Matrix​

Global vs Regional Scope​

Native Hierarchy Support​

PRIORITY: Always use native hierarchies when available. They provide operational benefits flat names cannot.

Common Pitfalls & Solutions​

Quick Reference by Layer​

Infrastructure Layer​

VPC: acme--payments--checkout-api--vpc
Subnet: acme--payments--checkout-api--subnet-private-1a
Security Group: acme--payments--checkout-api--alb

Compute Layer​

ECS Cluster: acme--payments--checkout-api--cluster
ECS Service: acme--payments--checkout-api
EC2 Instance: acme--payments--checkout-api--web-01
Lambda: acme--payments--checkout-api--webhook-handler

Data Layer​

DynamoDB: acme--payments--checkout-api--transactions
RDS Instance: acme--payments--checkout-api--primary
RDS Database: acme_payments_checkout_api
ElastiCache: acme--payments--checkout-api--cache
S3 Bucket: ap-southeast-2--prod--acme--payments--checkout-api--data

Messaging Layer​

SNS Topic: acme--payments--checkout-api--transactions
SQS Queue: acme--payments--checkout-api--events
SQS DLQ: acme--payments--checkout-api--events--dlq
Kinesis Stream: acme--payments--checkout-api--events

Integration Layer​

API Gateway: acme--payments--checkout-api--api
Step Functions: acme--payments--checkout-api--order-processing
EventBridge Rule: acme--payments--checkout-api--process-webhook-rule

Observability Layer​

CloudWatch Logs: /acme/payments/checkout-api/application-logs
CloudWatch Metrics:
  Namespace: acme/payments (org/domain only)
  Dimensions: service=checkout-api (env via account boundary)
  Metric Name: request-count, error-rate, latency-p99
  Example Query: "All high-CPU services in payments" → Query namespace acme/payments, filter by service dimension
  Permission Boundary: Account segregation; no env dimension needed
X-Ray Rule: acme--payments--checkout-api--sampling-rule
Config Rule: acme--payments--checkout-api--encryption-enabled-rule

Security Layer​

IAM Role: /acme/payments/checkout-api/checkout-api--lambda-role
IAM Policy: acme--payments--checkout-api--s3-access-policy
WAF Web ACL: acme--payments--checkout-api--waf
ACM Certificate: checkout-api.prod.acme.com

DNS Layer​

Hosted Zone: prod.acme.com
DNS Record: checkout-api.prod.acme.com
Route53 Private Zone: checkout-api.internal.prod.acme.com
CloudFront Alias: checkout-api.prod.acme.com

Storage/Config Layer​

S3 Object Key: acme/payments/checkout-api/schema.sql
SSM Parameter: /acme/payments/checkout-api/stripe-webhook-secret
Secrets Manager: acme/payments/checkout-api/db-password

Tagging Strategy​

Apply these tags to all resources for cost allocation and resource management:

Implementation Checklist​

• Define segments: org, domain, service values
• Account strategy: 1 per environment? (Recommended: yes)
• Test naming: Create 1-2 sample resources in non-prod
• Document exceptions: Route53 reverse hierarchy, DNS patterns
• Create IAM policies: Use path prefixes for least privilege
• Enable AWS Config: Enforce naming patterns automatically
• Set up tagging: Apply tags to non-nameable resources
• Create runbooks: How to find resources by naming convention
• Train team: Share cheatsheet and examples
• Monitor drift: Regular audits for non-compliant names

Format Comparison Examples​

One-Liner Reference​

Need to name a resource? Apply this logic in order:

1. Does it support native hierarchy? → Use it (/ for paths, . for DNS)
2. Is it globally unique (S3, ACM, CloudFront)? → Add ap-southeast-2--prod-- prefix (literal region and env values)
3. Is it DNS-based? → Use reverse hierarchy: {service}.prod.acme.com (env in domain via account)
4. Otherwise → Use format: {org}-{domain}-{service}-{key} with - delimiters, -- between segments
5. Tag everything else that doesn't support naming

This document defines where configuration and secrets live, why, and the rules governing each layer.
The goal is to make configuration explicit, auditable, secure, and predictable.

Where does configuration live?​

Configuration is split into layers, each with a clear responsibility.
No single system should answer every question.

Configuration Authority Hierarchy

Each configuration value has exactly one authority.

.env files (Local Development Layer)​

.env files are used only for local development.

Purpose​

• Provide secrets and configuration for local execution
• Allow developers to run services without cloud dependency

Rules​

• Must not be committed to Git
• Must be gitignored
• Must only exist locally
• Must not be used in production
• Must follow the same schema as production configuration

Git (Policy Layer)

Git is the source of truth for intent and policy.

It answers why something exists, not what it currently is.

Git defines​

• Allowed values
• Schemas
• Constraints
• Policy-level defaults
• Environment shapes

Git must not contain​

• Secrets
• Runtime values
• Environment-specific endpoints
• Credentials

Rules​

• All changes require review
• All changes must be auditable
• Git defines policy, not runtime state

SSM Parameter Store (Runtime Configuration Layer)

SSM represents runtime configuration state.

Rules​

• Values must conform to Git policy
• Values must be environment-scoped
• Changes must not require rebuilds
• Parameters must be hierarchical and namespaced
• Secrets Manager should be preferred over SSM for secrets

Naming Convention​

/{org}/{system}/{env}/{service}/{key}

Example:

/fortiro/protect/prod/api/feature/scan-enabled /fortiro/protect/prod/api/db/host

Secrets Manager (Primary Secrets Layer)

Secrets Manager is the preferred system for managing secrets.

Rules​

• Must be injected at runtime
• Must never be hardcoded
• Must never be committed to Git
• Must be readable only by authorised services
• Rotation should be enabled when possible

Tags (Metadata Layer)

Tags define ownership and metadata.

Rules​

• All AWS resources must be tagged
• Tags must never control application behavior
• Tags must not contain secrets

Codebase (Consumer Layer)

The codebase consumes configuration.

Rules​

• Must not define runtime values
• Must not define secrets
• Must validate schema
• Must fail fast on missing configuration

Fail Fast Requirement

Application startup must fail if:

• Required configuration is missing
• Secrets cannot be retrieved
• Configuration violates schema

Configuration Injection Model

Configuration must be injected at runtime via:

• Environment variables
• SSM Parameter Store
• Secrets Manager

Configuration must never be compiled into the application artifact.

Runtime Defaults Policy

Defaults must exist only in configuration, not application logic.

Allowed:

size: params.size ?? config['app.pagination.default.size']

Forbidden:

size: params.size ?? 20

Environment Precedence

Highest precedence first:

1. Explicit test configuration injection
2. System environment variables
3. Local .env
4. SSM Parameter Store
5. Secrets Manager
6. Git policy
7. Code schema validation

Result

This model ensures:

• Secure secret handling
• Explicit runtime configuration
• Fail-fast startup guarantees
• Predictable deployments

Glossary

• Deployment Instances