Skip to content

Introduction ​

Tack moves the primary of a CloudNativePG database from one Kubernetes site to another. It is for setups where Flux deploys every site from one Git repository. It handles two cases: a planned switchover, and a failover after a site is lost.

The operator starts every run. Tack never decides to fail over by itself.

Why ​

Moving the primary by hand fails in two ways:

What goes wrongWhat Tack does
Flux applies the old values from Git and undoes the switch.Stops Flux from applying the objects the run changes, and only those. Commits the new values to Git. Lets Flux apply those objects again once Git matches live.
The old primary's demotion token must be carried to the new primary's cluster, between two steps. Promoting without the token can fork the data: the two sites then hold different histories.Waits for the old primary to publish the token. Records the token in the ledger. Promotes the new primary with it.

Tack changes the database only through CloudNativePG's own API, and records every step in a ledger, the SiteFailover resource. Concepts shows how a run works. RFC#0001 gives the full scope.

What keeps it safe ​

PropertyHow
The operator starts every runOnly tack run starts a run. Tack has no timer, watch or health check that starts one.
Plan firsttack plan reads every site and Git. It prints every step, patch, wait, Git edit and check. It changes nothing.
Typed confirmationtack run and tack resume print the plan or the ledger, then ask the operator to type the workload's name. Without a terminal they refuse, unless --yes is passed for a run that a human approved.
Narrow holdTack holds only the objects the run changes. The hold is an annotation on the live objects: nothing is annotated in Git. No Kustomization is suspended.
Resume from the ledgerThe plan is stored in the ledger when the run starts. tack resume continues that plan and never plans again. Every step is safe to repeat.
Git equals live before releaseTack renders the run's commit the way Flux does. It releases an object only once that render matches live. After release, it checks that Flux changed nothing.
Stop and askAnything unexpected stops the run, with exit code 3 and a reason in the ledger. For example: Git changed during the run, a token is missing, a lost site came back as primary, or an object is held by someone else.
Break-glassIf a site is lost and Git is down too, Tack still switches live. Then it waits at the Git step, with exit code 4. Once Git is back, tack resume commits. Nothing is released before that.
Explicit contextsEach site uses the kube context named in the Workload file. Tack never falls back to the current context.
AI agentstack --help and tack --skill tell agents never to start tack run or tack resume without a human's explicit instruction for that run, and to run tack plan first.
No secretsGit access comes from the operator's own git configuration. The ledger holds no secret, and tack status prints captured values by name only.

What v1 supports ​

AreaSupport
WorkloadCloudNativePG in the distributed topology: one Cluster per site, the primary named by .spec.replica.primary, and an optional read-write Pooler per site. The driver is cnpg.
GitOpsFlux kustomize-controller with a GitRepository source. One Git repository serves all sites.
Routing checkOptional. Reads the SiteService status of Strait v1.0.0 or later. Strait routes clients to the primary.
PlatformsLinux, macOS and Windows, amd64 and arm64.
Tested withCloudNativePG v1.30.1, Flux v2.10.0 and Kubernetes v1.37, in the end-to-end test.

Versions ​

Releases are on the releases page. The API is failover.tako.id/v1, for both the SiteFailover ledger and the Workload file. A change that would break a user comes as a new API version. failover.tako.id/v1alpha1 was the API of v0.1.x. It is deprecated but still served: see Upgrade from v0.1.x.

Released under the Apache License 2.0.