New to KubeDB? Please start here.

Branching Setup and Configuration

Choose the setup for your environment:

Single-Cluster Installation

Before You Begin

  • Have kubectl and Helm configured for the cluster.
  • Install KubeDB following the Helm installation guide, with a valid cluster license.
  • Use compatible Courier, KubeDB Provisioner, and database images that support branching. The provisioner must recognize branch resources and adopt cloned volumes; the PostgreSQL images must support starting from branched data.
  • Configure a Ceph RBD CSI StorageClass, snapshot support, and a compatible VolumeSnapshotClass as described in snapshot configuration.

These instructions use the KubeDB installer charts. When using feature builds, set their image tags explicitly using the configuration keys below. A chart version alone does not establish that every image includes the feature.

Enable Courier with KubeDB

For a new installation, enable the Courier subchart:

helm install kubedb oci://ghcr.io/appscode-charts/kubedb \
  --version v2026.11.15 \
  --namespace kubedb --create-namespace \
  --set-file global.license=/path/to/license.txt \
  --set kubedb-courier.enabled=true \
  --wait --burst-limit=10000

For an existing Helm release, first update the Branch CRDs as described below, then enable Courier while preserving existing values:

helm upgrade kubedb oci://ghcr.io/appscode-charts/kubedb \
  --version v2026.11.15 \
  --namespace kubedb \
  --reuse-values \
  --set kubedb-courier.enabled=true \
  --wait --burst-limit=10000

Use one Courier installation per cluster. If Courier is already managed by the KubeDB subchart, update that release instead of adding another installation.

Single-cluster configuration

The following keys apply when Courier is installed through the KubeDB chart. Drop the kubedb-courier. prefix for a separate Courier release.

Helm valuePurpose
kubedb-courier.enabledEnable the Courier subchart; the default is false.
kubedb-courier.image.registryImage namespace; the default is kubedb.
kubedb-courier.image.repositoryImage repository; the default is kubedb-courier.
kubedb-courier.image.tagCourier image tag; an empty value uses the chart’s app version.
kubedb-courier.registryFQDNRegistry host; the default is ghcr.io.
kubedb-courier.resourcesCourier container resource requests and limits.
kubedb-courier.nodeSelector, kubedb-courier.tolerations, kubedb-courier.affinityCourier pod placement.
kubedb-provisioner.operator.tagProvisioner image tag in the KubeDB release.

For example, pass --set kubedb-courier.image.tag=<courier-tag> and --set kubedb-provisioner.operator.tag=<provisioner-tag> to the KubeDB Helm command when selecting feature builds. Use the installation guide for database image registry configuration.

CRDs and upgrades

The Courier chart ships the Branch and BranchWork CRDs and installs them on a fresh install. Helm does not upgrade CRDs from a chart’s crds/ directory during helm upgrade. Before upgrading an existing release, apply the matching CRDs from the public apimachinery repository:

kubectl apply --server-side -f https://raw.githubusercontent.com/kubedb/apimachinery/refs/heads/master/crds/courier.kubedb.com_branches.yaml
kubectl apply --server-side -f https://raw.githubusercontent.com/kubedb/apimachinery/refs/heads/master/crds/courier.kubedb.com_branchworks.yaml

The URLs above track master. For a versioned installation, use a repository revision whose CRD schemas match the operator release. If server-side apply reports a field-ownership conflict, review the existing owner and schema differences before transferring ownership.

Verify the single-cluster installation

kubectl get crd branches.courier.kubedb.com branchworks.courier.kubedb.com
kubectl -n kubedb get deployment -l app.kubernetes.io/name=kubedb-courier
kubectl -n kubedb rollout status deployment \
  -l app.kubernetes.io/name=kubedb-courier --timeout=5m
kubectl get storageclass ceph-rbd
kubectl get volumesnapshotclass

Confirm that the Courier Deployment is available and that the snapshot class driver matches the StorageClass provisioner. Continue with PostgreSQL branching.

Cross-Cluster Installation with OCM

This section installs Courier into an existing OCM environment to enable cross-cluster branching. It assumes the hub and managed clusters are already configured.

OCM prerequisites

Ensure that:

  • The OCM hub has working registration, work delivery, and addon management, including the AddOnTemplate API.
  • Source and target are registered, accepted, and available managed clusters. Their ManagedCluster names are used as Courier cluster identities.
  • The hub can deliver ManifestWork to both clusters, and addon registration can issue credentials for the managed-cluster agents.
  • KubeDB, valid per-cluster licenses, and compatible branching-capable operator/database images are installed on the participating clusters. The hub only needs OCM and the Courier addon manager.
  • Both database clusters use the same network-reachable CoW storage backend, such as Ceph RBD, with compatible CSI settings. Source data must already reside on that backend. See snapshot configuration.
  • kubectl contexts named hub, source, and target select the intended clusters. In these examples, the managed-cluster names are also source and target.

