External private registries

This guide explains how to pull container images from external private registries in CFKE, such as AWS ECR, GCP Artifact Registry, Docker Hub, and self-hosted registries.

If you want to use Cloudfleet’s managed container registry, see Container registry. Cloudfleet Container Registry (CFCR) integrates with CFKE, so your clusters pull images automatically without any credentials.

Pulling from external registries

When you deploy a workload in Cloudfleet Kubernetes Engine (CFKE), you can pull container images from public or private container registries.

CFKE has built-in support to pull images from AWS Elastic Container Registry or GCP Artifact Registry without using hardcoded credentials. For these services, you authorize Cloudfleet-owned roles from GCP and AWS to pull images from your private registries.

AWS Elastic Container Registry

CFKE is set up to assume an AWS role that Cloudfleet owns. When you authorize this role on your AWS account, CFKE can pull images from your private ECR repositories. CFKE authenticates to this role.

To authorize the provider to access the ECR repository, create a policy in the ECR repository. Use this policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ECRRepositoryPolicy",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::CLOUDFLEET_AWS_ACCOUNT_ID:role/cfke-CLUSTER_ID"
      },
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ]
    }
  ]
}

Replace CLOUDFLEET_AWS_ACCOUNT_ID with the corresponding Cloudfleet AWS account ID based on your control plane region. The possible values are:

Replace CLUSTER_ID with the cluster ID.

GCP Artifact Registry

To authorize CFKE to access the Artifact Registry, authorize the following principal in the relevant Artifact Registry repository with the artifactregistry.reader role:

principal://iam.googleapis.com/projects/207152264238/locations/global/workloadIdentityPools/cfke/subject/CLUSTER_ID

Replace CLUSTER_ID with the cluster ID.

Other private registries

For private registries other than AWS ECR or GCP Artifact Registry, create an image pull secret with your registry credentials. This applies to Docker Hub, GitHub Container Registry, GitLab Container Registry, self-hosted registries, and any other registry that requires authentication. For the full guide, see the Kubernetes documentation.

Creating an image pull secret

Create a Secret that contains your registry credentials:

kubectl create secret docker-registry my-registry-secret \
  --docker-server=REGISTRY_SERVER \
  --docker-username=USERNAME \
  --docker-password=PASSWORD \
  --docker-email=EMAIL

Replace the placeholders with your registry details:

• REGISTRY_SERVER: The registry URL (for example, https://index.docker.io/v1/ for Docker Hub, ghcr.io for GitHub, registry.gitlab.com for GitLab)
• USERNAME: Your registry username
• PASSWORD: Your registry password or access token
• EMAIL: Your email address

Using the secret in your Pods

Reference the Secret in your Pod specification:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: my-app
    image: my-registry.example.com/my-image:latest
  imagePullSecrets:
  - name: my-registry-secret