Custom Resource Reference

The plugin's API group is plugin-branching.plugins.openeverest.io, version v1alpha1. It has three namespaced resources, all in the namespace of the OpenEverest Instance they're about:

Kind	Short name	What it is
Branch	br	a writable copy of a database, or of a whole instance
RestorePoint	rp	a point an instance, or one of its databases, can be rolled back to
Operation	brop	a one-off reset, promote or rollback

kubectl get branches,restorepoints,operations -n team-a
kubectl get br -n team-a

All three are owned by their Instance (an owner reference is added by the controller), so deleting the instance deletes them. The controller also labels them with plugin-branching.plugins.openeverest.io/instance and plugin-branching.plugins.openeverest.io/provider.

v1alpha1

The API is at an early stage and may change in incompatible ways between releases.

Branch

A Branch is a writable copy of a database of an OpenEverest instance (method: Clone) or of the whole instance (method: Snapshot). See Branch methods.

Example

apiVersion: plugin-branching.plugins.openeverest.io/v1alpha1
kind: Branch
metadata:
  name: feature-x
  namespace: team-a              # the instance's namespace
spec:
  instanceRef:
    name: orders-db              # immutable
  method: Clone                  # Clone (default) | Snapshot; immutable
  source:
    database: app                # immutable
  database: app_feature_x        # immutable
  sourceConnections: Terminate   # Terminate (default) | Fail
  deletionPolicy: Delete         # Delete (default) | Retain
status:
  phase: Ready
  database: app_feature_x
  databaseOID: 16842
  owner: app
  createdAt: "2026-11-10T13:20:01Z"
  copyMethod: clone
  duration: 412ms
  terminatedConnections: 1
  conditions:
    - type: Ready
      status: "True"
    - type: ReplicasCopyOnWrite
      status: "True"
      reason: StandbysClone

An instance branch:

apiVersion: plugin-branching.plugins.openeverest.io/v1alpha1
kind: Branch
metadata:
  name: pr-42
  namespace: team-a
spec:
  instanceRef:
    name: orders-db
  method: Snapshot
  instanceName: orders-db-pr-42
status:
  phase: Ready
  instance: orders-db-pr-42
  volumeSnapshot: orders-db-pr-42-1a2b3c4d
  snapshotSource: orders-db-2
  targetLSN: 0/5A000060
  duration: 26.895s

Spec

Field	Type	Default	Description
instanceRef.name	string	—	Required. The Instance to branch, in the Branch's namespace. Immutable.
method	Clone | Snapshot	Clone	Clone makes a new database in the same instance with PostgreSQL 18's file_copy_method = clone. Snapshot makes a new single-node Instance from a volume snapshot of the source. Immutable.
source.database	string, 1–63 chars	—	The database to branch. Required for Clone; Snapshot branches the whole instance. Immutable.
database	string, ^[a-z_][a-z0-9_]{0,62}$	—	The branch database's name. Required for Clone. Immutable.
instanceName	string, ^[a-z]([a-z0-9-]{0,48}[a-z0-9])?$	—	The branch Instance's name, in the Branch's namespace. Required for Snapshot. Immutable.
sourceConnections	Terminate | Fail	Terminate	What to do with sessions connected to the source, since PostgreSQL copies a database only while nobody else is connected to it. Terminate disconnects them for the copy; Fail waits until the source is idle.
deletionPolicy	Delete | Retain	Delete	What deleting the Branch does: Delete drops the branch database, or deletes the branch Instance and its snapshot; Retain keeps them.

Validation rules, enforced by the API server:

• instanceRef, method, source, database and instanceName are immutable.
• Clone needs source.database and database.
• Snapshot needs instanceName.

Status

