Compute
Plan, apply and read back a change
Inspect what exists, review a change plan before it expires, apply it idempotently, then read back the resource state and its receipt. The same change never applies twice.
Before you start
You need an administration credential for the account you are changing, and the resource you intend to change. Work keys cannot make configuration changes.
Every configuration change follows the same six steps: describe, inspect, plan, approve where required, apply, read back. Learn it once and every resource family behaves the same way.
Inspect current state first
Describe the resource family, then inspect the specific resource. Never plan against what you remember.
Inspection returns the current value and its version. That version is what your plan is built against, and it is what a later apply checks.
Review the plan before it expires
A plan is a reviewable document, not a submitted change. It names each resource, its current value, its desired value, and whether it needs an approval.
Plans expire. Read one while it is current, and apply it before its validity window closes, or build a new one.
Read the plan for effects you did not intend. An invitation, an external write and a payment are not undone by a later rollback, so catch them here.
Apply idempotently
Apply the plan by its identifier, and quote the digest you reviewed.
lithi configuration apply --sandbox <plan-id> --expected-digest <digest>
The digest binds the apply to the exact plan you read. If the plan changed after you read it, the apply refuses rather than applying something else.
Sending the same apply twice is safe. An exact replay returns the prior result. The same identity with a different payload is treated as equivocation and refuses.
Read back the returned state
Each resource returns its own state. Read them individually, not as one number.
| State | What it means | What to do |
|---|---|---|
PLANNED | In the plan, not yet started | Apply the plan |
WAITING_APPROVAL | Needs a separate approval | Ask the approver to decide |
READY | Approved and queued | Wait |
APPLYING | In progress | Wait |
APPLIED_UNVERIFIED | Written, not yet confirmed | Read back again |
VERIFIED | Written and confirmed | Done |
ALREADY_MATCHED | Desired value was already in place | Done, nothing changed |
REFUSED | Rejected with a reason | Change the input, replan |
CONFLICT | Resource moved since the plan | Inspect, replan, apply |
RETRYABLE | Transient failure | Send the same apply again |
REVOKED | Authority withdrawn before it applied | Get authority, replan |
ROLLED_BACK | Reverted to its prior value | Read back, then decide |
The change as a whole returns one of four states: COMPLETE, PARTIAL_WITH_NEXT_ACTION, REFUSED or EXPIRED. Never read the aggregate without reading the per-resource states behind it.
Confirm success
COMPLETE with every resource at VERIFIED or ALREADY_MATCHED is a finished change.
Keep the receipt reference the response returns. It is what you quote to support, and it explains later what changed and when.
The response also carries a request_id, an observed_at time and a valid_until time. A read-back older than valid_until is stale, so read again rather than trusting it.
If the apply does not complete
PARTIAL_WITH_NEXT_ACTION means some resources verified and the rest name what to do. Resume from those next actions.
EXPIRED means the plan aged out before the apply finished. Inspect current state and build a new plan; the verified resources stay verified.