Using Private Registry with Kubernetes

This guide covers integrating vCloud Private Registry with Kubernetes clusters for seamless private image deployment and management.

Overview

To use private images from vCloud Registry in Kubernetes, you need to:

1. Create authentication secrets containing registry credentials
2. Configure pods or service accounts to use these secrets
3. Reference private images in your Kubernetes manifests
4. Monitor and troubleshoot image pull operations

1. Creating Registry Secrets

1.1. Create Docker Registry Secret

Create a Kubernetes Secret containing your registry authentication information:

kubectl create secret docker-registry regcred \
  --docker-server=k8s.io.reg.vnetwork.dev \
  --docker-username=<username> \
  --docker-password=<password> \
  --namespace=<namespace>

Where:

• regcred is the name of the Secret (can be customized)
• <username> and <password> are the credentials provided via email
• <namespace> is the Kubernetes namespace where you want to use the Secret

Account Credentials

Registry username and password are provided directly to your email upon service activation. Please check your email or contact VNETWORK support if you haven't received your login credentials.

1.2. Verify Secret Creation

Check that the secret was created successfully:

kubectl get secret regcred -n <namespace>
kubectl describe secret regcred -n <namespace>

2. Using Secrets in Kubernetes Resources

2.1. Adding imagePullSecrets to Pods

Reference the secret directly in pod specifications:

apiVersion: v1
kind: Pod
metadata:
  name: my-private-app
  namespace: <namespace>
spec:
  containers:
  - name: private-app
    image: k8s.io.reg.vnetwork.dev/<namespace>/<repository>:<tag>
    ports:
    - containerPort: 8080
  imagePullSecrets:
  - name: regcred

2.2. Adding imagePullSecrets to ServiceAccount

Instead of adding the secret to each pod, attach it to a ServiceAccount so all pods using that ServiceAccount can access the registry:

kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}]}' -n <namespace>

Verify the ServiceAccount configuration:

kubectl describe serviceaccount default -n <namespace>

3. Using Private Images in Workloads

3.1. Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: <namespace>
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: k8s.io.reg.vnetwork.dev/<namespace>/<repository>:<tag>
        ports:
        - containerPort: 8080
        env:
        - name: ENV
          value: "production"
      imagePullSecrets:
      - name: regcred

3.2. StatefulSet Example

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: my-stateful-app
  namespace: <namespace>
spec:
  serviceName: "my-service"
  replicas: 3
  selector:
    matchLabels:
      app: my-stateful-app
  template:
    metadata:
      labels:
        app: my-stateful-app
    spec:
      containers:
      - name: my-app
        image: k8s.io.reg.vnetwork.dev/<namespace>/<repository>:<tag>
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: data
          mountPath: /data
      imagePullSecrets:
      - name: regcred
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi

3.3. DaemonSet Example

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: my-daemon
  namespace: <namespace>
spec:
  selector:
    matchLabels:
      app: my-daemon
  template:
    metadata:
      labels:
        app: my-daemon
    spec:
      containers:
      - name: my-daemon
        image: k8s.io.reg.vnetwork.dev/<namespace>/<repository>:<tag>
        resources:
          limits:
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 100Mi
      imagePullSecrets:
      - name: regcred
      tolerations:
      - key: node-role.kubernetes.io/master
        effect: NoSchedule

4. Verification and Monitoring

4.1. Check Pod Status

Monitor pod creation and image pull status:

kubectl get pods -n <namespace>
kubectl describe pod <pod-name> -n <namespace>

Look for the "Events" section in the describe output to see the image pull process.

4.2. Image Pull Logs

Check detailed logs for image pull operations:

# Check pod events
kubectl get events --sort-by=.metadata.creationTimestamp -n <namespace>

# Check specific pod events
kubectl describe pod <pod-name> -n <namespace> | grep -A 10 Events

4.3. Verify Image Pull Success

Successful image pulls will show events like:

Normal  Pulling    Started pulling image "k8s.io.reg.vnetwork.dev/myteam/myapp:1.0.0"
Normal  Pulled     Successfully pulled image "k8s.io.reg.vnetwork.dev/myteam/myapp:1.0.0"
Normal  Created    Created container my-app
Normal  Started    Started container my-app

5. Troubleshooting

5.1. Common Issues and Solutions

Authentication Errors

Error: ErrImagePull or ImagePullBackOff

Solutions:

1. Verify secret exists and is correctly configured:

kubectl get secret regcred -n <namespace> -o yaml

2. Check secret data is properly base64 encoded:

kubectl get secret regcred -n <namespace> -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

3. Ensure imagePullSecrets is added to pod/deployment specification

Network Connectivity Issues

Error: Connection timeouts or DNS resolution failures

Solutions:

1. Test connectivity from cluster nodes:

# Test from a node
curl -I https://k8s.io.reg.vnetwork.dev

# Test DNS resolution
nslookup k8s.io.reg.vnetwork.dev

2. Check network policies and firewall rules
3. Verify registry endpoint accessibility

Permission Issues

Error: 403 Forbidden or access denied errors

Solutions:

1. Verify namespace permissions in the private registry
2. Check username/password credentials
3. Ensure repository exists and is accessible
4. Contact support to verify account permissions

5.2. Debugging Commands

# List all secrets in namespace
kubectl get secrets -n <namespace>

# Check secret content
kubectl get secret regcred -n <namespace> -o yaml

# Check ServiceAccount imagePullSecrets
kubectl describe serviceaccount default -n <namespace>

# Get detailed pod information
kubectl describe pod <pod-name> -n <namespace>

# Check cluster events
kubectl get events --all-namespaces --sort-by=.metadata.creationTimestamp

6. Advanced Configuration

6.1. Multiple Registry Secrets

You can configure multiple registry secrets for different registries:

spec:
  imagePullSecrets:
  - name: regcred-vnetwork
  - name: regcred-dockerhub
  - name: regcred-gcr

6.2. Creating Secret from Docker Config

For CI/CD automation, create secrets from existing Docker configuration:

kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson \
  -n <namespace>

6.3. Namespace-wide Configuration

Apply imagePullSecrets to all ServiceAccounts in a namespace:

# Get all ServiceAccounts
kubectl get serviceaccounts -n <namespace>

# Patch each ServiceAccount
for sa in $(kubectl get serviceaccounts -n <namespace> -o name); do
  kubectl patch $sa -n <namespace> -p '{"imagePullSecrets": [{"name": "regcred"}]}'
done

Best Practices

Security

• Least Privilege: Grant minimal necessary permissions to registry namespaces
• Secret Management: Use secure secret management tools in production
• Regular Rotation: Rotate registry credentials periodically
• Audit: Monitor registry access and image pull activities

Performance

• Image Optimization: Use multi-stage builds to minimize image sizes
• Layer Caching: Optimize Dockerfile for better layer caching
• Local Caching: Configure node-level image caching for frequently used images
• Resource Limits: Set appropriate resource limits for containers

Operations

• Monitoring: Set up monitoring for image pull failures and performance
• Automation: Automate secret creation and updates in CI/CD pipelines
• Documentation: Document image naming conventions and deployment procedures
• Testing: Test image pulls in staging environments before production

---

For more information about Private Registry features and management, see the Private Registry Overview.