Container Registry

Edka supports multiple container registries to store and manage your Docker images. This guide covers setup and configuration for supported registries.

Supported Registries

• GitHub Container Registry (ghcr.io)
• Docker Hub
• AWS Elastic Container Registry (ECR)
• Google Artifact Registry
• Custom Container Registry
• In-Cluster Zot Registry (per-cluster)

External registry credentials are stored once at the account level under Integrations > External Container Registry, then applied to individual clusters from each cluster’s Registry > External Registries tab (where one can be set as the cluster default).

How external registry sync works

External registries are configured in two steps:

1. Add the registry credential under Integrations > External Container Registry.
2. Apply it to a cluster from Clusters > your cluster > Registry > External Registries.

When a registry is applied to a cluster, Edka installs and configures the edka-registry-operator inside the cluster. The operator continuously reconciles registry pull credentials:

• Creates a kubernetes.io/dockerconfigjson pull Secret named edka-registry-<registry-name> in every active namespace.
• Adds that pull Secret to the namespace’s default ServiceAccount imagePullSecrets.
• Watches for new namespaces and adds credentials there automatically.
• Updates credentials when the account-level registry credential changes.
• Removes managed pull Secrets when a registry is no longer applied to the cluster.
• Renews AWS ECR Docker authorization tokens before they expire.

If your workload uses the namespace’s default ServiceAccount, no extra Kubernetes configuration is required. If your workload uses a custom ServiceAccount, add the generated pull Secret to that ServiceAccount’s imagePullSecrets.

Changing the cluster default registry does not remove credentials for other applied registries. To stop distributing a registry’s pull credentials, remove it from the cluster’s applied registries.

Build pushes and workload pulls

Registry credentials are used in two places:

• Kubernetes pulls: the in-cluster operator creates namespace pull Secrets so pods can pull private images.
• Edka build pushes: branch deployment builds create a per-build Docker config so BuildKit can push the built image to the cluster default registry.

Docker Hub, GHCR, Google Artifact Registry, and custom Docker-compatible registries use the configured Docker credential directly.

AWS ECR is different. Store an AWS access key ID, secret access key, and registry URL in Edka. Edka exchanges those IAM credentials for short-lived ECR Docker authorization tokens when syncing Kubernetes pull Secrets and when creating build jobs. Do not paste the output of aws ecr get-login-password into Edka as the long-lived registry password.

In-Cluster Zot Registry

Edka also supports an in-cluster registry powered by Zot.

• Managed from the cluster’s Registry tab > Cluster Registry sub-tab.
• Includes runtime visibility (pods/workload/resource usage/volume usage).
• Supports safe storage expansion for existing installations.

For full operational guidance, see:

• Cluster Registry (In-Cluster Zot)

GitHub Container Registry

Overview

GitHub Container Registry (ghcr.io) stores images alongside GitHub repositories and works directly with GitHub Actions.

Benefits:

• Free for public images
• 500MB storage for private repos (free tier)
• Integrated with GitHub Actions
• Fine-grained permissions

Setup

1. Enable GitHub Packages

1. Go to your GitHub account settings
2. Navigate to Developer settings > Personal access tokens
3. Generate a new token (classic) with scopes:
   • write:packages - Upload images
   • read:packages - Pull images
   • delete:packages - Delete images (optional)

2. Configure in Edka

1. In Edka dashboard, go to Integrations > External Container Registry
2. Select GitHub Container Registry
3. Enter:
   • Registry Name: a unique identifier you choose
   • Registry URL: ghcr.io
   • Username: Your GitHub username
   • Token: Personal access token
4. Click Save

Docker Hub

Overview

Docker Hub is the default registry for Docker images, with public and private repositories.

Benefits:

• Unlimited public repositories
• 1 private repository (free tier)
• Official images
• Automated builds

Setup

1. Create Docker Hub Account

1. Sign up at hub.docker.com
2. Create an access token:
   • Go to Account Settings > Security
   • Click New Access Token
   • Set permissions and generate

2. Configure in Edka

1. Navigate to Integrations > External Container Registry
2. Select Docker Hub
3. Enter:
   • Registry Name: a unique identifier you choose
   • Username: Docker Hub username
   • Password: Access token
