Deploying the Multigres Operator

Running Postgres at scale is hard. Managing database connections, owning High Availability and failover, disaster recovery, scaling read replicas, and taking backups across availability zones is a full time job. Each piece is well understood in isolation, but keeping them working together reliably across availability zones is difficult.

Multigres is a scalable operating system for Postgres: it holistically manages your Postgres instances and gives you sharding, connection pooling, automatic failover, and backup orchestration.

We deploy Multigres with Kubernetes, which is the industry standard for managing infrastructure at scale. As many can attest, deploying and managing Kubernetes comes with its own set of challenges. That is exactly where the multigres operators come in.

Demo Video:

What is an operator?

An operator is a Kubernetes controller that runs inside your cluster and manages the lifecycle of a complex application on your behalf. Instead of manually applying configuration changes, scaling resources, or handling failures, you declare the state you want and the operator continuously works to make it so.

The Multigres operator is what turns a single YAML declaration into a fully orchestrated, multi-zone Postgres cluster.

What the operator manages

The operator manages pods: the individual containers running each component. The operator is primary-aware, meaning it knows which pod holds the active Postgres primary at any given moment. In practical terms, primary-awareness ensures the operator always acts on standbys first and the primary last when restarting pods for a config change, scaling the cluster, or performing failover. By acting on the primary last, the operator guarantees safe operations without interrupting writes on the primary.

A Multigres cluster is made up of several components that work together across availability zones. The operator provisions the following components from a single MultigresCluster manifest:

GlobalTopoServer is a managed etcd cluster that records the topology state: which databases exist, which cells they live in, and where every component is registered. Cells are user-defined groupings that map to availability zones. In a multi-zone deployment, the topology splits into a global server for cluster-wide state and per-cell servers for local discovery, so a partitioned cell keeps operating against its own local view.

MultiAdmin is the management plane for the cluster, including a web UI.

MultiGateway speaks the Postgres wire protocol. Your application connects to a gateway, which forwards queries to the right MultiPooler over gRPC. Adding more gateways scales Multigres’ connection capacity horizontally.

MultiOrch: the orchestrator. One set of MultiOrch instances per shard, running across cells. It watches replication health, appoints leaders through a consensus protocol, runs failovers, and coordinates bootstrap, backup, restore, and scaling events. When you apply the manifest, MultiOrch runs bootstrap as a consensus-backed election. This is the same code path as every later failover- so, there is no separate provisioning script that can race with itself.

Postgres pods themselves, managed by pgctld which owns the local Postgres process and MultiPooler. One pooler per Postgres instance.

Deploying on EKS

Amazon EKS provides a managed Kubernetes control plane across AWS availability zones, which we use as the foundation for a multi-zone Multigres cluster. Each cell in Multigres maps to a real AZ. A zone failure can take down one cell, while the other two keep operating without interruption. The Multigres EKS guide covers everything you need to stand this up: prerequisites, zone labels, storage, S3 backup identity, and the full cluster manifest.

The short version of what you need is a kubeconfig pointed at an EKS cluster with the operator installed and a manifest like this.

In the Manifest linked to above, you’ll see three cells, each mapped to a real AWS availability zone. AT_LEAST_2 durability means every committed write is acknowledged by one standby (one primary and one standby). The operator infers everything else from the templates: resource limits, gateway configuration, topo server sizing — and builds the full topology.

Run kubectl apply -f demo-multi-az.yaml and then kubectl get pods -w. Within a minute you have a global topo server, MultiAdmin, MultiGateway, MultiOrch across three zones, and Postgres pool pods across three zones.

You should eventually see pods for global topo, multiadmin, multigateway, multiorch, and three poolers.

Verify The Cluster

Once deployed, check the Multigres resources like this:

kubectl get multigresclusters
kubectl get shards

Check the pods:

kubectl get pods

Scaling Replicas

Scaling replicas is a spec change on the MultigresCluster. Child resources are owned by the operator and reconciled back to the desired state if edited directly. To add a replica per cell:

kubectl patch multigrescluster demo-multi-az \
  --type=json \
  -p='[{"op":"replace","path":"/spec/databases/0/tablegroups/0/shards/0/spec/pools/default/replicasPerCell","value":2}]'

The operator provisions new standby pods across all three zones simultaneously. Scale back down by patching the value to 1. The operator drains standbys out of the replication set before terminating their pods.

Connecting

Applications inside the cluster connect through the MultiGateway service:

postgresql://postgres:<password>@demo-multi-az-multigateway:5432/postgres

The gateway speaks standard Postgres wire protocol. The gateway routes writes to the primary's pooler and, if the application opts in, routes reads to replicas.