IaC sidecar API

Ten paths, all under /v1 except the liveness probe.

GET /v1/jobs/{job_id} returns the job. All keys are always present; started_at, finished_at, result, and error are null until they become meaningful.

kind is one of init, validate, plan, show, apply, import, state_resource_ids, scope_resource_ids. status moves through four values:

The two failure planes are deliberately distinct, and a caller must tell them apart.

Polling an unknown or expired job is 404, and a job_id that is not a valid UUID is 422. The bundled implementation keeps terminal jobs in memory for its job_ttl (one hour) and holds no job across a restart, so a client must treat an unexpected 404 as job loss and resubmit if the work still matters.

The core polls every services.iac.job_poll_interval seconds and gives up after services.iac.job_timeout (3600 seconds by default). That timeout has to cover both the queue wait and the command itself, and against the bundled implementation it is the only limit: when an engine command hangs, the core stops waiting once the timeout elapses, while the job stays running and the command keeps running in the sidecar until it exits on its own.

Only the commands that reach a cloud API need to know which scope they run against, and only those carry scope_id and terraform_provider:

Generated provider blocks do not name a scope. So where a cloud exposes a provider-level environment variable that names one, the implementation injects scope_id into the engine’s environment for that command only, picking the variable from terraform_provider:

Only Azure and GCP have such a variable. An AWS account is implicit in the credentials the provider resolves, and an OCI compartment or a Kubernetes namespace is a resource argument rather than a provider setting, so no environment variable redirects a command to one. For those three the bundled implementation injects nothing: the command runs against whatever scope the deployment’s ambient credentials and configuration select, and making those agree with scope_id is the deployment’s responsibility. The pair stays required on the wire so the intended scope is always stated, and so an implementation that can enforce it has what it needs.

An implementation may scope a command by another mechanism instead — an AWS AssumeRole into the account, a provider alias, a credential broker — as long as the command runs against scope_id. Callers need to know nothing about which mechanism was used.

Where the overlay is applied it sits on top of the service’s own environment, so it wins over an ARM_SUBSCRIPTION_ID set on the container. Ambient provider credentials are otherwise untouched.

