The Autonomous Operator for Couchbase on Kubernetes lets you manage Couchbase clusters not as a collection of pods, but as a single, cohesive, self-healing system.
Let’s get this running. First, we need a Kubernetes cluster. If you don’t have one, kind is a great way to spin one up locally for testing:
cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
EOF
Now, we need to install the Couchbase Autonomous Operator itself. This involves applying a few Kubernetes manifests. The operator runs as a Deployment in its own namespace, typically couchbase-operator.
kubectl apply -f https://raw.githubusercontent.com/couchbase/couchbase-operator/v2.4.0/deploy/operator.yaml
This command downloads the operator’s YAML definition from GitHub and applies it to your cluster. You can verify the operator is running with:
kubectl get pods -n couchbase-operator
You should see a single pod named something like couchbase-operator-xxxxxxxxxx-yyyyy in a Running state. This operator is now watching for CouchbaseCluster custom resources.
To deploy our first Couchbase cluster, we define a CouchbaseCluster YAML. This is where we specify the desired state of our Couchbase cluster.
apiVersion: couchbase.com/v2
kind: CouchbaseCluster
metadata:
name: my-couchbase-cluster
spec:
image: couchbase/server:7.1.0
clusterNetwork:
services:
- name: kv
port: 11210
- name: index
port: 9102
- name: n1ql
port: 8093
- name: mgmt
port: 8091
- name: data
port: 8092
- name: query
port: 18091
- name: eventing
port: 8098
- name: analytics
port: 8094
- name: syslog
port: 20000
ports:
- name: tls
port: 11207
buckets:
- name: default
type: couchbase
memoryQuota: 256
replicas: 1
nodes:
- name: node1
resources:
requests:
memory: 2Gi
cpu: 1000m
- name: node2
resources:
requests:
memory: 2Gi
cpu: 1000m
- name: node3
resources:
requests:
memory: 2Gi
cpu: 1000m
auth:
adminPasswordSecret:
secretName: couchbase-admin-password
Save this to a file, say couchbase-cluster.yaml. The spec section is crucial:
image: Specifies the Couchbase Server version.clusterNetwork.services: Defines the ports for various Couchbase services.buckets: Configures data buckets. Here, we create a default bucket with 256MB quota and 1 replica.nodes: Defines the number and resource requests for Couchbase nodes. We’re asking for 3 nodes.auth.adminPasswordSecret: This is important for security. It points to a Kubernetes Secret containing the Couchbase administrator password.
Before applying the cluster definition, you need to create that secret.
kubectl create secret generic couchbase-admin-password --from-literal=password='YourSecurePassword123!'
Replace YourSecurePassword123! with a strong password. The operator will read this secret and use it to set the Couchbase administrator credentials.
Now, deploy the Couchbase cluster:
kubectl apply -f couchbase-cluster.yaml
The operator will notice the new CouchbaseCluster resource and start provisioning the necessary Kubernetes resources: StatefulSets for the Couchbase nodes, Services for access, and PersistentVolumeClaims for data storage.
You can watch the progress:
kubectl get couchbasecluster my-couchbase-cluster -w
Initially, the status will show Provisioning. As pods come up and Couchbase nodes join the cluster, it will transition to Running.
To interact with your Couchbase cluster, you’ll typically use the Couchbase Web Console or the Couchbase CLI. The operator creates a Kubernetes Service for the management API (port 8091).
kubectl get service my-couchbase-cluster-mgmt
You’ll see output like:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
my-couchbase-cluster-mgmt ClusterIP 10.96.147.123 <none> 8091/TCP 5m
To access this from your local machine, you can use kubectl port-forward:
kubectl port-forward service/my-couchbase-cluster-mgmt 8091:8091
Now, open your browser to http://localhost:8091. Log in with the username Administrator and the password you set in the secret (YourSecurePassword123!). You should see the Couchbase Web Console.
The most surprising thing about the Autonomous Operator is how it abstracts away the complexities of distributed systems management. It doesn’t just deploy pods; it understands Couchbase’s internal topology and healing mechanisms, translating your desired state into the correct sequence of Couchbase commands.
Inside the CouchbaseCluster resource, the nodes section specifies not just the count but also the roles each node will play. The operator intelligently assigns services (KV, Index, N1QL, etc.) to these nodes based on Couchbase’s best practices and your configuration. For example, if you define a node with resources.requests.memory greater than a certain threshold (e.g., 8GB), the operator might automatically assign it the Analytics service.
The operator manages the entire lifecycle: initial bootstrapping, adding/removing nodes, scaling services, performing rolling upgrades, and even handling failures by orchestrating the necessary Couchbase commands to rebalance data and maintain cluster health. It uses Kubernetes Operators SDK and leverages Custom Resource Definitions (CRDs) to extend the Kubernetes API with CouchbaseCluster and CouchbaseBackup objects, allowing you to manage Couchbase using familiar kubectl commands.
What most people don’t realize is how deeply the operator understands Couchbase’s internal state. It’s not just creating pods and hoping for the best. It continuously monitors the health of each Couchbase node, checks for rebalancing events, and ensures that the cluster configuration matches the CouchbaseCluster resource definition. If a node fails, the operator will attempt to replace it and trigger a rebalance. This proactive management is what makes it "autonomous."
The next step is usually to explore advanced configurations like persistent storage, custom resource allocation per service, and setting up Couchbase backups.