One chart
Install the management plane with an exact chart version. Production values add HA replicas, CloudNativePG, Sentinel-backed Valkey, TLS, NetworkPolicy and backups. Astronomer uses Gateway API for ingress.
ASTRONOMER PRODUCT / ARCHITECTURE
Central intent. Local convergence.
Astronomer splits responsibility on purpose. PostgreSQL holds product intent and history. Each cluster’s Kubernetes API holds its live objects. An outbound agent connects the two, and Flux on each cluster does the reconciling, so a management-plane outage does not stop released work.
Alpha · Kubernetes v1.33–v1.35 · PostgreSQL 16–17 · Flux v2.9.601 / THE SHAPE
From your operators to your clusters.#
Operators use the console, the API or the CLI. The management plane decides and records. Agents in member clusters dial out, receive assignments and report status. Flux on each member cluster applies them.
02 / COMPONENTS
Inspect the parts.#
Select a component to see its job, its boundaries and what it depends on.
Management plane
Go API server and background worker, plus the React operator console. The server serves the API and holds agent connections; the worker runs durable operations and reconciliation. Several replicas can run, and reconciler leadership is held through a PostgreSQL session that is monitored and released if lost.
- Server, worker and frontend replica controls, disruption budgets and topology spread in the chart.
- Every mounted route is described by the published OpenAPI contract.
- Runs on a Kubernetes cluster you control.
PostgreSQL
PostgreSQL is the authority for Astronomer’s own records: users, sessions, RBAC, audit history, projects, cluster inventory, encrypted credentials, delivery intent and operation records. Committed work waits in outbox tables, so it survives a worker or queue failure.
- PostgreSQL 16 or 17; TLS required in production.
- Production profile: a three-instance CloudNativePG cluster with synchronous replication, or external services.
- A compact single-node profile uses one CloudNativePG instance.
Queue
Redis-compatible queues carry background jobs and schedules. They are transport, not the source of truth: losing the queue or restarting a worker cannot erase committed work, and replay is idempotent and bounded.
- Sentinel-backed Valkey in the production profile, or an external service.
- Queue, dead-letter and outbox views in the console.
- The bundled single instance is for development and small smoke environments.
Cluster agent
Runs in each adopted cluster and connects out to the management plane. It carries API proxying, logs, exec, service proxying and health, accepts only delivery assignments bound to its own cluster identity, and materializes a closed set of Flux objects in Astronomer-owned namespaces.
- No inbound access to the member cluster.
- Protocol and capability negotiation; unknown future agent versions are rejected before authentication.
- Mirrors selected resources, such as vulnerability reports, back to the management plane.
Flux on each cluster
Every adopted cluster runs the release-pinned Flux source, Kustomize and Helm controllers shipped with the Astronomer release. They converge the cluster to the last accepted assignment and keep doing so if the management plane is unavailable.
- Flux distribution v2.9.6 for the current release line, pinned by digest.
- Notification, image-reflector and image-automation controllers are excluded.
- Astronomer observes Flux conditions; it never writes Flux status.
Identity broker
Single sign-on runs through a bundled Dex, installed and configured from Astronomer. Connectors cover OIDC, Okta, Entra ID, GitHub, GitLab, Bitbucket Cloud, Google, SAML 2.0, LDAP and generic OAuth.
- Off by default in the Helm chart.
- Group mappings and SCIM provisioning on the Astronomer side.
- Has its own disruption budget in the production profile.
03 / WHO OWNS WHAT
Each kind of state has one authority.#
This split is why Astronomer can keep history and audit without pretending PostgreSQL replaces etcd, or that Flux is an account database.
| State | Authority | Rule |
|---|---|---|
| Users, RBAC, audit, projects, inventory, credentials, operations | PostgreSQL | Durable intent and history; secrets encrypted, hashed or referenced externally |
| Background execution | PostgreSQL outbox, carried by the queue | Queue loss or a worker restart cannot erase committed work |
| Live Kubernetes objects | Each member cluster’s API | Read live; edits use server-side apply without forcing ownership |
| Delivery convergence | Flux on each member cluster | Astronomer supplies desired objects and observes conditions |
| Optional CRD intent | Cluster, Project and AgentProfile resources | UI and API cannot silently overwrite CRD-owned fields |
04 / INTERFACES
One API under every client.#
The console, the astro CLI and generated TypeScript and Go clients all use the same public API, described by an OpenAPI contract that covers every mounted route. Long-running changes return durable receipts with idempotency, so a retry does not repeat the work.
With CRDs enabled, management.astronomer.io/v1alpha1 exposes Cluster, Project and AgentProfile intent for kubectl apply and GitOps workflows, with status conditions. The CRDs are an intent surface, not a mirror of every database object.
astro / cli
astro login
astro cluster list
astro cluster-agent list
astro delivery target preview
astro docs # open the live API reference05 / INSTALL AND AIR GAP
A Helm chart, your keys, your registry.#
You hold them
The chart ships no key material. Generate the signing and encryption keys once and keep them; back them up separately from the database.
Mirror one release
A release is one compatibility unit: chart, images, agent, Flux distribution and built-in bundles. Verify the signed release manifest, mirror every listed image to your private registry and install with no public registry access.
A release supports upgrades across its documented schema range. Read the release’s migration notes and back up the database and encryption key before upgrading.
NEXT STEP
Walk through the architecture with us.
Bring your cluster layout, network boundaries and identity provider. We will map them to Astronomer’s components.