Pacto for platform engineers¶

You run the platform other teams deploy to. Pactify a service connects one service to delivery. This page is for the rest of the job: reading any team's contract to see what its service needs to run, such as its kind of workload, whether it keeps data, its APIs, the services it calls and its settings.

How a service is deployed stays in its own Kubernetes files. With delivery, pacto publish ships those files with each version and Flux applies them; the contract only points at them (publish.deploy). The contract says what the service is. 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[Files a plugin writes]
    DI --> CI[CI Gate]

1. Pull a service contract¶

pacto pull oci://ghcr.io/acme/contracts/payments-api: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/contracts/payments-api:2.1.0

See pacto explain for the output format.

3. Check for breaking changes¶

pacto diff oci://ghcr.io/acme/contracts/payments-api:2.0.0 \
  oci://ghcr.io/acme/contracts/payments-api: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/contracts/payments-api: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¶

If you would rather generate Kubernetes files from contracts than keep them by hand, pacto generate <name> runs a plugin program called pacto-plugin-<name> and writes the files it returns. The two official plugins generate parts of an existing contract: openapi-infer writes the OpenAPI document and schema-infer writes the configuration schema. Both need a pacto.yaml in the folder first. To generate deployment files, write your own plugin: a small program in any language that reads a contract as JSON and returns file contents. See Plugin development.

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 values below, such as shared/persistent, are short for the state.persistence.scope and state.persistence.durability fields, as pacto explain shows them. They describe the service. The table shows one sensible way to map them on Kubernetes:

`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

The contract leaves out upgrade strategy, shutdown timing, replica counts and autoscaling on purpose. Those stay in your Kubernetes files.