Skip to content

MDAA Naming

This package defines an interface for MDAA-compatible naming implementations, along with a default implementation. Naming implementations will be passed the MDAA CDK App Context in order to initialize themselves based on any context specified in the MDAA execution environment.

Resource Type Support

The MdaaResourceType enum and withResourceType() method allow custom naming implementations to produce resource-type-aware names. The default implementation is a no-op — it ignores the resource type and returns names unchanged, preserving backwards compatibility.

The example output below is only achievable via a custom implementation that overrides withResourceType() (see CUSTOMIZATION.md). Out of the box, the default implementation will produce the same name regardless of which MdaaResourceType value is supplied.

// With a custom impl that overrides withResourceType (see CUSTOMIZATION.md):
const naming = customNaming.withResourceType(MdaaResourceType.S3_BUCKET);
const bucketName = naming.resourceName('my-data');
// → "aw-dev-s3-dpl-retail-datalake-my-data"

See CUSTOMIZATION.md for full examples.

Including env in SSM Paths and Export Names

By default, the SSM parameter paths and CloudFormation export names generated by the default naming implementation do not include the environment (env):

Method Default format
ssmPath() /<org>/<domain>/<module_name>/<path>
exportName() <org>:<domain>:<module_name>:<path>

This causes a collision when the same module is deployed to multiple environments (e.g. dev and prod) within a single AWS account: both deployments produce identical SSM parameter names (silent overwrite / cross-environment leakage) and identical CloudFormation export names (the second deployment fails outright, since export names must be unique per account/region).

Enabling env-aware paths

Set the @mdaaIncludeEnvInSsmPath CDK context flag to true (via a context block in your MDAA config, or additional_context on a module). The value must be exactly true or false — any other value is rejected with an error to prevent a typo (e.g. yes, 1) from being silently misinterpreted. When enabled, env is inserted immediately after domain:

Method Format with @mdaaIncludeEnvInSsmPath: true
ssmPath() /<org>/<domain>/<env>/<module_name>/<path>
exportName() <org>:<domain>:<env>:<module_name>:<path>

The flag defaults to false, so existing deployments are unaffected unless explicitly opted in. When enabled, all internal code paths that publish SSM parameters and exports (via naming.ssmPath(...) / naming.exportName(...)) automatically adopt the new format — no per-module code changes are required.

Referencing env-aware parameters

The flag only affects the publish side. When referencing another module's env-aware parameter in config, the framework cannot infer which environment you mean, so you must supply env explicitly — just as you already supply the module name:

# Preferred for same-domain references — ssm-env: already prepends /<org>/<domain>/<env>/,
# so no manual env segment is needed:
someKmsKeyArn: ssm-env:/my-kms-module/cmk/arn

# With ssm-domain: (prepends only /<org>/<domain>/), include the env segment yourself:
someKmsKeyArn: ssm-domain:/dev/my-kms-module/cmk/arn

# With ssm-org: or a literal resolve:ssm: reference, write the full env-aware path:
someKmsKeyArn: ssm-org:/my-domain/dev/my-kms-module/cmk/arn

Migrating an existing deployment

Enabling the flag changes SSM parameter names and CloudFormation export names, so it is a breaking change for any deployment whose consumers reference the old paths. Because the parameter/export names change while the underlying CloudFormation logical IDs do not:

  • Each SSM parameter is replaced in place — CloudFormation creates the new env-aware parameter and deletes the old one in the same deploy. There is no lingering old parameter to clean up, and no overlap window where both the old and new names resolve.
  • An export name cannot be changed while another stack still imports it (Fn::ImportValue). You must stop consumers from importing the old export before (or in the same coordinated change as) redeploying the producer, otherwise the producer deploy will fail.

To migrate safely:

  1. Update all config references to the affected parameters/exports to the env-aware paths (see above) before redeploying the producers, so no stack imports the old export name.
  2. Enable @mdaaIncludeEnvInSsmPath: true and redeploy. Producers publish at the env-aware paths (old parameters are replaced, not orphaned) and consumers resolve the new paths.