apecloud/kubeblocks-cluster-lifecycle

Manage Cluster Lifecycle: Stop, Start, Restart

Overview

KubeBlocks supports stopping, starting, and restarting database clusters through OpsRequest CRs. Stopping a cluster terminates all pods while retaining PVCs, allowing cost savings when the cluster is not in use.

Official docs: https://kubeblocks.io/docs/preview/user_docs/maintenance/stop-start-a-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Workflow

- [ ] Step 1: Check current cluster status
- [ ] Step 2: Apply the lifecycle operation (Stop / Start / Restart)
- [ ] Step 3: Verify the operation

Step 1: Check Current Cluster Status

kubectl get cluster <cluster-name> -n <namespace>

| Status | Meaning | |--------|---------| | Running | Cluster is healthy and serving traffic. Can be stopped or restarted. | | Stopped | Cluster pods are terminated, PVCs retained. Can be started. | | Updating | An operation is in progress. Wait for it to complete. |

Step 2: Apply the Lifecycle Operation

Stop a Cluster

Stops all pods in the cluster. PVCs are retained so data is preserved.

OpsRequest method:

apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: stop-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Stop

Before applying, validate with dry-run:

kubectl apply -f - --dry-run=server <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: stop-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Stop
EOF

If dry-run reports errors, fix the YAML before proceeding.

Apply:

kubectl apply -f - <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: stop-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Stop
EOF

Alternative — kubectl patch method:

kubectl patch cluster <cluster-name> -n <namespace> \
  --type merge -p '{"spec":{"componentSpecs":[{"name":"<component-name>","stop":true}]}}'

Replace <component-name> with the component name for the addon (e.g., mysql, postgresql, redis, mongodb, kafka-combine).

Start a Cluster

Recreates pods from the retained PVCs, restoring the cluster to its previous state.

OpsRequest method:

apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: start-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Start

Before applying, validate with dry-run:

kubectl apply -f - --dry-run=server <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: start-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Start
EOF

If dry-run reports errors, fix the YAML before proceeding.

Apply:

kubectl apply -f - <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: start-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Start
EOF

Alternative — kubectl patch method:

kubectl patch cluster <cluster-name> -n <namespace> \
  --type merge -p '{"spec":{"componentSpecs":[{"name":"<component-name>","stop":false}]}}'

Restart a Cluster

Performs a rolling restart of specified components. Pods are restarted one at a time to maintain availability.

OpsRequest method:

apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: restart-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Restart
  restart:
    - componentName: <component-name>

Before applying, validate with dry-run:

kubectl apply -f - --dry-run=server <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: restart-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Restart
  restart:
    - componentName: <component-name>
EOF

If dry-run reports errors, fix the YAML before proceeding.

Apply:

kubectl apply -f - <<'EOF'
apiVersion: apps.kubeblocks.io/v1beta1
kind: OpsRequest
metadata:
  name: restart-<cluster-name>
  namespace: <namespace>
spec:
  clusterName: <cluster-name>
  type: Restart
  restart:
    - componentName: <component-name>
EOF

Note: The componentName depends on the addon. Common values:

• MySQL: mysql
• PostgreSQL: postgresql
• Redis: redis
• MongoDB: mongodb
• Kafka: kafka-combine (combined topology) or kafka-broker / kafka-controller (separated topology)

You can restart multiple components by adding more entries to the restart list.

Step 3: Verify the Operation

Monitor the OpsRequest

kubectl get ops -n <namespace> -w

Success condition: .status.phase = Succeed | Typical: 1-3min | If stuck >5min: kubectl describe ops <ops-name> -n <namespace>

Expected progression: Pending → Running → Succeed.

Check Cluster Status

kubectl get cluster <cluster-name> -n <namespace> -w

Success condition: Stop: .status.phase = Stopped | Start/Restart: .status.phase = Running | Typical: 1-3min | If stuck >5min: kubectl describe cluster <cluster-name> -n <namespace>

• After Stop: status changes to Stopped, all pods terminated.
• After Start: status changes to Running, all pods recreated.
• After Restart: status briefly shows Updating, then returns to Running.

Check Pods

kubectl get pods -n <namespace> -l app.kubernetes.io/instance=<cluster-name>

• After Stop: no pods found.
• After Start / Restart: all pods in Running state.

Troubleshooting

OpsRequest stuck in Running:

• Check OpsRequest events: kubectl describe ops <ops-name> -n <namespace>
• Check KubeBlocks controller logs: kubectl logs -n kb-system -l app.kubernetes.io/name=kubeblocks --tail=50

Start fails after Stop:

• Ensure PVCs still exist: kubectl get pvc -n <namespace> -l app.kubernetes.io/instance=<cluster-name>
• If PVCs were manually deleted, the cluster cannot be started and must be recreated.

Restart takes too long:

• Rolling restart is sequential. For large clusters, it processes one pod at a time.
• Check if pods are stuck: kubectl describe pod <pod-name> -n <namespace>

Additional Resources

For component names by engine, kubectl patch alternatives, cluster status transitions, and cost-saving patterns, see reference.md.

For general agent safety conventions (dry-run, status confirmation, production protection), see safety-patterns.md.