Explaining configuration

Usage

ael config explain
ael config explain --json

What it shows

For every field of every configuration in the project, it shows:

• The value it has.
• The layer that set it: the configuration's defaults, a shared configuration, a named environment variable or file, the deployment, or an override for one run.
• What it overrides: the values from lower layers that it replaces, field by field.
• External values: for a value that refers to an environment variable, a file or a secret, the reference, and whether it is resolved when a run starts.

Layers apply in the order you declare, and a higher layer overrides a lower one for each field separately. The order in which files are found never decides a value. Configuration describes the layers.

Secrets stay secret

ael config explain never prints a secret value. A secret is shown as its reference, masked, never as the value it holds. Secret values appear nowhere in your source, in compiled files or in the explanation.

Problems it reports

It applies the same rules as ael check, and names the field and the layers involved in each problem:

• a field that the configuration does not declare;
• a required field that no layer sets;
• a value of the wrong type, or text longer than its field allows;
• two layers of the same rank that set one field;
• configurations that refer to each other in a cycle.

Snapshots

Before a run is admitted, its configuration is resolved, validated and pinned, and the run keeps that snapshot to the end. What ael config explain shows is what a run starting with the same deployment settings would be pinned to. A value that changes later applies to runs that start afterwards.

What it never does

It reads no environment variable, file or secret value, opens no connection, calls no model and runs none of your code. It changes nothing.

Related

• Configuration: configuration files, layers and snapshots.
• Effects and capabilities: what configuration can never grant.