Verify the existing OCM registration:

kubectl --context hub get managedclusters source target

Both clusters should report JOINED=True and AVAILABLE=True with hub acceptance enabled.

Prepare the managed clusters

Branch and BranchWork CRDs must exist on both managed clusters before enabling the addon. If your KubeDB installation has not already installed them, apply the matching CRDs:

for context in source target; do
  kubectl --context "$context" apply --server-side \
    -f https://raw.githubusercontent.com/kubedb/apimachinery/refs/heads/master/crds/courier.kubedb.com_branches.yaml \
    -f https://raw.githubusercontent.com/kubedb/apimachinery/refs/heads/master/crds/courier.kubedb.com_branchworks.yaml
done

The managed-cluster addon supplies the Courier agents. Disable any existing standalone Courier Deployment on those clusters as part of the transition, so each cluster runs a single Courier agent installation. For a Courier subchart, set kubedb-courier.enabled=false in the existing KubeDB release; retain its CRDs.

Install the Courier addon manager on the hub

Install the Courier manager and its OCM addon definitions from the public OCI chart:

helm --kube-context hub upgrade --install kubedb-courier-addon-manager \
  oci://ghcr.io/appscode-charts/kubedb-courier-addon-manager \
  --version v0.8.0 \
  --namespace kubedb --create-namespace \
  --wait

The chart installs the hub Courier CRDs, manager Deployment, RBAC, ClusterManagementAddOn, and AddOnTemplate. It also delegates the permissions needed by OCM’s addon manager and work agents. Use the same Courier build for the manager and agents.

For upgrades, also apply matching CRDs on the hub before updating the manager, using the CRD upgrade procedure with --context hub. Use schemas matching the operator build on all three clusters.

Enable the addon on both managed clusters

By default, the chart uses manual addon placement. Create one ManagedClusterAddOn in each cluster’s hub namespace:

apiVersion: addon.open-cluster-management.io/v1alpha1
kind: ManagedClusterAddOn
metadata:
  name: courier
  namespace: source
spec:
  installNamespace: kubedb
---
apiVersion: addon.open-cluster-management.io/v1alpha1
kind: ManagedClusterAddOn
metadata:
  name: courier
  namespace: target
spec:
  installNamespace: kubedb

Save this manifest as courier-addons.yaml, then apply it to the hub:

kubectl --context hub apply -f courier-addons.yaml

OCM deploys courier-agent on each managed cluster. The addon supplies each agent’s cluster name and scoped hub credentials. Keep each installNamespace consistent with agent.installNamespace in the Helm values.

Cross-cluster configuration

Helm valueDefaultPurpose
image.registryghcr.io/kubedbRegistry and image namespace for the shared Courier image.
image.repositorykubedb-courierShared image repository.
image.tagChart app versionManager and agent image tag.
manager.replicaCount1Hub manager replicas.
manager.leaderElectiontrueLeader election for the manager.
manager.maxFeedbackWatch100Concurrent watch-based feedback limit; additional feedback uses polling.
agent.installNamespacekubedbAgent namespace on managed clusters.
agent.image.registry, agent.image.repository, agent.image.tagShared image valuesOptional agent image overrides.
agent.placement.nameEmptyExisting OCM Placement used for automatic addon placement.
agent.placement.namespaceopen-cluster-managementNamespace of the existing Placement.
ocm.addonManager.namespaceopen-cluster-management-hubExisting OCM addon-manager namespace.
ocm.addonManager.serviceAccountNameaddon-manager-controller-saExisting addon-manager ServiceAccount.
ocm.workAgent.namespaceopen-cluster-management-agentExisting work-agent namespace on managed clusters.
ocm.workAgent.serviceAccountNameklusterlet-work-saExisting work-agent ServiceAccount.

Set the OCM identity values to match the existing installation so the chart grants permissions to the correct ServiceAccounts.

Verify cross-cluster Courier

kubectl --context hub -n kubedb rollout status deployment/kubedb-courier-addon-manager --timeout=5m
kubectl --context hub get clustermanagementaddon courier
kubectl --context hub get addontemplate
kubectl --context hub -n source get managedclusteraddon courier -o yaml
kubectl --context hub -n target get managedclusteraddon courier -o yaml
kubectl --context source -n kubedb rollout status deployment/courier-agent --timeout=5m
kubectl --context target -n kubedb rollout status deployment/courier-agent --timeout=5m

Check that addon registration is applied and that availability conditions are True. Confirm the agents start controller workers in their logs:

kubectl --context source -n kubedb logs deployment/courier-agent --tail=100
kubectl --context target -n kubedb logs deployment/courier-agent --tail=100

Check Branch API availability on each cluster:

for context in hub source target; do
  kubectl --context "$context" get crd \
    branches.courier.kubedb.com branchworks.courier.kubedb.com
done

Continue with the PostgreSQL cross-cluster tutorial.