Service Dependencies
Cadence is a self-contained distributed service, not a cluster add-on. The server defines no custom resources, requires no runtime access to a Kubernetes API server, and installs no controller or operator into the environment that hosts it. It runs on Kubernetes, VMs, or a laptop. The official Helm chart creates deployment resources through the Kubernetes API and can optionally create monitoring objects for CRDs that an operator has already installed.
The question this page answers is therefore not "what does Cadence install into your cluster" but "what else has to be running for a Cadence cluster to work." The short answer is: one database, and nothing else. Everything beyond that is opted into by enabling a feature.
For the server components themselves and how they are laid out, see Architecture requirements and Deployment topology.
Required dependencies
A persistence datastore
A Cadence cluster requires exactly one external service: a database. It holds workflow mutable state, event histories, task lists, domain metadata, and cluster configuration.
| Backend | Status | Notes |
|---|---|---|
| Cassandra | Production | CI covers 4.1 |
| MySQL | Production | CI covers 8.0 |
| PostgreSQL | Production | CI covers 17.4 |
| SQLite | Development only | Single node, cannot be clustered; SQLite's exclusive write locks mean one shared connection pool per process |
| MongoDB, DynamoDB | In progress | Plugins exist but are not yet complete |
Persistence sits behind a plugin interface, so the backend is a configuration choice rather than a build-time one. Versioned schemas and the cadence-cassandra-tool and cadence-sql-tool utilities ship with the server repository.
By default the same datastore also serves basic visibility, which lists and filters workflows by workflow ID, workflow type, status, and time range. A separate visibility backend is only needed for search on custom attributes, described below.
What Cadence does not require
The absence of these dependencies is a deliberate design choice, and it shapes what an adopter has to operate.
| Not required | Why |
|---|---|
| etcd, ZooKeeper, or Consul for the default deployment | Cluster membership and shard ownership use Ringpop, a gossip protocol compiled into the server binary. The optional Shard Manager currently introduces an etcd dependency. |
| An external message broker for core orchestration | Workflow and activity task dispatch runs through internal task lists owned by the Matching service. See Built-in task dispatch. |
| Runtime access to a Kubernetes API server, Cadence CRDs, or an operator | Cadence is not a cluster extension. The server has no Kubernetes client dependency and makes no Kubernetes API calls. Helm uses the API at install and upgrade time, but the running server does not. |
| A hosted control plane or vendor account | Cadence is Apache 2.0 and fully self-hosted. It sends no usage telemetry to the project and phones no service home. Operator-configured metrics stay within the adopter's monitoring system. See Sovereignty. |
| A separate service for cross-region replication | Cross-cluster replication moves data between Cadence clusters using a database-backed replication queue. It adds no third-party infrastructure. |
Peers discover each other through one of five Ringpop bootstrap modes: a static host list, a JSON file, DNS A records, DNS SRV records, or a custom provider. The only network requirement is that server nodes can reach one another and resolve a seed address.
Optional dependencies
Each of the following is introduced by turning on a specific feature. A cluster that uses none of them runs completely on its single datastore.
| Feature | Dependency | Required when |
|---|---|---|
| Advanced visibility | OpenSearch, Elasticsearch, or Pinot, and a message bus (Kafka) | Searching or filtering workflows by custom search attributes |
| Archival | Amazon S3, Google Cloud Storage, or a shared filesystem | Retaining closed workflow history beyond the domain retention period |
| Async workflow APIs | Kafka | Accepting workflow starts through a queue rather than a synchronous call |
| Metrics | Prometheus, StatsD, or M3 | Collecting server metrics |
| Authentication | An OIDC or OAuth provider, or a configured key pair | Enforcing caller identity at the Frontend |
| Web UI | The cadence-web service | Browsing workflows through a browser rather than the CLI |
| Shard Manager | etcd | Replacing default Ringpop-based shard ownership with the optional Shard Manager |
Advanced visibility requires a message bus
This is the dependency adopters most often miss, so it is worth stating plainly: enabling advanced visibility adds two services, not one.
The write path is asynchronous by design. When a workflow starts, closes, or is updated, the visibility record is published to a message topic rather than written to the index inline. The internal Worker service consumes that topic and bulk-writes batches into the search backend. This keeps index latency and availability off the critical path of starting a workflow, at the cost of a second piece of infrastructure and eventual consistency in search results.
In the open-source build that message bus is Kafka, and the same applies to Elasticsearch, OpenSearch, and Pinot alike. The producer sits behind a messaging.Producer interface, so organizations running a custom build can substitute their own transport without changing the visibility code.
Adopters who do not need custom search attributes should leave advanced visibility off and use basic visibility on the core datastore, which requires nothing extra.
Archival
Archival copies closed workflow histories and visibility records to cheaper long-term storage before retention deletes them. Providers are pluggable: Amazon S3, Google Cloud Storage, or a filesystem path. The filesystem provider writes to local disk, so the archive path must be writable from every host that can perform an archival, which includes the History service and not only the Worker. Visibility records are archived inline from History; history archival runs in a Worker system workflow by default but also falls back to an inline write from History when the history is small enough. The object-store providers need only credentials and network reachability. The Docker and Helm production-oriented configurations disable archival by default; the source development configuration enables it against a local filesystem.
Metrics
Metrics are emitted through a pluggable interface with implementations for Prometheus, StatsD, and M3. Prometheus scrapes the server; StatsD and M3 push to a collector. No metrics backend is needed for Cadence to function, only to observe it. See Monitoring.
Authentication
Cadence does not run an identity provider. The OAuth authorizer validates JWTs signed by an external OIDC or OAuth provider against a public key you configure, which is the path for normal callers.
There is one exception worth knowing: the CLI can sign admin JWTs itself using a configured private key, and the server recognizes these as internally issued. A deployment that only needs operator access can therefore enforce identity without standing up an external provider. See Identity and access management.
Internal components
These are parts of Cadence rather than dependencies on other systems. All four roles are built from the same binary and can run as one process for development or as four independently scaled deployments in production.
| Component | Role | Default ports |
|---|---|---|
| Frontend | Public API surface; authentication, rate limiting, routing | 7933 Thrift, 7833 gRPC |
| History | Owns workflow execution state and history shards | 7934 Thrift, 7834 gRPC |
| Matching | Task list management and task dispatch to workers | 7935 Thrift, 7835 gRPC |
| Worker | Internal system workflows, replication, visibility indexing, archival | 7939, membership only; the Worker serves no RPC API |
They communicate over YARPC (gRPC and Thrift) and locate each other through Ringpop. Two further components sit outside the server but are also Cadence rather than third-party infrastructure:
- Application workers are your processes that run workflow and activity code and poll task lists. Cadence never executes user code inside the server.
- cadence-web is the optional browser UI, deployed separately and talking to the Frontend over the normal API.
Dependency summary
| Dependency | Required | Introduced by |
|---|---|---|
| Datastore (Cassandra, MySQL, PostgreSQL) | Yes | The cluster itself |
| Search backend (OpenSearch, Elasticsearch, Pinot) | No | Advanced visibility |
| Kafka | No | Advanced visibility, async workflow APIs |
| Object store or shared filesystem | No | Archival |
| Metrics backend | No | Observability |
| OIDC / OAuth provider | No | Authentication |
cadence-web | No | Browser UI |
| Coordination service (etcd) | No | Optional Shard Manager |
| Runtime Kubernetes API access, Cadence CRDs, operator | No | The Helm deployment client uses the Kubernetes API; optional monitoring objects require their CRDs to be installed separately |
A minimal production cluster is therefore Cadence plus one database. A full-featured one adds a search backend, Kafka, an object store, a metrics backend, an identity provider, and the Web UI. Each is added independently and only when the corresponding feature is wanted.
Worked configuration examples for every combination live in config/, with matching Docker Compose files in docker/.