Skip to main content
Limited Release. The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you’re on the latest EDK version before starting new projects.
The EDK compares authored TypeScript with state and the live Elementum target, then shows the changes required to make them match.

​
Plan and apply workflow

Run the workflow from the marked <instance>/<organization> workspace:
Each command has a distinct purpose:
  1. npx tsc --noEmit checks TypeScript without generating JavaScript.
  2. elementum plan builds the current source, then previews the EDK changes for the selected Elementum target.
  3. elementum apply builds again, then applies the reviewed changes.
  4. A final elementum plan should report no changes.
You do not need to run elementum build before plan or apply. Use it when you want to generate and inspect .tf/out/ without contacting the platform. Use --skip-build only when you deliberately want plan or apply to use the existing .tf/out/ output.

​
Review the complete workspace

plan and apply always operate on the full organization workspace. You can pass the organization root or any nested path:
The nested path only helps locate the marked organization root. It does not limit the plan to one App, Element, or file. Before applying, account for every reported operation:
  • Add creates a resource that is configured but not bound in state.
  • Change updates a resource in place. The plan may instead report a replacement when the changed property cannot be updated.
  • Destroy removes a resource that remains in state but is absent from the built configuration.
Unexpected replacements and destroys are blockers. Resolve them before applying.

​
Apply and confirm the result

Apply only the plan you reviewed:
Then plan again:
A converged workspace produces a zero-change plan. If the EDK still proposes changes, do not repeatedly apply. Compare the remaining diff with the authored source, generated diagnostics, selected profile, and backend binding.

​
Backend and state

Behind the EDK workflow, OpenTofu state provides the durable mapping between authored labels and live Elementum objects. Losing or using the wrong state can make existing objects appear new. For compatibility, an organization workspace without backend.tf uses a committed root terraform.tfstate through a generated local backend. This supports a single-author workspace but does not provide locking. Avoid concurrent plans or applies. Shared workspaces and CI should commit a non-secret <orgRoot>/backend.tf that declares a remote backend with verified locking. During build, the EDK copies that declaration to .tf/out/backend.tf. The backend locks state during plans, applies, pulls, renames, and repairs. Never commit:
  • .tf/ or .terraform/
  • Backend credentials
  • Saved plan files
  • Recovery snapshots
Keep credentials in the backend’s normal environment or workload-identity chain. EDK does not provision backend infrastructure and does not accept secrets in backend.tf.

​
Migrate or recover state

Use the guarded migration command when moving local state to a declared remote backend or changing remote backends:
The migration creates an ignored recovery snapshot, verifies the result, and requires a final zero-change plan. Follow the exact rollback instructions printed if it fails.
If state is lost, do not run apply. The EDK can interpret live resources as new and attempt to create duplicates.
Restore the recovery snapshot when available. Otherwise, refresh organization references and re-pull each existing managed root:
Pull verifies the expected state bindings and requires a clean follow-up plan without changing the live resources.

​
Apply versus environment promotion

elementum plan and elementum apply reconcile authored source with the organization and environment selected by authentication. They do not perform Elementum’s cross-environment promotion workflow. After testing an EDK change in a lower environment, use the platform promotion workflow to move it to another environment. If the promotion reports missing environment configuration, the /elementum-deployments playbook can review and configure it from the admin URL or asyncTaskId. See Authentication for target selection and Playbooks for the promotion and UAT playbooks.