Keep a Tenant in Git
Export a tenant from a running instance as a tenant folder, commit it, and plan and import changes to it from the folder. Bundles, plans and ownership are explained in Configuration as code; this page uses the same commands and token (Export a tenant).
Export the tenant as a folder
End --output with a slash, or name an existing empty directory:
eudiplo config export --instance production --output ./config/acme/
Any other --output writes a bundle file: JSON for .json, a ZIP otherwise,
also without an extension.
-
Names. Files are named after the resource ID (
clients/<clientId>.json,key-chains/<id>.json,issuance/issuance.json, …). An ID that is no valid file name on every system, that is longer than 80 characters or that differs from another only in case gets a short hash suffix; the ID inside the document is what counts. -
Stable output. Keys are sorted and indented by two spaces, so exporting the same configuration again writes the same files and
git diffshows only real changes. -
Secrets. Placeholders and
keySource: { "type": "required" }are written as the export has them. Instead of amanifest.json, the command lists each value to supply with its file:2 value(s) to supply before this folder can be imported:clients/portal.json /spec/secret: ${CLIENT_PORTAL_SECRET} (CLIENT_SECRET_REQUIRED)key-chains/signing.json /spec/keySource: private key (PRIVATE_KEY_REQUIRED) -
Target. The directory must not exist or must be empty; the folder is written in full or not at all. Name it after the tenant: the startup import takes the tenant from the folder name, and a CLI import uses it as the bundle source.
Plan and import the folder
config plan and config import take the folder in place of a bundle:
eudiplo config plan ./config/acme --instance staging --mode upsert --diff --output plan.json --allow-env PORTAL_SECRET
eudiplo config import ./config/acme --instance staging --mode upsert --plan plan.json --allow-env PORTAL_SECRET
- The CLI validates the folder offline, like
eudiplo config tenant validate. A folder with errors exits with1and is not sent, and so is a folder with a symbolic link that points outside it or does not resolve. - It fills in
${VAR}placeholders from the variables named in--allow-env(see below). A placeholder without a value is named in a warning and sent as it is; the plan blocks that resource withSECRET_REQUIREDuntil the variable is set and named. - It sends the folder as a bundle archive,
info.jsonandimages/included. The bundle is the same for the same files and environment, so the import matches the reviewed plan.
The tenant comes from the access token, not from the folder name.
Planning a freshly exported folder against the same instance shows every
resource as unchanged, except those with a requirement: a client whose secret
is a placeholder is blocked with SECRET_REQUIRED, and a key chain with
"type": "required" with PRIVATE_KEY_REQUIRED, as when the bundle export
itself is planned.
Placeholders and the CLI's environment
A placeholder can sit in any field, and the plan shows field values. So that a change to the folder cannot copy a value out of the environment the CLI runs in, for example a CI runner:
${VAR}placeholders resolve only from the variables named in--allow-env(comma-separated). The CLI reads no other variable, and the option applies to a folder only; a bundle's placeholders are resolved by the server.EUDIPLO_TOKEN,EUDIPLO_CLIENT_IDandEUDIPLO_CLIENT_SECREThold the CLI's own credentials and are refused in--allow-env.- The plan or result that
config planandconfig importprint or save, and an error the API answers, show each filled-in value as its placeholder again, in field values and messages; kinds, IDs and the plan fingerprint stay as they are. A value shorter than eight characters is only replaced where it is the whole value.
config import still stores the filled-in values: review which variables a
change adds to --allow-env before you import it. The startup import fills
placeholders from the backend's whole environment.
Folder imports and the startup import
Every import records its source on the resources it writes: a CLI import of a
folder bundle:<folder name>, the startup import the folder in
CONFIG_FOLDER. replace mode deletes only resources whose recorded source is
its own. If both import the same tenant, each takes over the resources it
writes: switching between them gives !generate clients a new secret, applies
unchanged key chains again (a regenerate key source gets new keys), and a
replace of one does not delete resources last written by the other. Manage a
tenant with one of the two.