How-To

Troubleshoot Capsule

Common issues and solutions for Capsule multi-tenancy.

Capsule Operator Issues

Operator Pod Not Running

# Check operator status
kubectl get pods -n capsule-system

# Check operator logs
kubectl logs -n capsule-system deployment/capsule-controller-manager

Common causes:

  • Insufficient resources (check resource limits)

  • Webhook certificate issues

  • CRD not installed

Webhook Errors

If namespace creation fails with webhook errors:

# Check webhook configuration
kubectl get validatingwebhookconfigurations | grep capsule

# Check webhook service
kubectl get svc -n capsule-system

Tenant Issues

Tenant Not Active

kubectl get tenant bd -o yaml

Check status.state. If not “Active”:

  • Verify owner exists (ServiceAccount)

  • Check for conflicting tenant definitions

Namespace Creation Fails

Error: “namespace name must match tenant prefix”

# Wrong - doesn't match prefix
kubectl create namespace my-namespace
# → Error

# Correct - matches tenant prefix
kubectl create namespace bd-my-namespace
# → Created

Error: “namespace quota exceeded”

# Check current namespace count
kubectl get tenant bd -o jsonpath='{.status.namespaces}'

# Check quota
kubectl get tenant bd -o jsonpath='{.spec.namespaceOptions.quota}'

Solution: Delete unused namespaces or request quota increase.

Resource Quota Exceeded

# Check tenant resource usage
kubectl describe tenant bd

Look for resourceQuotas in status. If exceeded:

  • Delete unused resources in tenant namespaces

  • Request quota increase from admin

Access Issues

“Forbidden” When Accessing Namespace

Verify tenant membership:

# Check who you are
kubectl auth whoami

# Check tenant owners
kubectl get tenant bd -o jsonpath='{.spec.owners}'

Ensure ServiceAccount name matches exactly:

  • Format: system:serviceaccount:<namespace>:<name>

  • Example: system:serviceaccount:capsule-system:bd-sa

Token Expired

If getting authentication errors:

# Check token expiration
echo $TOKEN | cut -d. -f2 | base64 -d | jq '.exp | . as $e | now | $e - . | . / 3600 | "Hours remaining: \(.)"'

Generate new token if expired:

kubectl create token bd-sa -n capsule-system --duration=8760h

ArgoCD Sync Issues

Application Out of Sync

# Check ArgoCD application
kubectl get application capsule -n argocd

# Force sync
argocd app sync capsule

Tenant CRD Missing

If tenant creation fails with “unknown resource”:

# Check CRDs
kubectl get crd | grep capsule

# Expected CRDs
# tenants.capsule.clastix.io
# globaltenantresources.capsule.clastix.io

If CRDs missing, ensure Capsule Helm chart deployed successfully.