README
¶
Converge — declarative resource orchestration
Introduction • Quickstart • Demos • Docs • API reference • Contributing
Introduction
A declarative orchestration engine for platform teams building internal developer platforms (IDPs), self-service infrastructure APIs, and control planes: you describe the resources you want as specs, and Converge reconciles the world to match — composing, ordering, healing, and rolling up status. It is built for scale (millions of resources, thousands of reconciliations per second), simplicity (a single binary + a database), and reactivity (work is pushed, not polled).
It is provider-agnostic — the core knows no concrete resource type. You teach it a kind by applying a Kubernetes CRD-style manifest plus handler code in a worker, and that handler can do anything: run Terraform, a shell script or any binary, a Kubernetes Job, or any cloud/API call.
Like Crossplane and kro, it composes a resource into a graph of children and rolls their readiness up into the composite's status — but dependency edges and value flows are first-class declarative data, not imperative controller code, so you write the composition in Go, TypeScript, CEL, Starlark, or any external program. The logic that makes decisions is real code, not a templating dialect — see why workers are code, not YAML (and how an AI agent can write one for you from the demos). See how Converge compares to Terraform/Pulumi, K8s operators, and Temporal/Restate.
Architecturally it is a single binary over Postgres — a control plane and a broker mesh that any-language workers dial to pull work (topology). For the whole feature surface at a glance, see Converge at a glance.
Quickstart
One command stands up the whole thing — control plane + broker mesh + a worker + the web UI, against a throwaway Postgres — and runs a live demo. You only need just; just setup checks the rest of the toolchain (Go, Node, Docker):
git clone https://github.com/salesforce/converge.git && cd converge
just setup # (optional) verify Go/just/Node/Docker are installed
just install # install the converge/stdworker/conctl binaries onto your PATH (GOPATH/bin)
cd examples/demos/classic && just demo # builds everything, then spins the cluster + applies a demo
Then open the UI at http://localhost:8080 and watch a BOM fan out into accounts/VPCs/routes/TGW and converge to Ready. Ctrl+C tears it all down. Eight demos cover Go, CEL, Starlark, Terraform, any-language stdio, TypeScript, GitOps sync, and a Backstage golden path — see Demos below.
What it's great for
Example — a landing zone. One landingzone composer declares the shape once; a single
spec — { kind: landingzone, name: payments, spec: { accounts: 100, tier: pci } } — fans out
into 100 AWS accounts, each expanded in dependency order into the VPCs, routes, TGW,
guardrails, and IAM that different teams own. Converge flows each account's account_id into
its VPC, the vpc_id into its routes, and rolls it all up into one status — Ready only when
every child is healthy, else Degraded naming the culprit. Edit a kind and every landing zone
re-converges; no tickets, no central Terraform monolith.
More broadly, Converge fits when many dependent resources must be continuously reconciled, not provisioned once and forgotten:
- Self-service platform APIs — one high-level request expands into all the underlying cloud and API objects, so app teams declare what they want without learning the substrate.
- Ordered dependency graphs — resources come up in the right order, each one's outputs feeding the ones that depend on it, with no glue code to wire them.
- Fleet-wide drift correction — anything that drifts is detected and healed automatically, continuously, across millions of resources.
- Status you can trust — a composite is healthy only when everything under it is, and it tells you which piece is at fault when it isn't.
- Automatic follow-up actions — run a durable side effect whenever something changes (record a result, clean up, notify), without wiring a separate workflow.
Providers
A worker is just a client that dials the broker and pulls work, so it can be written in any
language. Converge ships two worker SDKs: sdk-go/converge for Go and
converge-worker-sdk for TypeScript.
You don't have to write a provider at all. Converge ships a default worker,
stdworker, hosting a set of generic built-in providers —
including stdio, which makes any external program (a bash script, a Python file, a binary
in any language) a resource kind, no SDK import or compile step.
A composer is just a provider too, so composition is equally pluggable — Go, declarative CEL rules, a kro-style CEL resource graph, or a Starlark program.
To implement your own, see docs/implementing-a-provider.md — defining a kind (provider handler code + CRD manifest), the input/output contract, value flows, status rollup, and terminal-vs-transient failure.
Demos
Eight runnable demos, each with a just demo and a walkthrough in its README (the Quickstart shows the flow):
- classic — a hand-written Go composer fans a BOM of teams into accounts/VPCs/routes.
- datadriven — the same DAG built as data, no Go: CEL rules, a kro-style CEL resource graph, and a Starlark program.
- stdterraform — a real
tofu apply(OpenTofu) on a module, outputs rolled into status, destroy on delete. - stdio — bridge any external program (any language, no Go) into a kind over the stdio protocol.
- stdshell — run a script carried inline in the resource spec.
- typescript — a composer + leaves written in TypeScript on the
converge-worker-sdkSDK. - gitops — reconcile a directory of manifests with
conctl sync, Argo-CD/Flux-style (apply + prune by app scope). - backstage — a Backstage golden-path template provisions a deployment through Converge; one
docker compose upbrings up the whole stack (Converge + a real Backstage UI, pre-wired).
Install & run
- Installation & running guide — running it for real against your own Postgres/RDS/Aurora, as images, or on Kubernetes/Helm.
- High availability & disaster recovery — surviving pod, database, and zone failures.
Binaries
Three shipped binaries (plus each demo's own worker):
converge— the server (control plane and/or broker tier).conctl— the kubectl-style CLI for the REST API.stdworker— the default worker, hosting the built-in std* providers.
Get them one of three ways:
- Install script — detects your OS/arch, downloads the matching release archive, verifies its checksum, and installs to your PATH:
curl -fsSL https://raw.githubusercontent.com/salesforce/converge/main/install.sh | sh - Prebuilt archives — download a per-platform tarball (linux/darwin × amd64/arm64) from the latest release; each contains all three binaries, with a
SHA256SUMSto verify. - From source —
just build(intobin/) orjust install(onto your PATH).
Status
Converge is v0.x and experimental: until a stable v1.0.0, nothing is guaranteed backwards-compatible and anything (API, protos, CLI, schema) may break between releases.
Contributing & license
Contributions are welcome — see CONTRIBUTING.md for the build/test workflow, coding conventions, commit/branching model, and how to open a PR. Please also read the Code of Conduct. To report a vulnerability, see SECURITY.md.
Licensed under the Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
conctl
command
Command conctl is the kubectl-style CLI for the converge control plane.
|
Command conctl is the kubectl-style CLI for the converge control plane. |
|
converge
command
|
|
|
gen-types
command
Command gen-types generates provider-side TYPES from a kind's CRD manifest — the schema-first source of truth.
|
Command gen-types generates provider-side TYPES from a kind's CRD manifest — the schema-first source of truth. |
|
stdworker
command
Command stdworker is the DEFAULT converge worker: a first-class, shipped binary that hosts converge's built-in general-purpose ("std") providers.
|
Command stdworker is the DEFAULT converge worker: a first-class, shipped binary that hosts converge's built-in general-purpose ("std") providers. |
|
examples
|
|
|
demos/classic/account
Package account implements the account kind under the ONE converge.Provider contract: a single provider that serves account/v1 and routes every reaction the kind declares through Work.
|
Package account implements the account kind under the ONE converge.Provider contract: a single provider that serves account/v1 and routes every reaction the kind declares through Work. |
|
demos/classic/classicbom
Package classicbom implements the compose + rollup reactions for kind=classicbom.
|
Package classicbom implements the compose + rollup reactions for kind=classicbom. |
|
demos/classic/cmd/worker
command
Command worker is the CLASSIC demo's dumb worker: the classicbom composer (a hand-written Go composer that fans a BOM-of-teams into per-FD/per-team resources) + its child kinds (account, networking: vpc/route/tgw) + the statussink reactor.
|
Command worker is the CLASSIC demo's dumb worker: the classicbom composer (a hand-written Go composer that fans a BOM-of-teams into per-FD/per-team resources) + its child kinds (account, networking: vpc/route/tgw) + the statussink reactor. |
|
demos/classic/fault
Package fault is the classic demo's simulated-failure knob: a tiny, shared fault injector the leaf workers (account, networking: vpc/route/tgw) consult before doing their stub work.
|
Package fault is the classic demo's simulated-failure knob: a tiny, shared fault injector the leaf workers (account, networking: vpc/route/tgw) consult before doing their stub work. |
|
demos/classic/networking
Package networking implements the three networking kinds — VPC, TGW, Route — as providers: each is a Manifest (pure data) + reaction Handlers (code), sharing one stub backend.
|
Package networking implements the three networking kinds — VPC, TGW, Route — as providers: each is a Manifest (pure data) + reaction Handlers (code), sharing one stub backend. |
|
demos/classic/statussink
Package statussink implements the REFERENCE reactor: it uploads a watched resource's rolled-up status to an object store when that resource crosses a subscribed lifecycle transition (typically 'synced' = "rolled up").
|
Package statussink implements the REFERENCE reactor: it uploads a watched resource's rolled-up status to an object store when that resource crosses a subscribed lifecycle transition (typically 'synced' = "rolled up"). |
|
demos/datadriven/celbom
Package celbom is the DECLARATIVE-RULES counterpart to the shipped Starlark composer providers/stdstarlark: the same "BOM of teams × policies → children DAG" composer, but the composition is expressed as RULE DATA + CEL predicates instead of an embedded Starlark program.
|
Package celbom is the DECLARATIVE-RULES counterpart to the shipped Starlark composer providers/stdstarlark: the same "BOM of teams × policies → children DAG" composer, but the composition is expressed as RULE DATA + CEL predicates instead of an embedded Starlark program. |
|
demos/datadriven/cmd/worker
command
Command worker is the DATA-DRIVEN demo's worker: like every converge worker it declares its providers, installs a signal ctx, and calls converge.Serve (which reads config from the env and owns dialing, reconnect, config, readiness, and drain).
|
Command worker is the DATA-DRIVEN demo's worker: like every converge worker it declares its providers, installs a signal ctx, and calls converge.Serve (which reads config from the env and owns dialing, reconnect, config, readiness, and drain). |
|
demos/datadriven/fakeapp
Package fakeapp is the simulation leaf that CONSUMES values flowed from TWO upstream resources — the downstream half of the dependency + value-flow demo.
|
Package fakeapp is the simulation leaf that CONSUMES values flowed from TWO upstream resources — the downstream half of the dependency + value-flow demo. |
|
demos/datadriven/fakedb
Package fakedb is a second simulation PRODUCER leaf (sibling of fakevpc): on reconcile it derives a deterministic fake DB endpoint from its spec's account_id and writes it to status.
|
Package fakedb is a second simulation PRODUCER leaf (sibling of fakevpc): on reconcile it derives a deterministic fake DB endpoint from its spec's account_id and writes it to status. |
|
demos/datadriven/fakek8sjob
Package fakek8sjob is a simulation leaf that fakes "run a team's Kubernetes Job".
|
Package fakek8sjob is a simulation leaf that fakes "run a team's Kubernetes Job". |
|
demos/datadriven/faketerraform
Package faketerraform is a simulation leaf that fakes "run a team's Terraform bundle from S3".
|
Package faketerraform is a simulation leaf that fakes "run a team's Terraform bundle from S3". |
|
demos/datadriven/fakevpc
Package fakevpc is a simulation leaf that PRODUCES an id in its status, the upstream half of a dependency + value-flow demo (its consumer is providers/fakeapp).
|
Package fakevpc is a simulation leaf that PRODUCES an id in its status, the upstream half of a dependency + value-flow demo (its consumer is providers/fakeapp). |
|
internal
|
|
|
api
Package api is the HTTP layer for Converge.
|
Package api is the HTTP layer for Converge. |
|
awsauth
Package awsauth wires AWS IAM database authentication (RDS / Aurora) into the Postgres connection paths.
|
Package awsauth wires AWS IAM database authentication (RDS / Aurora) into the Postgres connection paths. |
|
broker
Package broker is the server half of the universal work-distribution API.
|
Package broker is the server half of the universal work-distribution API. |
|
conctl
Package conctl implements the converge control-plane CLI — a kubectl-style client for the REST API (apply/get/list/delete over resources, kind manifests, provider configs, reactor bindings, and the cluster registry).
|
Package conctl implements the converge control-plane CLI — a kubectl-style client for the REST API (apply/get/list/delete over resources, kind manifests, provider configs, reactor bindings, and the cluster registry). |
|
conctl/apiclient
Package apiclient provides primitives to interact with the openapi HTTP API.
|
Package apiclient provides primitives to interact with the openapi HTTP API. |
|
conctl/apiclient/spectool
command
Command spectool down-converts the converge OpenAPI 3.1 golden spec to an equivalent 3.0.3 document that oapi-codegen v2 can consume.
|
Command spectool down-converts the converge OpenAPI 3.1 golden spec to an equivalent 3.0.3 document that oapi-codegen v2 can consume. |
|
engine
Package engine assembles the process from composable DUTIES over one shared Postgres.
|
Package engine assembles the process from composable DUTIES over one shared Postgres. |
|
health
Package health serves the Kubernetes probe endpoints — /healthz, /livez, and /readyz — for every Converge pod regardless of role.
|
Package health serves the Kubernetes probe endpoints — /healthz, /livez, and /readyz — for every Converge pod regardless of role. |
|
kindschema
Package kindschema is the server-side schema tooling for kind manifests: it derives a Go type's JSON Schema (authoring), decodes stored schema bytes back into a validator (the round-trip huma can't do on its own output), hashes a manifest's schemas for the stability gate, and lints an in-place re-publish for backward compatibility.
|
Package kindschema is the server-side schema tooling for kind manifests: it derives a Go type's JSON Schema (authoring), decodes stored schema bytes back into a validator (the round-trip huma can't do on its own output), hashes a manifest's schemas for the stability gate, and lints an in-place re-publish for backward compatibility. |
|
meshpb/meshpbconnect
Package converge.mesh.v1 is the INTERNAL broker↔broker mesh API — NOT part of any worker SDK's contract.
|
Package converge.mesh.v1 is the INTERNAL broker↔broker mesh API — NOT part of any worker SDK's contract. |
|
metrics
Package metrics wires OpenTelemetry metrics for the converge control-plane and broker tiers.
|
Package metrics wires OpenTelemetry metrics for the converge control-plane and broker tiers. |
|
model
Package model holds the kind-agnostic CORE contract: the kind-identity primitives (Kind, KindVersion, ResourceRef, ResourceManifest), the reaction request/response and composition value types the control plane builds from a DB row and applies (Resource, ReactionRequest, Outcome, ChildSpec, DepEdge, …), the author-facing Trigger/Transition enums, the config-merge helpers, the per-stage wire DTOs, the CRD-style KindManifest with its validation lattice, and the StageDispatcher seam.
|
Package model holds the kind-agnostic CORE contract: the kind-identity primitives (Kind, KindVersion, ResourceRef, ResourceManifest), the reaction request/response and composition value types the control plane builds from a DB row and applies (Resource, ReactionRequest, Outcome, ChildSpec, DepEdge, …), the author-facing Trigger/Transition enums, the config-merge helpers, the per-stage wire DTOs, the CRD-style KindManifest with its validation lattice, and the StageDispatcher seam. |
|
providers/stdcel
Package stdcel is the GENERIC, kro-style composer: it turns a RESOURCE GRAPH DEFINITION expressed entirely as DATA — a set of child resources whose fields are CEL expressions over the instance's spec and over each other — into a child DAG, with no per-kind Go.
|
Package stdcel is the GENERIC, kro-style composer: it turns a RESOURCE GRAPH DEFINITION expressed entirely as DATA — a set of child resources whose fields are CEL expressions over the instance's spec and over each other — into a child DAG, with no per-kind Go. |
|
providers/stdio
Package stdio is the GENERIC provider: it lets an external program — written in ANY language, with no converge Go SDK — act as a converge resource kind via a stdin/stdout JSON protocol.
|
Package stdio is the GENERIC provider: it lets an external program — written in ANY language, with no converge Go SDK — act as a converge resource kind via a stdin/stdout JSON protocol. |
|
providers/stdshell
Package stdshell is a REAL leaf provider that runs a user-supplied script.
|
Package stdshell is a REAL leaf provider that runs a user-supplied script. |
|
providers/stdstarlark
Package stdstarlark is the GENERIC Starlark composer: it runs an operator-supplied Starlark program — shipped as a zip of .star files in the providerconfig BUNDLE — that fans a resource's spec out into a child DAG (children + edges + provider configs), with no per-kind Go.
|
Package stdstarlark is the GENERIC Starlark composer: it runs an operator-supplied Starlark program — shipped as a zip of .star files in the providerconfig BUNDLE — that fans a resource's spec out into a child DAG (children + edges + provider configs), with no per-kind Go. |
|
providers/stdterraform
Package stdterraform is a REAL leaf provider that runs a user's Terraform module as a converge resource: its spec points at a module (a *.tar.gz in S3, GCS, Azure Blob, or over HTTPS, or a git repo), and per task the worker fetches it, injects a state backend keyed to the resource, and runs a real `terraform apply` (or `terraform destroy` on delete).
|
Package stdterraform is a REAL leaf provider that runs a user's Terraform module as a converge resource: its spec points at a module (a *.tar.gz in S3, GCS, Azure Blob, or over HTTPS, or a git repo), and per task the worker fetches it, injects a state backend keyed to the resource, and runs a real `terraform apply` (or `terraform destroy` on delete). |
|
runtime
Package runtime is the per-pod runtime that drives providers.
|
Package runtime is the per-pod runtime that drives providers. |
|
shardutil
Package shardutil holds the shard-space size constant and tiny helpers for assigning pod-to-shard ownership.
|
Package shardutil holds the shard-space size constant and tiny helpers for assigning pod-to-shard ownership. |
|
specschema
Package specschema is the SINGLE server-side schema validator for resource specs, providerconfig documents, and operate-verb inputs.
|
Package specschema is the SINGLE server-side schema validator for resource specs, providerconfig documents, and operate-verb inputs. |
|
store
Package store wraps the sqlc-generated dbq package with the higher-level operations the rest of the codebase uses: sorted+typed bulk upserts, provider-friendly task abstractions, polymorphic outbox append, soft-delete primitives.
|
Package store wraps the sqlc-generated dbq package with the higher-level operations the rest of the codebase uses: sorted+typed bulk upserts, provider-friendly task abstractions, polymorphic outbox append, soft-delete primitives. |
|
wire
Package wire is the CORE-SIDE converter between the internal/model stage request/response types and their typed proto wire forms (sdk-go/workerpb — the public worker contract).
|
Package wire is the CORE-SIDE converter between the internal/model stage request/response types and their typed proto wire forms (sdk-go/workerpb — the public worker contract). |
|
pkg
|
|
|
drainctx
Package drainctx provides the graceful-drain context split shared by every long-running Converge driver — the worker runner (sdk-go/converge) and the broker's work + reactor dispatchers (internal/runtime).
|
Package drainctx provides the graceful-drain context split shared by every long-running Converge driver — the worker runner (sdk-go/converge) and the broker's work + reactor dispatchers (internal/runtime). |
|
spiffeauthz
Package spiffeauthz is the shared, domain-free SPIFFE-ID allowlist primitive: parse a comma-separated list of spiffe://… IDs into a matcher, and check a verified peer's certificate against it.
|
Package spiffeauthz is the shared, domain-free SPIFFE-ID allowlist primitive: parse a comma-separated list of spiffe://… IDs into a matcher, and check a verified peer's certificate against it. |
|
tlsreload
Package tlsreload hot-reloads TLS material — a keypair and an optional CA pool — from files that are AUTO-INJECTED and rotated underneath a running process (cert-manager, a SPIFFE sidecar, a mounted k8s Secret).
|
Package tlsreload hot-reloads TLS material — a keypair and an optional CA pool — from files that are AUTO-INJECTED and rotated underneath a running process (cert-manager, a SPIFFE sidecar, a mounted k8s Secret). |
|
wirelimits
Package wirelimits holds Connect wire-size limits shared by BOTH ends of the WorkerService — the broker handler (internal/broker) and the worker client (sdk-go/converge).
|
Package wirelimits holds Connect wire-size limits shared by BOTH ends of the WorkerService — the broker handler (internal/broker) and the worker client (sdk-go/converge). |
|
sdk-go
|
|
|
converge
Package converge is the CLIENT SDK for building a converge worker — a normal, high-level library shaped like a cloud SDK, not a framework.
|
Package converge is the CLIENT SDK for building a converge worker — a normal, high-level library shaped like a cloud SDK, not a framework. |
|
workerpb/workerpbconnect
Package converge.worker.v1 is the PUBLIC worker↔broker work-distribution API — the SINGLE cross-language contract every worker SDK (Go, and future TypeScript / Java / … bindings) wraps.
|
Package converge.worker.v1 is the PUBLIC worker↔broker work-distribution API — the SINGLE cross-language contract every worker SDK (Go, and future TypeScript / Java / … bindings) wraps. |
|
internal/demoruntime
Package demoruntime is the TEST-ONLY constructor bridge that returns each demo provider as a converge.Provider for the in-process engine harness (test/internal/inproc).
|
Package demoruntime is the TEST-ONLY constructor bridge that returns each demo provider as a converge.Provider for the in-process engine harness (test/internal/inproc). |
|
internal/inproc
Package inproc holds the TEST-ONLY in-process reaction executor.
|
Package inproc holds the TEST-ONLY in-process reaction executor. |
|
internal/noop
Package noop implements a Worker-only kind that does no external work: it sleeps for a configured delay and reports success.
|
Package noop implements a Worker-only kind that does no external work: it sleeps for a configured delay and reports success. |
Click to show internal directories.
Click to hide internal directories.