Kubernetes Configuration Management - CLI Guide | Codiac

Configurations are key/value pairs, often used as settings.

What you'll get

• Set, view, import, and delete config at enterprise, environment, cabinet, or asset scope
• Use #REF| to reference secrets from AWS Secrets Manager or Azure Key Vault
• Config hierarchy: child scopes override parent; one image, many environments

Prerequisites

• Codiac account and CLI installed and logged in
• An enterprise, environment, and cabinet (or Hosted Sandbox); for secrets, a secret store linked

Interactive CLI

The Codiac CLI guides you through each command interactively. Just run codiac config set and the CLI prompts you for scope, config type, key, and value. Configurations are 100% encrypted at rest.

Usage and Options

Use codiac config -h to see all the available options:

Adds a key value pair to the app config

USAGE
  $ codiac config COMMAND

TOPICS
  config settings  Shows the list of clusters.

COMMANDS
  config add     Adds a key value pair to the app config
  config delete  Removes the given keys from the app config
  config deploy  Deploys a given asset to a given cabinet.  Defaults to current version.
  config import  Adds a key value pair to the app config
  config set     Adds a key value pair to the app config
  config view    Shows the values that are explicitly set in the given config

Add a config

codiac config set

The CLI prompts you to select:

1. Config type (file, env, filestore, footprint, helm, annotation, label, probing, k8spatch). footprint covers replicas, CPU/memory, scaling.* and rollout.*.
2. Scope (enterprise, environment, cabinet, or asset level)
3. Key and value for the configuration

Scripted mode (for automation)

Use the --to-script flag to run without interactive prompts:

codiac config set --to-script

This outputs the full command with all flags that you can use in CI/CD pipelines.

tip

Do you have an existing configuration you want to copy over to a new asset? Use pipes!

Edit a config

codiac config set

The CLI guides you to select the existing config you want to edit, then prompts for the new value.

Copy a config

Use pipes with the codiac config settings get command to copy configs into a different cabinet, environment, or enterprise.

For example, the command to copy the fav-color config at the dev environment level to the qa cabinet (on the my-api asset in the main enterprise) is:

codiac config settings get --enterprise main -a my-api -e dev --setting fav-color | cod config set -a my-api -c qa

tip

Use codiac config setings get --to-script to help you automatically assemble the command arguments.

See Piping configs for more detailed information.

Delete a config

codiac config delete

The CLI prompts you to select the configuration you want to delete.

Scripted mode (for automation)

codiac config delete --to-script

Expression-powered configs

Config values and config conditions support JSONata expressions evaluated at deploy time against the deployment context — environment name, cluster properties, asset name, cabinet namespace, and more. This works across all config types.

For example, a config value of:

"https://" & asset.name & "." & environment.name & ".example.com"

resolves to https://my-api.prod.example.com when deploying the my-api asset to the prod environment.

Individual settings can also carry a condition expression. If the condition is falsy at deploy time, that setting is omitted — without needing separate config entries per environment.

• Expression Context Reference — all available fields and functions
• Expression Examples — recipes for common workflows

Piping configs

Pipes let you use the output of one command as the input for another.

tip

Use codiac config setings get --to-script to help you automatically assemble the command arguments.

Example 1: Pipe configs from one env to another

You can use pipes to copy Codiac configs from one environment into another. For example:

1. The following command retrieves all the configs at the environment level for the dev environment:

codiac config settings get -a my-api -e dev -f app-config.json

2. Next, build on that command by using pipes to copy the configs from the dev environment into the qa environment:

codiac config settings get -a my-api -e dev -f app-config.json | cod config set -a my-api -f app/app-config.json -e qa 

Example 2: Pipe configs into a file

You can also pipe configs into a file. This lets you examine and edit the values before you copy them into a new environment.

This command writes the configs for the dev environment into a file named temp-configs.json:

codiac config settings get -a my-api -e dev -f app-config.json > temp-configs.json