4. Click Save

Rate Limits

Anonymous users: 100 pulls per 6 hours Authenticated users: 200 pulls per 6 hours Paid users: Unlimited

AWS Elastic Container Registry

Overview

AWS ECR stores container images and authenticates through AWS IAM.

Benefits:

• Integrated with AWS IAM
• Vulnerability scanning
• Image replication
• Lifecycle policies

Setup

1. Create ECR Repository

# Create repository
aws ecr create-repository --repository-name my-app --region us-east-1

2. Configure IAM

Use an IAM user or role that can request ECR authorization tokens and access the repositories Edka will use.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ecr:GetAuthorizationToken",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:BatchCheckLayerAvailability",
                "ecr:BatchGetImage",
                "ecr:CompleteLayerUpload",
                "ecr:GetDownloadUrlForLayer",
                "ecr:InitiateLayerUpload",
                "ecr:PutImage",
                "ecr:UploadLayerPart"
            ],
            "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-app"
        }
    ]
}

If Edka only needs to pull existing images from ECR, keep ecr:BatchGetImage and ecr:GetDownloadUrlForLayer in the repository statement. If Edka builds and pushes images to ECR, keep the write actions shown above.

3. Configure in Edka

1. Go to Integrations > External Container Registry
2. Select AWS ECR
3. Enter:
   • Registry Name: a unique identifier you choose
   • Registry URL: 123456789012.dkr.ecr.us-east-1.amazonaws.com
   • Access Key ID: AWS access key
   • Secret Access Key: AWS secret key
4. Click Save

For FIPS or GovCloud endpoints, also fill in the AWS Region field (for example us-gov-west-1).

4. Apply to a cluster

1. Open the cluster’s Registry page.
2. Select the External Registries tab.
3. Apply the ECR registry to the cluster.
4. Set it as the default registry if Edka builds should push new images there.

After the registry is applied, newly created namespaces receive the ECR pull Secret automatically. ECR tokens are renewed inside the cluster before they expire.

Google Artifact Registry

Overview

Google Artifact Registry is Google Cloud’s container registry, with regional and multi-regional storage.

Benefits:

• Regional and multi-regional storage
• Vulnerability scanning
• Binary authorization

Setup

1. Enable API and Create Repository

# Enable API
gcloud services enable artifactregistry.googleapis.com

# Create repository
gcloud artifacts repositories create my-repo \
  --repository-format=docker \
  --location=us-central1 \
  --description="My container images"

2. Configure Authentication

# Configure Docker
gcloud auth configure-docker us-central1-docker.pkg.dev

# Create service account
gcloud iam service-accounts create edka-registry

# Grant permissions
gcloud artifacts repositories add-iam-policy-binding my-repo \
  --location=us-central1 \
  --member="serviceAccount:edka-registry@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.reader"

# Create key
gcloud iam service-accounts keys create key.json \
  --iam-account=edka-registry@PROJECT_ID.iam.gserviceaccount.com

3. Configure in Edka

1. Navigate to Integrations > External Container Registry
2. Select Google Artifact Registry
3. Enter:
   • Registry Name: a unique identifier you choose
   • Registry URL: us-central1-docker.pkg.dev
   • Project ID: Your GCP project
   • Service Account Key: Contents of key.json
4. Click Save

Troubleshooting

New namespace cannot pull private images

Wait for the registry operator to reconcile, or trigger an immediate sync with Sync Now on the cluster’s Registry > External Registries tab. Then check that the namespace has an edka-registry-<registry-name> Secret and that the namespace’s default ServiceAccount references it. If the workload uses a custom ServiceAccount, add the same Secret to that ServiceAccount’s imagePullSecrets.

ECR build push returns 401 Unauthorized

A namespace pull Secret only affects Kubernetes image pulls. Edka build pushes use a separate BuildKit Docker config generated for the build job. Check that:

• The ECR registry is the cluster default registry when the build starts.
• The ECR registry URL is correct.
• The AWS credentials can call ecr:GetAuthorizationToken.
• The IAM policy includes ECR push permissions for the target repository when Edka is building and pushing images.