Field	Description
phase	Pending, Creating, Ready, Resetting, Promoted, Failed or Deleting.
message	A human-readable explanation of the phase.
database	The branch database, once created (Clone).
databaseOID	The branch database's OID. The plugin only drops the database with this OID.
owner	The branch database's owner: the source's owner.
instance	The branch Instance (Snapshot).
volumeSnapshot	The VolumeSnapshot the branch Instance started from (Snapshot).
snapshotSource	The source's PVC that was snapshotted: a standby's when there is one.
targetLSN	The source primary's WAL position when the branch was requested. The snapshotted standby replays up to it first, so the branch has everything committed before. For SQL Server, each database's log position on the primary, as db=lsn,…, which the snapshotted secondary hardens first.
createStartedAt	Set right before the plugin first changes anything, and kept: lets a retry adopt a half-made branch instead of failing.
createdAt	The branch point: the branch has the source's data as of then.
copyMethod	The file_copy_method the primary copied the source with (Clone).
duration	How long making the branch took.
terminatedConnections	How many sessions of the source were terminated.
resets	How many times the branch was reset.
promotedAt	When the branch's data became its source's. A promoted branch no longer owns that data: deleting it leaves it in place.
observedGeneration	The generation the status is about.
conditions	See below.

Phases

Conditions

Type	Meaning
Ready	The branch exists and can be used. The reason explains why not when it's False.
ReplicasCopyOnWrite	For Clone branches of instances with standbys: True (StandbysClone) when the standbys clone the branch too, False (StandbysCopy) when they copy it in full because their file_copy_method isn't clone.

Reasons

Reason	Phase	Meaning
NotReady	Pending	The instance isn't ready yet; retried.
RoleNotApplied	Pending	The plugin's database role isn't applied yet; retried.
SourceBusy	Pending	The source has sessions and sourceConnections: Fail, or clients reconnect faster than the retries; retried with backoff.
InProgress	Creating	An instance branch is being made over several steps.
UnsupportedVersion	Failed	The database version doesn't support the method: PostgreSQL before 18 for Clone, before 15 for Snapshot.
Unsupported	Failed	The plugin has no engine for the instance's provider and the method.
InvalidSource	Pending	The source database doesn't exist yet; retried, so a branch of a branch can be applied together with its source.
InvalidSource	Failed	The source database is the branch database itself, a system database, or owned by a superuser or operator role.
UnsupportedSource	Failed	The source can't be branched as configured, for example WAL on a separate volume, or the branch Instance can't be created from it.
DatabaseExists	Failed	The branch database's name is taken by a database the plugin didn't make.
InstanceExists	Failed	An Instance or VolumeSnapshot with the branch's name already exists.
DatabaseMissing	Failed	The branch database was dropped by hand. Deleting the Branch then succeeds.
InstanceMissing	Failed	The branch Instance was deleted by hand.

Printer columns

kubectl get branches shows INSTANCE, METHOD, SOURCE, DATABASE, BRANCH INSTANCE, PHASE, DURATION and AGE.

RestorePoint

A RestorePoint is a point an instance, or one of its databases, can be rolled back to with a Rollback operation. See Reset, restore points, rollback and promote.

Example

apiVersion: plugin-branching.plugins.openeverest.io/v1alpha1
kind: RestorePoint
metadata:
  name: before-migration
  namespace: team-a
spec:
  instanceRef:
    name: orders-db
  method: Snapshot              # Snapshot (default) | Clone
  # database: app               # required for Clone
status:
  phase: Ready
  createdAt: "2026-11-11T17:28:47Z"
  duration: 8.94s
  snapshots:
    - instance: orders-db-1
      volumeSnapshot: rp-5e6f7a8b-orders-db-1
      primary: true
    - instance: orders-db-2
      volumeSnapshot: rp-5e6f7a8b-orders-db-2

Spec

The whole spec is immutable.

Field	Type	Default	Description
instanceRef.name	string	—	Required. The Instance, in the RestorePoint's namespace.
method	Snapshot | Clone	Snapshot	Snapshot snapshots the volumes of every instance, standbys first; rolling back swaps them in. Clone keeps a hidden copy of one database with file_copy_method = clone; rolling back clones it in place of the database.
database	string, up to 63 chars	—	The database to keep. Required for Clone.

Status

