Runtime Environment Configuration How-To

How to wire a CloudFormation output value from a runtime environment into a deployed Kotlin service.

Design documentation for the Runtime Platform Model, environment configurations, and infrastructure resource catalogs is covered in the Current System architecture documentation.

CloudFormation Output Naming Conventions

Export names follow two patterns depending on intended audience.

Values accessible outside the defining repository:

Identifier	Regular expression
Logical ID	/.*_?API$/
Export Name	/.*-API-.*/

Values used internally within the defining repository (outside CDK/CloudFormation code):

Identifier	Regular expression
Logical ID	/.*_?I$/
Export Name	/.*-I-.*/

A service may only access *-API-* outputs from other repositories. It may access both *-API-* and *-I-* outputs from its own repository.

Accessing an Output in Application Code

The following six steps wire a CloudFormation output into a Kotlin service’s runtime configuration.

Step 1: Add a readExport line to the Helm values script

In ${PROJECT_ROOT}/src/helm/read-cloudformation-values.cmd, add:

readExport <path>.<to>.<key>.extras.some.myKey ${PURPOSE}-API-MyKey

Where <path>.<to>.<key> is the dotted path in application.conf where the value will be placed. See the helm-deploy-pipeline-action documentation for the full syntax and available options.

Step 2: Declare the key in application.conf

In the service’s application.conf (or the appropriate module configuration file, e.g. reference/item/application.conf):

extras {
  some {
    myKey = ""
  }
}

If a placeholder value is required for unit tests and cannot be set in test setup, add it to an application-test.conf file.

Step 3: Include the key in the Helm ConfigMap

In ${PROJECT_ROOT}/src/helm/templates/configmap.yaml:

override.properties: |
  ...
  path.to.key.extras.some.myKey={{ .Values.system.reference.item.extras.myKey | required "myKey" }}

Step 4: Add the key to lintValues in build.gradle.kts

val lintValues = mapOf(
  // ... existing entries ...
  "path.to.key.extras.some.myKey" to "lint-value-placeholder"
)

Step 5: Verify the build passes

./gradlew clean build

Step 6: Test-deploy to local Kubernetes

./gradlew clean helmInstallToLocal