1. Open the file temp-configs.json and edit the values. In this example, we change Hometown to Chicago. We also change the user and password to reference the secrets for the qa environment:

   {
     "hometown": "Chicago",
     "db": {
       "server": "mongo.qa.ourcompany.com",
       "name": "growing",
       "user": "#REF|our-secret-store|growdb-qa-user",
       "password": "#REF|our-secret-store|growdb-qa-password"
     }
   }

2. Save and exit the file.

3. Pipe the contents of temp-configs.json into a codiac config set command to copy the configs into the qa environment.:

cat temp-configs.json | codiac config set -a my-api -f app/app-config.json -e qa

4. Refresh the qa cabinet to see the new configs:

codiac config deploy -a my-api -f app-app-config.json -c sprint15

Notes on piping configs

1. The commands codiac config delete and codiac config set only affect config/value pairs. You have to set the destinations (e.g., asset, file, cabinet, etc) on these commands to declare where they will be written, no matter where the piped input came from.

2. TTY User interaction is deactivated when you pipe stdin. The --silent flag is set automatically. This means you must set up your command correctly before you execute it.

3. the --setting argument is multi-use on codiac config delete. It also supports globbing. eg: --setting 'db.*'.

warning

USE LITERAL QUOTATIONS WHEN GLOBBING. Otherwise, your shell may execute the glob in the current working directory before Codiac can interpret it. Your shell may automatically pass a list of local files matching your glob to the Codiac CLI instead of the glob pattern itself.

Inline expressions

Config values can embed @{...} expressions that Codiac evaluates at deploy time. The result is substituted into the value before the config is applied, so the same setting resolves differently for each cabinet without maintaining per-environment copies.

# Embed asset and cabinet names in a URL at deploy time
cod config set -a my-api -t env \
  --setting API_URL \
  --value 'https://@{asset.name}.@{cabinet.name}.mydomain.com'

Expressions use JSONata — not just field lookups, but also comparisons, string concatenation, and conditionals. See Expression Examples for recipes.

Available context paths

Expression	Returns
@{asset.name}	Asset name
@{asset.version}	Asset version being deployed
@{cabinet.name}	Cabinet name
@{cabinet.namespace}	Cabinet's internal runtime namespace
@{cluster.name}	Cluster name
@{cluster.provider}	Cloud provider (azure, aws, other)
@{cluster.location.code}	Cloud region code (e.g. eastus, us-east-1)
@{enterprise.name}	Enterprise name
@{environment.name}	Environment name
@{tenant.code}	Tenant identifier
@{secrets.<store>.<key>}	A secret value from a KVP store, fetched at deploy time

For the full schema, see Expression Context Reference.

@{$hostmap(...)} and @{$hostmap_path(...)}

Resolve a cabinet's domain mapping into a concrete hostname at deploy time. Use this to wire a fully-resolved host into a config value without maintaining per-environment hostname strings manually.

@{$hostmap("<strategy>", "<domain>")}
@{$hostmap_path("<strategy>", "<domain>")}

• <strategy> — a host naming strategy from cod host list (e.g. svc_dot_cab_dot_domain)
• <domain> — the base domain you registered with cod host map (e.g. my-company.com)

Strategy	$hostmap returns	$hostmap_path returns
svc_dot_cab_dot_domain	<asset>.<cabinet>.<domain>	""
service_dot_domain	<asset>.<domain>	""
cab_dot_domain_slash_service	<cabinet>.<domain>	/<asset>
cab_dot_cluster_dot_domain_slash_service	<cabinet>.<cluster>.<domain>	/<asset>
cab_dot_cluster_dot_enterprise_dot_domain_slash_service	<cabinet>.<cluster>.<enterprise>.<domain>	/<asset>
globally_shared_domain_slash_service	<cabinet>.<enterprise>.<tenant>.<cluster>.<domain>	/<asset>
domain_slash_service	<domain>	/<asset>
shared_ingress_ip	the cluster's ingress IP	/<tenant>/<enterprise>/<cabinet>/<asset>

Example:

