cla import - import Clarive configuration from HCL

cla import: reads HCL files and makes the installation match them.

Nothing is changed until you have seen the plan and agreed to it. The plan is computed by comparing what the files say against what is actually stored, so it lists real changes rather than differences in spelling.

Usage¶

cla import <files|dirs>... [-y] [--diff] [--allow-missing] [--lax]
           [--prune] [--internal] [--no-moved] [--secret-key KEY] [--dry-run]

With no paths, ./cla-objects/<env> is read — the same environment-scoped directory cla export writes to, so cla -c prod import reads ./cla-objects/prod. With no config in play it is ./cla-objects.

A path may be a file or a directory; directories are read recursively. A file holding many objects is just a file — there is nothing special to say about packed exports.

The order files are read in never matters.

A path you asked for and that is not there stops the command before anything is planned. Carrying on with the paths that do exist would give you a plan built from part of your configuration, and under --prune the missing part reads as "delete these" — so a mistyped path would delete exactly the objects it was meant to import.

What you see first¶

  1. CREATE    generic_server.back-office (15 attrs)
  2. UPDATE    generic_server.front-desk (1 attr)
1 create, 1 update, 1 unchanged
Apply these 2 change(s)? [y/N]

UNCHANGED entries are counted but not listed. An entry that is a rename shows <- old-address, and one with a reason shows -- reason.

--diff also shows the old and new value of every attribute that changes.
-y skips the question. Use it in scripts.
--dry-run computes and shows everything, and writes nothing.

A sensitive attribute reads (sensitive) on both sides rather than showing its value. By the time a plan exists the secret has been decoded back to the text that would be written, so printing it would put a live credential on your terminal and in the log of whatever ran the command. You still see that it changed, which is what the plan is for.

Actions¶

CREATE — nothing at that address yet.
UPDATE — it exists and some attribute differs.
UNCHANGED — it already matches.
RENAME — a moved block says it used to be called something else, and that something else is what is actually there.
DELETE — a removed block, or --prune.
SKIPPED — it depends on something missing, and --allow-missing was given.
CONFLICT — declared twice in the files, or the live match is ambiguous.
ERROR — it could not be understood.

An import with any CONFLICT or ERROR is refused outright.

Deleting¶

Deletion is never implied by a file simply not mentioning something.

A removed { at = <address> } block asks for one object to go.
--prune proposes deleting live objects absent from the files, limited to the families the files actually talk about. Importing only roles can never propose deleting a resource.

Either way the deletions appear in the plan and need the same confirmation.

When something is missing¶

By default a reference to an object that is neither in the files nor already installed is an error, and the whole import stops. That is deliberate: a dangling reference is how a migration quietly corrupts a target.

--allow-missing turns those into warnings and skips whatever depended on them. The skip travels: if B needs a missing A, and C needs B, both are skipped.

Other options¶

--lax — accept attributes this installation does not recognise, for files written by a newer version. Unknown blocks are still refused.
--secret-key KEY — decrypt values written with --secret encrypt.
--internal — also import classes normally treated as runtime state.
--no-moved — ignore the recorded rename history. A moved {} block in a file still works; what is skipped is the history previous imports wrote.

--plan and -p are accepted and have no effect. To write a plan file, use cla import-plan --out.

Rules¶

Rules import like anything else, and a rule that has not changed plans as UNCHANGED — its version does not move and no version row is written.

A changed rule goes through the same save the Rule Designer uses: the steps are compiled before anything is stored, so a rule that does not build is refused rather than written, and the change is versioned exactly as an edit in the browser would be. A step naming an operation this installation does not have, or pointing at an object that is not there, is reported with its file and line and stops the import.

The addresses inside a rule's steps are resolved against this installation. A step that ran on generic_server.back-office on the machine it was exported from runs on whatever that server is here, whatever id it happens to have.

--prune scopes rules by type, so a file holding only pipelines can never propose deleting a workflow.

Order, and reference cycles¶

Objects are written in dependency order, and references are linked in a second pass once everything exists. Two objects that point at each other are therefore ordinary and need nothing special.

Failure¶

There is no rollback. Mongo offers no transaction across documents here, so the plan-and-confirm step is the safety, not a pretend undo. If something fails partway, the run stops and reports exactly what was applied and what was not.

cla import-plan¶

The same pipeline with the apply removed: it builds the plan, shows it, and never constructs anything that could write.

--out plan.json also writes the plan as JSON, for an approval gate to read. Sensitive values are replaced there too, by the same (sensitive) marker, with a "sensitive": 1 beside them saying why. If the file cannot be written the command exits 2 rather than reporting a success nobody can verify.

Exit codes¶

0 — applied, or nothing to do.
1 — you said no.
2 — the plan could not be built, a requested path was unreadable, or the plan has conflicts or errors.
3 — an apply failed partway.

Examples¶

See what would happen, change nothing:

cla import-plan ./cla-objects --diff

Apply without being asked:

cla import ./cla-objects -y

Make an installation match a directory exactly, deletions included:

cla import ./cla-objects --prune