Pacto for Platform Engineers¶

You run the platform other teams deploy to. This guide shows how to pull a service's contract from a registry and read what it needs to run: workload type, state, interfaces, capabilities, dependencies and config schema. The contract says what the service is, not how to deploy it, so provisioning, scaling and wiring stay your decision.

Your workflow¶

flowchart LR
    R[OCI Registry] --> PL[pacto pull]
    PL --> E[pacto explain]
    PL --> DI[pacto diff]
    PL --> G[pacto graph]
    PL --> GEN[pacto generate]
    GEN --> K[Deployment Artifacts]
    DI --> CI[CI Gate]

1. Pull a service contract¶

pacto pull oci://ghcr.io/acme/payments-api-pacto:2.1.0

explain, diff, graph and generate accept oci:// references directly and cache what they download, so this pull step is optional.

A private repository needs credentials first: pacto login <registry>, or an already-authenticated gh for GHCR. Authentication gives the full resolution order.

2. Inspect it¶

pacto explain oci://ghcr.io/acme/payments-api-pacto:2.1.0

See pacto explain for the output format.

3. Check for breaking changes¶

pacto diff oci://ghcr.io/acme/payments-api-pacto:2.0.0 \
  oci://ghcr.io/acme/payments-api-pacto:2.1.0

It exits non-zero if breaking changes are detected. See Diff and change classification for the full reference and worked examples.

4. Resolve the dependency graph¶

$ pacto graph oci://ghcr.io/acme/payments-api-pacto:2.1.0
payments-api@2.1.0
├─ auth-service@2.3.0
│  └─ user-store@1.0.0
└─ notifications@1.0.0 (shared)

Pacto follows each dependency to its own contract in the registry, all the way down, and caches the results. Add --with-references to also show configuration and policy references, or --only-references to show only those.

5. Generate deployment artifacts¶

pacto generate <name> spawns a pacto-plugin-<name> binary and writes whatever it returns. Pacto ships no deployment-artifact plugin — the two official ones (schema-infer, openapi-infer) run inward, deriving contract inputs from files you already have. Generating Helm charts or Kubernetes manifests means writing the plugin, which is deliberately small — a binary that reads a contract as JSON on stdin and writes file descriptions on stdout, in any language. See the Plugin Development guide.

Mapping contracts to infrastructure¶

Workload type¶

`workload`	Kubernetes resource	Notes
`service`	Deployment or StatefulSet	Based on `state.type`
`job`	Job	Runs to completion
`scheduled`	CronJob	Schedule defined externally

State model¶

The scope/durability values below (e.g. shared/persistent) are shorthand for the state.persistence.scope + state.persistence.durability fields, matching the pacto explain display. These are platform-agnostic signals, not Kubernetes prescriptions — the mapping below is one reasonable interpretation for Kubernetes; the equivalent decision exists on Nomad, ECS or a custom platform:

`state.type`	`state.persistence`	Infrastructure
`stateless`	`local/ephemeral`	Deployment, no PVC, free to scale horizontally
`stateful`	`local/persistent`	StatefulSet + PVC, stable identity per replica
`stateful`	`local/ephemeral`	StatefulSet with emptyDir (stable identity, no durable storage)
`stateful`	`shared/persistent`	Network-attached or shared storage
`hybrid`	`local/persistent`	StatefulSet + PVC, tolerates cold starts
`hybrid`	`local/ephemeral`	Deployment with emptyDir, warm caches improve performance

Deployment mechanics the contract deliberately does not carry — upgrade strategy, graceful-shutdown timing, replica counts and autoscaling bounds — stay with your deployment tooling.