# 1. Map the domain — declares how assets on a cabinet route on this domain
cod host map mywebsite.com -e main -v primero-dev -n svc_dot_cab_dot_domain --silent

# 2. Reference the mapping in a helm chart ingress host setting
cod config set -a my-asset -c develop -t helm \
  --setting ingress.host \
  --value '@{$hostmap("svc_dot_cab_dot_domain", "mywebsite.com")}'

At deploy time, Codiac resolves @{$hostmap(...)} against the cabinet's mappings and writes the concrete hostname into the config value. If the (strategy, domain) pair has not been mapped on the cabinet, the value is <HOSTMAP_ERROR: ...> — visible in cod config preview so the failure surfaces loudly. Run cod host list to see what's mapped.

See Ingress and Domain Routing for full details on host naming strategies.

Escaping expressions

@@{...} emits @{...} as a literal in the output. Use it when a config value contains @{...} syntax from another system that should not be evaluated by Codiac.

# Stored and deployed as the literal string @{someOtherSystem.value}
cod config set -a my-api -t helm --setting some.template --value '@@{someOtherSystem.value}'

Shell and bash variable safety

${...} is not processed by Codiac. Bash variables, shell scripts, and other content using ${VAR} syntax pass through unchanged — no conflict with @{...} expressions.

Bulk import with --escape-expressions

When importing a config file from an external system that already uses @{...} syntax — a CI template, a Helm values file, or a shell script — use --escape-expressions to store all occurrences as literals rather than evaluating them as Codiac expressions:

cat external-values.yaml | cod config import --escape-expressions
cat external-values.yaml | cod config set --entire-file --value-stdin --escape-expressions

This flag is all-or-nothing: it converts every @{...} in the input to @@{...}. If the file contains a mix of third-party expressions and Codiac expressions you want evaluated, escape the third-party ones manually with @@{...} instead of using this flag.

---

Runtime config injection

Use the #FROM replica syntax to inject a value that is determined at container startup — for example, the host IP address of the machine running the container:

Example

This example uses runtime injection for the HOST_IP environment configuration:

When the container instance is created, this environment config is dynamically set to the host IP address.

Syntax

Use the #FROM replica syntax in the setting's value to invoke this special behavior. For example:

#FROM|replica|HostIP

warning

These options are case-sensitive.

The #FROM|replica syntax supports the following options:

Option	Value	Description
annotations	KEY	The annotations option requires an additional segment, KEY, to declare which label to reference. For example: #FROM|replica|labels|my-category.
hostIP	n/a	The primary IP address of the machine running the container.
k8s.namespace	n/a	The name of the Kubernetes namespace where the container instance is deployed.
labels	KEY	The labels option requires an additional segment, KEY, to declare which label to reference. For example: #FROM|replica|annotations|prometheus.io/port=9153.
name	n/a	The name of the replica.
nodeName	n/a	The name of the machine running the container.
IP	n/a	The primary IP address of the replica.
IPs	n/a	List of all IP addresses assigned to a replica.
serviceAccountName	n/a	The security identity under which the container is being run.

Rollout strategy

Rollout settings control how Codiac replaces a workload's pods on deploy. They live in the footprint config type:

Setting	Values	What it does
rollout.strategy	RollingUpdate (default) or Recreate	RollingUpdate swaps pods over gradually. Recreate stops every old pod before it starts any new one.
rollout.maxUnavailable	An integer ≥ 0 or a percentage (0%–100%)	How many old pods can be down during the swap.
rollout.maxSurge	An integer ≥ 0 or a percentage (0%–100%)	How many extra pods can run above the replica count during the swap.

With no rollout settings, nothing changes. Codiac keeps its historical default of maxUnavailable and maxSurge at 100%: it replaces every pod at once. That's fast, but it can leave a short gap with no serving pod.

Zero-downtime deploys. This keeps every old pod serving until its replacement is Ready:

codiac config set -a my-api -c orders -t footprint --setting rollout.maxUnavailable --value 0

