How-To

Troubleshoot Cloud-Vinyl

Type: How-To (Task-oriented)

Difficulty: Intermediate

Operator Pod Not Starting

Check Pod Status

kubectl get pods -n cloud-vinyl-system
kubectl describe pod -n cloud-vinyl-system -l app.kubernetes.io/name=cloud-vinyl

Common Causes

cert-manager not ready: The operator webhooks require TLS certificates from cert-manager. Check cert-manager is running:

kubectl get pods -n cert-manager
kubectl get certificate -n cloud-vinyl-system

Image pull failure: Verify the operator image is accessible:

kubectl get events -n cloud-vinyl-system --field-selector reason=Failed

VinylCache Not Becoming Ready

Check VinylCache Status

kubectl get vinylcache <name> -n <namespace> -o yaml

Look at the status.conditions array for:

  • Ready — overall readiness

  • VCLSynced — VCL successfully loaded in all pods

  • BackendsAvailable — backend services are reachable

Check Operator Logs

kubectl logs -n cloud-vinyl-system -l app.kubernetes.io/name=cloud-vinyl --tail=100

Check Agent Logs

kubectl logs <varnish-pod> -n <namespace> -c vinyl-agent --tail=50

ArgoCD Sync Issues

HelmChart Stuck

If the HelmChart resource shows errors:

kubectl get helmchart -n cloud-vinyl-system
kubectl describe helmchart cloud-vinyl -n cloud-vinyl-system

Common fix: K3S Helm controller may need time to pull OCI charts. Check K3S Helm controller logs:

kubectl logs -n kube-system -l app=helm-controller --tail=50