How-To

Generate Kubeconfig for Tenant Owner¶

This guide shows how to create a kubeconfig file for a tenant owner to access the cluster.

Prerequisites¶

Tenant created and synced (see Create Tenant)
kubectl configured with cluster-admin access

Quick Method: Use the Script¶

The easiest way is to use the provided script:

cd dp-infra/capsule
./scripts/generate-kubeconfig.sh <tenant-name> [duration]

Examples¶

# Generate kubeconfig for 'bd' tenant (token valid 1 year)
./scripts/generate-kubeconfig.sh bd

# Generate kubeconfig for 'kup' tenant (token valid 30 days)
./scripts/generate-kubeconfig.sh kup 720h

# Generate kubeconfig for 'programmatic' tenant
./scripts/generate-kubeconfig.sh programmatic

The script creates kubeconfig-<tenant>.yaml with:

Cluster CA and API server from current context
Long-lived ServiceAccount token
Helpful usage comments

Test the Generated Kubeconfig¶

export KUBECONFIG=kubeconfig-bd.yaml

# Verify permissions
kubectl auth can-i create namespaces
# → yes

# Create test namespace
kubectl create namespace bd-test

# Clean up
kubectl delete namespace bd-test

Manual Method¶

If you need more control, follow these manual steps:

1. Generate ServiceAccount Token¶

# Generate long-lived token (1 year)
TOKEN=$(kubectl create token bd-sa -n capsule-system --duration=8760h)

2. Get Cluster Info¶

# Get API server and CA from current kubeconfig
API_SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CLUSTER_CA=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
CLUSTER_NAME=$(kubectl config view --minify -o jsonpath='{.clusters[0].name}')

3. Create Kubeconfig File¶

cat > kubeconfig-bd.yaml << EOF
apiVersion: v1
kind: Config
clusters:
  - cluster:
      server: ${API_SERVER}
      certificate-authority-data: ${CLUSTER_CA}
    name: ${CLUSTER_NAME}
contexts:
  - context:
      cluster: ${CLUSTER_NAME}
      user: bd
    name: bd@${CLUSTER_NAME}
current-context: bd@${CLUSTER_NAME}
users:
  - name: bd
    user:
      token: ${TOKEN}
EOF

chmod 600 kubeconfig-bd.yaml

Distributing Kubeconfigs¶

Important: Kubeconfig files contain bearer tokens. Handle securely:

Use encrypted email or secure file sharing
Consider password-protected archive
Document token expiration date
Store in a secrets manager if automated access is needed

Token Renewal¶

Tokens expire based on the --duration flag. To renew:

# Re-run the script
./scripts/generate-kubeconfig.sh bd

# Or manually update existing kubeconfig
NEW_TOKEN=$(kubectl create token bd-sa -n capsule-system --duration=8760h)
kubectl config set-credentials bd --token="${NEW_TOKEN}" --kubeconfig=kubeconfig-bd.yaml

Troubleshooting¶

“Forbidden” errors when listing namespaces¶

This is expected behavior. Kubernetes RBAC requires cluster-level permissions to list namespaces:

# Access specific namespaces (works)
kubectl get pods -n bd-myproject

# List all namespaces (fails - expected)
kubectl get namespaces

For namespace listing capability, consider deploying Capsule Proxy.

ServiceAccount not found¶

Ensure the tenant is defined in config.yaml and deployed:

# Check if ServiceAccount exists
kubectl get serviceaccount bd-sa -n capsule-system

# If not, verify tenant in config.yaml and re-deploy
kubectl get tenants

Token expired¶

Generate a new token:

./scripts/generate-kubeconfig.sh bd