If you set maxUnavailable to 0 without maxSurge, Codiac sets maxSurge to 1, so it adds one new pod at a time. To roll faster, set maxSurge at the same scope:

codiac config set -a my-api -c orders -t footprint --setting rollout.maxSurge --value 25%

Pair zero-downtime with a readiness probe

"Ready" is only meaningful if the app says so. Without a readiness probe, Kubernetes counts a pod as Ready as soon as its container starts. It then retires the old pod while the new one is still warming up. Add a readiness probe on an endpoint that checks the app can actually serve requests.

Recreate, for singletons. Some workloads must never run twice at once, such as a queue consumer that holds a lock or a single-writer database. For those, stop the old pod before the new one starts:

codiac config set -a my-worker -c orders -t footprint --setting rollout.strategy --value Recreate

Expect a short gap while the new pod starts. Codiac rejects maxUnavailable and maxSurge together with Recreate.

Rules to know:

• Set every rollout.* field at one scope. Footprint settings merge shallowly across enterprise, environment, cabinet and asset scopes, the same way scaling.* does. A rollout set on a cabinet replaces a rollout set on its environment entirely, and any field you leave out falls back to 100%.
• Validation runs before deploy. Codiac rejects maxUnavailable: 0 together with maxSurge: 0, negative numbers, and percentages outside 0%–100% or with fractions. The error reads Invalid footprint config on asset [my-api]: ….
• Replace k8spatch strategy workarounds. If you patch /spec/strategy with a k8spatch, that patch still overrides these settings. Move the values into rollout.*, delete the patch, redeploy, and confirm the change with kubectl get deploy my-api -o jsonpath='{.spec.strategy}'.

To see a rollout happen, deploy with --follow:

codiac asset deploy -a my-api -u 1.4.2 -c orders --follow

Raw Kubernetes patches (k8spatch)

When you need to set something on the rendered workload that isn't a first-class Codiac config — a nodeSelector, tolerations, node affinity, an extra volume, a serviceAccountName — use the k8spatch config type.

A k8spatch value is a JSON Patch (RFC-6902) array of {op, path, value} operations. Store it under the setting key deployment, service, or ingress, depending on which rendered object you're patching. It is not a strategic-merge partial manifest: a value shaped like spec.template.spec.nodeSelector... has no deployment key, so it is stored, deploys "SUCCESS", and is silently never applied. Pass --value-type string so the JSON array is stored verbatim.

warning

Patches are applied additively at deploy time. Deleting the setting does not revert a change that was already applied to the live object — add an inverse operation (op: remove) to undo it.

Pin a workload to a node pool (nodeSelector):

codiac config set -a my-asset -c dev -t k8spatch --setting deployment \
  --value '[{"op":"add","path":"/spec/template/spec/nodeSelector","value":{"workload":"extraction"}}]' \
  --value-type string

Tolerate a tainted (dedicated / spot / GPU) node pool — pair with the nodeSelector above so the pod both targets and is admitted onto the intended nodes:

codiac config set -a my-asset -c dev -t k8spatch --setting deployment \
  --value '[{"op":"add","path":"/spec/template/spec/tolerations","value":[{"key":"workload","operator":"Equal","value":"extraction","effect":"NoSchedule"}]}]' \
  --value-type string

Overwrite an existing field — use op: replace (here, force two replicas); op: add creates a field that isn't there yet:

codiac config set -a my-asset -c dev -t k8spatch --setting deployment \
  --value '[{"op":"replace","path":"/spec/replicas","value":2}]' \
  --value-type string

Verify against the live object once deployed:

kubectl get deploy my-asset -o jsonpath='{.spec.template.spec.nodeSelector}'

What's next

• Expression Context Reference — all fields available in config expressions
• Expression Examples — recipes for common expression workflows
• Dynamic configuration – Config-on-deploy concept
• Manage secrets – Reference cloud secret stores
• Config-on-deploy guide – Best practices
• System versioning – Snapshots and config
• Web UI: Configurations – Same in the dashboard