kubeblocks-cluster-lifecycle

name	kubeblocks-cluster-lifecycle
metadata	{"version":"0.1.0"}
description	Legacy compatibility shim for cluster lifecycle actions. The primary Day-2 entry is kubeblocks-op-lifecycle. Keep this skill callable for older references, but do not recommend it as the main path for cold-start agents.

Manage Cluster Lifecycle: Stop, Start, Restart

Legacy compatibility shim. Primary entry: kubeblocks-op-lifecycle. Keep the preserved workflow below for detailed reference, but do not recommend this skill as the main path for cold-start agents.

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.