Reconciliation

Reconciliation support is designed for SDKs used by infrastructure-as-code tools — Terraform providers, Kubernetes operators, Pulumi components. It is enabled per-language via the features.reconciliation field.

languages:
  - language: go
    features:
      reconciliation: terraform   # none | terraform | kubernetes | pulumi | custom
      driftDetection: true

What Generators Must Emit

When reconciliation is enabled, generators MUST produce:

State struct — a typed representation of desired vs. actual resource state, with fields annotated as mutable, immutable, or server-managed.

Reconcile function — compares desired state to actual, calls the appropriate Create/Update/Delete operations, and returns a typed result indicating whether the resource converged.

Drift detection helpers — field-level comparison functions that produce a diff between desired and actual state, excluding fields listed in codegenRules.reconciliation.ignoreDrift.

Generators SHOULD document which reconciliation modes they support. An unsupported mode MUST produce a warning, not a silent no-op.

Codegen Rules for Reconciliation

The codegenRules.reconciliation block applies cross-language and is required when any language target enables reconciliation.

codegenRules:
  reconciliation:
    mode: declarative           # declarative | imperative
    ignoreDrift:
      - status                  # server-managed; never reconcile
      - createdAt
      - updatedAt
      - etag
    immutableFields:
      - id                      # cannot change after creation
      - region
      - accountId

mode

Value	Description
declarative	Generators emit reconcile-loop functions that accept a desired state struct and converge to it. Terraform and Kubernetes operators typically use this model.
imperative	Generators emit CRUD helpers annotated with immutability constraints. Callers orchestrate the reconciliation logic themselves.

ignoreDrift

Fields whose server-side changes should never trigger reconciliation. Typically includes server-assigned timestamps, computed status fields, and ETags. Generators MUST exclude these fields from diff output.

immutableFields

Fields that cannot be updated after resource creation. Generators MUST mark these fields accordingly in the state struct and SHOULD emit a validation error if the caller attempts to modify them during an update.

Drift Detection

When driftDetection: true is set, generators emit standalone helpers that return a structured diff between two instances of a resource — independently of the reconcile loop. This is useful for plan-like operations (e.g. terraform plan) that preview changes without applying them.

// Example generated output (Go / terraform mode)
diff, err := client.Widgets.Diff(ctx, desired, actual)
if diff.HasChanges() {
    fmt.Println(diff.Summary())
}