yugabyte/yugabytedb-skills/yb-k8s-operator

YugabyteDB Kubernetes Operator

This skill includes:

• references/crd-examples.md — complete YAML examples for every CRD
• references/workflows.md — end-to-end provisioning, upgrade, backup, and DR workflows
• references/kubeconfig-secrets.md — create and rotate kubeconfig secrets for multi-cluster providers. Always follow this guidance; do not create generic kubeconfig secrets.
• references/multi-cluster.md — Helm overrides and pod address templates for Istio and Cilium

Note: This skill covers the YBA Kubernetes Operator (commercial). It does not fully apply to the YugabyteDB OSS Kubernetes Operator, which has fewer CRDs and features.

The operator manages YBA universes declaratively via Kubernetes CRs alongside YBA, watching a configured namespace for changes.

CRD source: https://raw.github.com/yugabyte/charts/<version>/crds/concatenated_crd.yaml Documentation: https://docs.yugabyte.com/stable/yugabyte-platform/anywhere-automation/yb-kubernetes-operator/

Prerequisites

Before creating any CRs:

• [ ] kubectl config current-context points to the cluster running the operator.
• [ ] You are targeting the namespace from yugaware.kubernetesOperatorNamespace (empty string = all namespaces).
• [ ] CRDs applied at the same version as the Helm chart (helm ls -A | grep yugaware).
• [ ] If RBAC is namespace-scoped (RoleBinding only, no ClusterRoleBinding), a YBProvider CR must be created explicitly — the operator cannot auto-discover node/zone topology.
• [ ] For multi-cluster universes, kubeconfig secrets exist for each remote cluster.

Auto-created vs explicit YBProvider: The operator auto-creates a provider only when the universe targets the same cluster as the operator AND YBA has a ClusterRoleBinding. Create a YBProvider CR explicitly when targeting a different cluster, when RBAC is namespace-scoped, or when you need per-zone control (storage class, namespace, overrides, kubeconfig, cert-manager).

CRD upgrades: Apply CRDs before helm upgrade — mismatched CRDs cause silent field drops or validation errors:

kubectl apply -f https://raw.github.com/yugabyte/charts/<new-version>/crds/concatenated_crd.yaml
helm upgrade yba yugabytedb/yugaware --version <new-version> ...

CRD Dependency Order

Create resources in this order; each must be Ready before dependents are created.

1. Release       — register DB software version
2. YBProvider    — define cloud/regions/zones (optional if auto-provider is available)
3. YBCertificate — (optional) TLS certificates
4. YBUniverse    — database cluster
5. StorageConfig — backup storage destination
6. Backup / BackupSchedule / RestoreJob — backup operations
7. PitrConfig    — point-in-time recovery config
8. PitrRestore   — PITR restore operation [v2026.1+]
9. DrConfig      — disaster recovery replication
10. SupportBundle — diagnostic log collection

CRD Quick Reference

All CRDs use apiVersion: operator.yugabyte.io/v1alpha1.

Release

Registers a YugabyteDB software version. Must reach status.success: true before a universe can reference it.

The CRD validation (v2026.1+) requires exactly one helmChart path and exactly one x86_64 path across the combination of http, s3, and gcs — they can come from different sources (e.g. http for the Helm chart and s3 for the tarball). In pre-2026.1 CRDs, x86_64 was optional.

Helm chart URL format: The chart filename uses the 3-part chart version, not the full DB version string — https://charts.yugabyte.com/yugabyte-<major>.<minor>.<patch>.tgz. For example, DB version 2025.2.3.0-b149 uses chart version 2025.2.3, so helmChart: "https://charts.yugabyte.com/yugabyte-2025.2.3.tgz". Confirm chart existence with helm search repo yugabytedb/yugabyte --versions before authoring the CR.

`kubernetesOperatorNamespace: ""` bug: When the operator watches all namespaces (empty string), ReleaseReconciler.onAdd throws namespace not specified when patching the CR status. The exception fires between YBA registration and the download trigger, so:

• The release appears in YBA metadata but packages are never downloaded — the release shows as incomplete in YBA and cannot be used to upgrade a universe.
• Subsequent reconcile loops log no changes found and do not retry the download.
• Releases that fail YBA registration (bad URL, non-existent version) are re-processed via the update path, which does write status correctly.

Workaround: Set kubernetesOperatorNamespace to the specific namespace where universes run instead of "". With a namespace set, the onAdd status patch succeeds and the download is triggered normally.

YBProvider

Defines a Kubernetes cloud provider. Universes reference this by metadata.name.

Status: status.state, status.message.

Kubeconfig secrets must contain a single key kubeconfig with complete kubeconfig YAML. Use long-lived service account tokens — YBA does not support short-lived token plugins. See references/kubeconfig-secrets.md for the full procedure.

For multi-cluster service mesh (Istio / Cilium), see references/multi-cluster.md.

YBCertificate

YBUniverse

The primary CRD. Creates and manages a YugabyteDB database cluster.

Core fields:

Password secrets: create a Kubernetes Secret with key ysqlPassword or ycqlPassword (≥12 chars, mixed case, numbers, special chars) in the same namespace as the YBUniverse, then reference via spec.ysqlPassword.secretName / spec.ycqlPassword.secretName. Both fields are immutable once set.

Placement (v2025.2+):

Storage — v2026.1+: `tserverVolume` / `masterVolume` (preferred):

Replaces deviceInfo/masterDeviceInfo; the two sets are mutually exclusive. numVolumes and storageClass are mutable when running DB ≥ 2026.1.0. Provider-level storage class takes precedence over storageClass here — leave the provider value empty to use this field. Once set, tserverVolume/masterVolume cannot be removed; perAZ within them cannot be removed once set.

Storage — legacy: `deviceInfo` / `masterDeviceInfo` (deprecated v2026.1+):