Field	Description
phase	Pending, Creating, Ready, Failed or Deleting.
message	A human-readable explanation of the phase.
createdAt	The point the instance or database rolls back to.
snapshots[]	For Snapshot: one entry per PostgreSQL instance, with instance (and its PVC's name), volumeSnapshot, and primary when it was the primary.
database	For Clone: the hidden copy of the database, <db>_rp_<hash>.
databaseOID	For Clone: the copy's OID.
duration	How long taking the restore point took.
progress	Steps done, so an interrupted restore point resumes where it stopped.
observedGeneration, conditions	Standard.

Deleting a RestorePoint deletes what it keeps: its VolumeSnapshots or its hidden database (finalizer plugin-branching.plugins.openeverest.io/restore-point).

kubectl get restorepoints shows INSTANCE, METHOD, DATABASE, PHASE and CREATED.

Operation

An Operation resets or promotes a branch, or rolls back to a restore point. Operations on an instance run one at a time, in creation order.

Example

apiVersion: plugin-branching.plugins.openeverest.io/v1alpha1
kind: Operation
metadata:
  generateName: promote-feature-x-
  namespace: team-a
spec:
  instanceRef:
    name: orders-db
  type: Promote                 # Reset | Promote (branchRef) | Rollback (restorePointRef)
  branchRef:
    name: feature-x
status:
  phase: Succeeded
  startedAt: "2026-11-11T17:29:37Z"
  completedAt: "2026-11-11T17:29:39Z"
  duration: 2.431s
  restorePoint: orders-db-before-feature-x-b54a14

Spec

The whole spec is immutable: create a new Operation to run again.

Field	Type	Description
instanceRef.name	string	Required. The instance the operation is about: the source of the branch, or the instance of the restore point.
type	Reset | Promote | Rollback	Required. Reset gives the branch a fresh copy of its source. Promote makes the branch's data the source's, after taking a restore point of the source. Rollback brings the instance, or database, back to a restore point.
branchRef.name	string	The branch to reset or promote. Required for Reset and Promote.
restorePointRef.name	string	The restore point to roll back to. Required for Rollback.

Status

Field	Description
phase	Pending, Running, Succeeded or Failed.
message	A human-readable explanation of the phase.
startedAt, completedAt	When the operation started and completed.
duration	From start to completion.
restorePoint	For Promote: the restore point taken first. Roll back to it to undo the promotion.
progress	Steps done. Each step is idempotent, so an operation interrupted by a restart resumes where it stopped and never repeats a step.
observedGeneration	Standard.

kubectl get operations shows INSTANCE, TYPE, BRANCH, RESTORE POINT, PHASE, DURATION and AGE.

Labels, annotations and finalizers

Key	On	Meaning
plugin-branching.plugins.openeverest.io/instance	Branch, RestorePoint, Operation	the Instance it's about
plugin-branching.plugins.openeverest.io/provider	Branch, RestorePoint, Operation	the Instance's provider
app.kubernetes.io/managed-by: plugin-branching	objects the plugin makes	branch Instances, VolumeSnapshots, PVCs
plugin-branching.plugins.openeverest.io/branch, …/branch-uid	objects made for a Branch	the plugin only deletes objects with the Branch's UID
plugin-branching.plugins.openeverest.io/restore-point-uid	VolumeSnapshots	snapshots of a restore point
plugin-branching.plugins.openeverest.io/operation-uid	VolumeSnapshots	snapshots an operation takes
plugin-branching.plugins.openeverest.io/source-instance	branch Instances (annotation)	the Instance a branch was made from
plugin-branching.plugins.openeverest.io/retained-from	PersistentVolumes	a replaced volume kept because snapshots still need it, see Retained volumes on ZFS
plugin-branching.plugins.openeverest.io/drop-database	Branch (finalizer)	removes the branch before the Branch goes away
plugin-branching.plugins.openeverest.io/restore-point	RestorePoint (finalizer)	deletes what the restore point keeps

The plugin never deletes what it didn't make: branch Instances, snapshots and volumes must carry the Branch's UID, and Clone branch databases are dropped only if their OID matches status.databaseOID or their comment is openeverest-branch:<Branch UID>.