OpenCloud Runbook¶

Metadata¶

Field	Value
Service	OpenCloud
Criticality	Tier 3 while under evaluation
Owner	Homelab operator
Namespace	opencloud
Clusters	local
Last validated	2026-09-14
Related service page	`docs/services/opencloud.md`

Trigger Conditions¶

https://opencloud.mutana.fr does not show the login page.
Sync, upload, sharing, or login tests fail.
The OpenCloud pod is Pending, unready, or restarting.
A planned image upgrade or restore drill is being performed.
Fleet reports that the opencloud namespace cannot be imported into release local-opencloud because Helm ownership metadata is missing.

1. Health Checks¶

kubectl --context rancher -n opencloud get deploy,pod,svc,pvc,ingressroute
kubectl --context rancher -n opencloud get endpoints opencloud
kubectl --context rancher -n opencloud logs deploy/opencloud --tail=200
curl -fsSIL https://opencloud.mutana.fr

Expected state is one available pod, two Bound PVCs, one Service endpoint, and an HTTPS response from OpenCloud.

Fleet ownership adoption¶

opencloud/fleet.yaml enables helm.takeOwnership. If Fleet previously failed because the namespace came from a direct Kustomize deployment, commit the bundle correction and let Fleet retry. Confirm the bundle becomes Ready:

kubectl --context rancher -n fleet-local get bundle local-opencloud

Do not manually label or annotate the namespace unless Fleet still fails after the corrected bundle has been delivered; an emergency live metadata patch must be approved and reconciled back into Git.

Probe verification¶

kubectl --context rancher -n opencloud describe pod \
  -l app.kubernetes.io/name=opencloud

The startup, readiness, and liveness checks use TCP port 9200. A passing TCP check proves the process listens; confirm the login flow separately over HTTPS.

2. Troubleshooting Workflows¶

CrashLoopBackOff or frequent restarts¶

kubectl --context rancher -n opencloud logs deploy/opencloud --previous
kubectl --context rancher -n opencloud get secret opencloud-secrets
kubectl --context rancher -n opencloud describe deploy opencloud

Confirm the Secret exists with key IDM_ADMIN_PASSWORD without printing its value. Check logs for initialization, configuration, or filesystem permission errors. Password changes in the Secret are ignored after first initialization.

Pod stuck in Pending¶

kubectl --context rancher -n opencloud describe pod \
  -l app.kubernetes.io/name=opencloud
kubectl --context rancher -n opencloud get pvc
kubectl --context rancher get nodes -o wide

Check PVC provisioning, node capacity, taints, and the selected node associated with the RWO local-path volumes.

PVC, mount, or storage errors¶

kubectl --context rancher -n opencloud describe pvc opencloud-config
kubectl --context rancher -n opencloud describe pvc opencloud-data
kubectl --context rancher get pv

The container runs as UID/GID 1000 and the pod applies fsGroup 1000. Investigate ownership and mount events before changing those identities.

Ingress, auth, or connectivity failures¶

kubectl --context rancher -n opencloud describe ingressroute opencloud
kubectl --context rancher -n opencloud get svc,endpoints
kubectl --context rancher -n traefik logs daemonset/traefik --tail=200

Confirm DNS, the opencloud.mutana.fr host rule, TLS, endpoint readiness, and that OC_URL exactly matches the public HTTPS URL.

3. Disaster Recovery¶

There is no supported backup yet. Treat the evaluation data as disposable. A future recovery procedure must restore opencloud-config and opencloud-data from the same recovery point, recreate opencloud-secrets, reapply the overlay, and validate login plus representative files and shares.

Recovery dependency order is cluster networking, local-path provisioner, Traefik, the bootstrap Secret, both PVCs, then the Deployment.

4. Scaling and Resource Management¶

The RWO local-path storage and embedded filesystem state make this a single-replica workload. Do not scale horizontally. Inspect use before changing the 250m CPU / 512Mi memory request or 2Gi memory limit:

kubectl --context rancher -n opencloud top pod --containers
kubectl --context rancher -n opencloud describe pod \
  -l app.kubernetes.io/name=opencloud

5. Maintenance Procedures¶

Before an image upgrade, preserve the current image pin, review upstream release and upgrade notes, and establish a recoverable PVC copy. Update the pin in Git, render and diff the overlay, apply it, then validate login, upload, download, share, and sync behavior. Test backups and restores before migrating real data.

Admin-password rotation uses the OpenCloud UI or CLI after initialization. A Secret-only update is insufficient.

6. Rollback Strategy¶

Revert the image pin to the previous production version and reapply the overlay. Scale the Deployment down first if an upstream migration makes the stored data incompatible. If evaluation must stop, delete the Deployment and IngressRoute while retaining both PVCs until the operator explicitly approves data removal. Nextcloud remains independent throughout rollback.

7. Post-Incident Actions¶

Record the failed test, relevant OpenCloud logs, image version, affected node, and whether data integrity was checked. Update this runbook when recovery steps change, add a changelog fragment for material fixes, and reconcile emergency cluster changes into Git.