Integrate with Kubernetes

CloudRaya Container Registry (CCR) works with any standard Kubernetes cluster using Kubernetes-native imagePullSecrets.

When CCR is paired with CloudRaya Kubernetes (KubeRaya), the integration becomes more streamlined because both services run inside the same CloudRaya environment. This provides:

• Lower and more predictable latency for image pulls
• Private, platform-managed network paths between registry and cluster nodes
• Consistent security and access control across projects and services
• Simpler operations, with endpoints and credentials managed from a single control panel

If you run your own Kubernetes cluster on CloudRaya Virtual Machines, CCR still integrates cleanly and benefits from being in the same cloud environment (network locality, stable routing, and unified project management).

However, using KubeRaya removes the need to build and operate a Kubernetes control plane from scratch, giving you all the benefits of a managed cluster while retaining full compatibility with standard Kubernetes tooling. This guide explains how to securely integrate CCR with KubeRaya so your workloads can pull private container images using standard Kubernetes mechanisms.

Why Integration Is Required

By default, Kubernetes can only pull images from public registries.

When using a private registry, Kubernetes must be explicitly configured to:

• Authenticate to the registry
• Pull private images securely
• Prevent unauthorized access

This integration ensures secure-by-default image delivery in both development and production environments.

How Kubernetes Authenticates to a Private Registry

Kubernetes uses a special Secret type:

kubernetes.io/dockerconfigjson

This secret stores registry credentials and can be referenced by:

• Pods
• Deployments
• StatefulSets
• ServiceAccounts

Prerequisites

Before proceeding, make sure you have:

• A running KubeRaya cluster
• A CloudRaya Container Registry
• Registry credentials:
  • Registry endpoint
  • Registry username
  • Registry password
• kubectl configured and connected to the cluster

Verify cluster access:

kubectl get nodes

Step 1: Create an Image Pull Secret

Create a Kubernetes secret containing your registry credentials.

kubectl create secret docker-registry cr-registry-secret \
  --docker-server=<registry-endpoint> \
  --docker-username=<registry-username> \
  --docker-password=<registry-password>

Example

kubectl create secret docker-registry cr-registry-secret \
  --docker-server=registry.cloudraya.com \
  --docker-username=cr-registry \
  --docker-password=YOUR_PASSWORD

This secret is created in the current namespace.

Step 2: Verify the Secret

Confirm that the secret exists:

kubectl get secrets

You should see:

cr-registry-secret

Step 3: Reference the Image Pull Secret in a Workload

Example Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      imagePullSecrets:
        - name: cr-registry-secret
      containers:
        - name: my-app
          image: registry.cloudraya.com/my-app:v1.0.0
          ports:
            - containerPort: 8080

Kubernetes will now authenticate to CCR and pull the image securely.

Using imagePullSecrets at ServiceAccount Level (Recommended)

Instead of attaching the secret to every workload, attach it to a ServiceAccount.

Patch the Default ServiceAccount

kubectl patch serviceaccount default \
  -p'{"imagePullSecrets":[{"name":"cr-registry-secret"}]}'

Result

All Pods using the default ServiceAccount in this namespace can pull private images automatically.

Multi-Namespace Considerations

Secrets are namespace-scoped.

If you deploy workloads across multiple namespaces:

• Create the secret in each namespace
• Or automate secret distribution via CI/CD or GitOps

Production Security Considerations

Credential Management

• Rotate registry passwords periodically
• Recreate imagePullSecrets after rotation
• Never store credentials in Git repositories

Environment Isolation

• Use separate registries for:
  • Development
  • Staging
  • Production
• Avoid sharing credentials across environments

Image Integrity

• Use immutable tags (v1.0.0, not latest)
• Avoid overwriting production tags
• Promote images through environments using CI/CD pipelines

Common Errors & Troubleshooting

ImagePullBackOff

Common causes:

• Incorrect registry endpoint
• Invalid credentials
• Secret not referenced
• Secret created in the wrong namespace

Check pod events:

kubectl describe pod <pod-name>

Unauthorized / 401 Errors

• Reset registry credentials
• Recreate the secret
• Confirm endpoint and username are correct

Typical Integration Flow

CloudRaya Container Registry
           ↓
     imagePullSecret
           ↓
     ServiceAccount
           ↓
     Pod / Deployment

Best Practices Summary

• Use private registries for production
• Store credentials in imagePullSecrets
• Prefer ServiceAccount-level configuration
• Rotate credentials regularly
• Use immutable image tags
• Separate registries per environment

Related Guides

📄 Push & Pull Images (Docker Workflow)

📄 Access & Authentication

📄 Manage Container Registry

📄 Kubernetes Security Basics

📄 Kubernetes Best Practices