On Azure that variable is also the azurerm backend’s, so init resolves the state storage account in scope_id’s subscription. A deployment keeping state outside that subscription has to name `subscription_id in its backend configuration; see Backend minimums.

POST /v1/import/scope-resource-ids is the exception: it launches no subprocess, so there is no environment to overlay. Its scope_id is the argument of the inventory query itself — the subscription, project, or account whose contents are listed.

Two endpoints answer the question "what already exists here that Terraform does not manage yet?" without running a state-mutating command. Both follow the job model, and on success both put a JSON array of identifier strings in the result’s stdout as a string, the way show returns the plan JSON, so a caller reads it with one JSON parse. The implementation normalizes both lists so they are directly comparable, and a caller typically diffs them to decide which existing resources still need an import job.

POST /v1/import/state-resource-ids runs state pull and extracts the provider-assigned identifier of every managed resource instance in the state — its arn attribute when it has one, otherwise its id — deduplicated. An instance with neither contributes nothing. An empty state answers []. A state pull that exits 0 but prints something other than a state document ends the job with exit code 1 and state pull returned an unparsable state document; a non-zero state pull is passed through with its own exit code, its stderr, and an empty stdout. The workspace must already be initialised.

POST /v1/import/scope-resource-ids talks to each cloud’s inventory API directly over HTTPS. No az, gcloud, or aws binary is involved, and none is present in the bundled image. Tokens come from the official auth libraries reading the same ARM_*, GOOGLE_*, and AWS_* variables the engine’s providers use, so most deployments that can run plan can run discovery unchanged.

oci and kubernetes are answered with exit code 2 and no scope discovery for provider '<provider>' in stderr, with the provider name quoted. That is a deliberate outcome, not a crash: the job still ends succeeded, and the exit code tells the caller the provider is unsupported rather than that a cloud call failed.

The contract’s own description of this endpoint’s scope_id field enumerates only Azure, GCP, and AWS, omitting both oci and kubernetes even though the schema’s provider enum accepts them. The omission is consequential here, unlike in the generic scope_id description: these are exactly the two providers that produce the exit code 2 above, so the field description reads as though they cannot be sent at all, when in fact they are accepted and answered with a negative result.

The core does not call this endpoint today. The generated client contains both operations, and the core defines the import operation type, but the mode is not wired into a session pipeline. See Import infrastructure.

The service does not choose where state goes. init reads the backend from the workspace it is handed, and preparing that workspace is the caller’s job. Kumoss’s core writes a backend_override.tf into the workspace before calling init, pinning state to the object store it already holds credentials for. The engine merges *_override.tf over the rest of the configuration, so an override both introduces a backend where the workspace declares none and replaces one that it does declare — any caller can use the same trick.

IAC_BACKEND_CONFIG is the escape hatch for a deployment that owns the decision instead. Set it to the path of a backend configuration file, .hcl or .tfbackend, and init runs with -backend-config=<path>, with the backend type still coming from the workspace’s own terraform { backend } block. The path is either absolute, for a file mounted into the container, or relative to the workspace, for one the target repository carries at a fixed place. Unlike the engine binary, the service does not check it at startup: under the second form the file exists only once a repository has been cloned into a workspace, so a wrong path fails on init, in that job’s stderr. The values in this file win over the core’s backend_override.tf key by key, and the override’s remaining keys survive the merge, so do not combine the two: set storage.terraform_state_bucket: "" whenever IAC_BACKEND_CONFIG is set. See Configure state backends.

Reinitialization. init always runs -reconfigure, so a workspace whose backend changed between calls is rebound to the new one instead of failing with "Backend configuration changed", which -input=false could not answer interactively. State already in the target backend is adopted; state held under the previous backend is not migrated. Move it yourself if it matters.

The full picture, including which of the three models to pick, is in Configure state backends.

The bundled image ships both engines and IAC_BINARY selects one at runtime, with no rebuild needed to switch:

The service itself is engine-agnostic: it only shells out to init, validate, plan, show, apply, import, and state pull, whose flags are identical across both engines, so any Terraform-compatible engine on PATH or at an absolute path works.

Three things to know when pointing a workspace previously managed by Terraform at the default OpenTofu engine:

The service operates on workspace_path as visible inside its own container. The contract makes no assumption about how the workspace got there. The compose deployment mounts a named workspaces volume at /workspaces in both the core and the IaC containers, so the core writes the cloned repository there and references the same path when submitting jobs. Other deployments may use a PersistentVolumeClaim, an NFS mount, object storage, or an upload endpoint — same contract, different mechanics.

The bundled image runs as an unprivileged user, kumoss, uid and gid 10001 by default, set by the KUMOSS_UID and KUMOSS_GID build arguments. The engine executes provider plugins and provisioners from generated code, so it must not run as root.

Because the engine writes .terraform/, .terraform.lock.hcl, plan files, and state next to the configuration, workspace directories must be writable by that uid. In the compose stack this holds because the core image is built with the same two build arguments and also runs as kumoss, so everything the core clones is owned by the same user. Override the two arguments together or not at all.

The bundled implementation reads four groups of variables.

Everything else is a property of the service rather than of a deployment: job_ttl, how long a terminal job stays pollable, and log_level. The per-cloud minimum sets and every credential variable are in Terraform providers; Cloud credentials for the IaC engine covers how they reach the container.

The implementation-agnostic Schemathesis suite at contracts/conformance/iac/ runs against any implementation of this contract, in-tree or your own. Point --service-url at a running instance:

--service-token is needed only if the implementation enforces authentication. Both values may also come from KUMOSS_IAC_URL and KUMOSS_IAC_TOKEN.

The suite generates requests from the OpenAPI document and checks that every status the service answers is one the contract documents for that operation, and that response bodies match the declared schemas. It does not check that every documented status is reachable — a status the implementation never emits, such as the submission-time 503, leaves the run green. Nor does it check that the commands the jobs run produce accurate output for your modules, cloud-provider authentication semantics, or behaviour under concurrency.

The bundled implementation has its own unit test suite, separate from this one; see Development.