Imported from yugabyte/yugabytedb-skills (skills/yb-k8s-operator/SKILL.md). Install upstream with npx skills add yugabyte/yugabytedb-skills --skill yb-k8s-operator. Copyright stays with the author.

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+):

Resource Spec (v2026.1+): Simple CPU/memory sizing as an alternative to kubernetesOverrides.resource. Values are integers (cores / GiB, min 1 each). When kubernetesOverrides.resource is already set on an existing universe, adding these fields is accepted by Kubernetes but the operator reconciles as NO_OP — no YBA update is triggered and sizing does not change. These fields only take effect on universes created without kubernetesOverrides.resource.

YBC Throttle Parameters (v2026.1+): Tune backup/restore throughput when backups consume too many resources. maxConcurrentUploads and maxConcurrentDownloads have a hard maximum of 3 — values above this cause Error Updating at reconcile time (the admission webhook does not validate them).

GFlags:

Kubernetes overrides (spec.kubernetesOverrides): free-form object passed to the Helm chart.

Read Replica (spec.readReplica):

Status: status.universeState (Ready, Creating, Editing, Deleting), status.sqlEndpoints, status.cqlEndpoints, status.resourceUUID. status.actions (v2026.1+): array of {action_type, message, taskUUID, status} where status is queued, running, or failed.

StorageConfig

Defines a backup storage destination. Referenced by Backup, BackupSchedule, and DrConfig.

Backup

BackupSchedule

Must set either schedulingFrequency or cronExpression.

Auto-deletes when owning universe is deleted.

RestoreJob

PitrConfig

kubernetesOperatorNamespace: "" bug: PitrConfigReconciler passes an empty namespace when looking up the referenced YBUniverse, causing a permanent Unable to fetch YBUniverse loop. PitrConfig will never be created when the operator watches all namespaces. Set kubernetesOperatorNamespace to a specific namespace to work around this.

PitrRestore (v2026.1+)

All fields are required and immutable. To restore to a different time, create a new CR.

Status: status.message, status.taskUUID.

DrConfig

sourceUniverse / targetUniverse mutations (v2026.1+): The webhook allows only these change patterns; any other combination is rejected:

• Switchover — swap source and target.
• Failover — source ← old target, target ← "".
• Restart/change replica — source unchanged, target ← new universe name.

Pre-2026.1: both fields were fully immutable.

SupportBundle

Plural resource name is support-bundles (hyphenated) — kubectl get support-bundles -A, not kubectl get supportbundle.

Status: status.status (generating, ready, failed), status.access (download URL).

Immutable Fields

Attempting to change an immutable field is rejected by the admission webhook — delete and recreate the CR (data loss for YBUniverse).

• YBUniverse: universeName, replicationFactor, providerName, zoneFilter, enableYSQL, enableYCQL, enableYSQLAuth, ysqlPassword, enableYCQLAuth, ycqlPassword, enableNodeToNodeEncrypt, enableClientToNodeEncrypt, rootCA, enableLoadBalancer, enableIPV6, deviceInfo.numVolumes, deviceInfo.storageClass, masterDeviceInfo.numVolumes, masterDeviceInfo.storageClass. tserverVolume/masterVolume cannot be removed once set; perAZ within them cannot be removed once set; numVolumes/storageClass within them are mutable with DB ≥ 2026.1.0.
• YBProvider: cloudInfo.kubernetesProvider
• StorageConfig: config_type, name, data.BACKUP_LOCATION
• DrConfig (pre-2026.1): sourceUniverse, targetUniverse fully immutable. See DrConfig section for v2026.1+ rules.
• PitrConfig: universe
• PitrRestore (v2026.1+): universe, pitrConfig, restoreTime — all immutable.
• BackupSchedule: backupType, universe, storageConfig, keyspace, name, tableByTableBackup, timeBeforeDelete, enablePointInTimeRestore

What Can Be Changed After Creation

• Scale: spec.numNodes and placementInfo zone counts.
• Upgrade: spec.ybSoftwareVersion (register the new Release first).
• GFlags: spec.gFlags.tserverGFlags / masterGFlags.
• Volume size: Increase volumeSize on any volume field (never decrease).
• Volume count / storage class (v2026.1+, DB ≥ 2026.1.0): tserverVolume.numVolumes, storageClass, per-AZ overrides.
• Resource spec (v2026.1+): tserverResourceSpec, masterResourceSpec.
• YBC throttle (v2026.1+): ybcThrottleParameters.
• Kubernetes overrides: Resource requests/limits, affinity, tolerations, annotations, labels, secretEnv, extraVolumes.
• Pause/resume: spec.paused on YBUniverse; spec.paused on DrConfig (v2026.1+).
• DR switchover / failover (v2026.1+): See DrConfig mutation rules.
• Backup schedule frequency: schedulingFrequency, cronExpression, incrementalBackupFrequency.

Anti-Patterns

Installation

kubectl apply -f https://raw.github.com/yugabyte/charts/<version>/crds/concatenated_crd.yaml

helm install yba yugabytedb/yugaware \
  --version <version> --namespace yb-platform \
  --set yugaware.kubernetesOperatorEnabled=true \
  --set yugaware.kubernetesOperatorNamespace='<operator-namespace>' \
  --set yugaware.defaultUser.enabled=true \
  --set yugaware.defaultUser.username='<username>' \
  --set yugaware.defaultUser.email='<email>' \
  --set yugaware.defaultUser.password='<password>'

Upgrade (enable operator, watch all namespaces):

kubectl apply -f https://raw.github.com/yugabyte/charts/<version>/crds/concatenated_crd.yaml
helm upgrade yba yugabytedb/yugaware --version <version> --namespace yb-platform \
  --reset-then-reuse-values \
  --set yugaware.kubernetesOperatorEnabled=true \
  --set yugaware.kubernetesOperatorNamespace=''

Current Limitations

• No multi-cluster universes.
• No software upgrade rollback.
• No xCluster replication (use DrConfig for DR).
• Read Replica defined in CRD but not fully supported via the operator.
• No encryption-at-rest.
• TLS config is immutable after creation; only self-signed supported.
• PitrRestore CR requires v2026.1+. Earlier versions must use the YBA UI or API for PITR restore.

Workflow Summaries

Detailed step-by-step workflows with full YAML: see references/workflows.md Complete YAML examples for every CRD: see references/crd-examples.md

Provision a Universe

1. Install YBA with operator enabled; apply CRDs.
2. Create Release CR → wait for status.success: true.
3. Create YBProvider CR (if needed).
4. Optionally create YBCertificate.
5. Create YBUniverse → monitor with kubectl get ybuniverse -w until Ready.

Upgrade DB Software

1. Create new Release CR → wait for status.success: true.
2. Edit spec.ybSoftwareVersion on the YBUniverse → monitor rolling upgrade.

Backups

• One-time: StorageConfig → Backup
• Scheduled: StorageConfig → BackupSchedule (set schedulingFrequency or cronExpression)
• Incremental: set incrementalBackupFrequency on schedule, or incrementalBackupBase on a Backup
• Restore from backup: RestoreJob with actionType: RESTORE

PITR Restore (v2026.1+)

1. Ensure PitrConfig exists for the target database.
2. Create PitrRestore CR with universe, pitrConfig, and restoreTime.
3. To restore to a different time, create a new PitrRestore CR.

Disaster Recovery

• Setup: Create StorageConfig → DrConfig with source/target universes and database list.
• Pause/resume: Toggle spec.paused on the DrConfig (v2026.1+).
• Switchover: Swap sourceUniverse/targetUniverse.
• Failover: Set sourceUniverse ← old target, targetUniverse ← "".
• Restart replication: Keep sourceUniverse unchanged, set targetUniverse to new universe.