Container Registry

Overview

This section allows you to define the container registries available within your organization. Once configured, only images stored in these registered container registries will be allowed to be deployed on your clusters. By connecting container registries to your organization, you can deploy applications using images from these registries across all your projects and environments.

Container registries configured here apply to the entire organization and are available for all projects.

Accessing Container Registry Settings

To manage container registries:

Navigate to Organization Settings → Container Registries
You’ll see a list of all configured registries

Supported Registry Types

Qovery supports the following container registry providers:

ECR (AWS Elastic Container Registry)
GCP Artifact Registry (Google Cloud Artifact Registry)
ACR (Azure Container Registry)
DOCR (DigitalOcean Container Registry)
Scaleway Container Registry
Docker Hub
GitHub Container Registry (GHCR)
GitHub Enterprise Container Registry
GitLab Container Registry
Public ECR (AWS Public Elastic Container Registry)
Generic Container Registry (any Docker-compatible registry accessible via docker login)

Create a Container Registry

Click Add Registry

Press the Add Registry button to create a new container registry connection

Select Registry Type

Choose your registry provider from the dropdown menu

Provide Required Information

Enter the necessary authentication details based on your registry type.Example for AWS ECR:

Registry URL: https://<aws_account_id>.dkr.ecr.<region>.amazonaws.com
Region: AWS region where your ECR is located (e.g., us-east-1, eu-west-1)
Authentication type:
- Assume role via STS (recommended): the Role ARN of an IAM role Qovery can assume. See AWS ECR with STS assume role.
- Static credentials: an AWS IAM Access Key ID and Secret Access Key with ECR permissions

Each registry type requires different configuration fields. The form will adapt based on your selection.

Test Connection

Qovery will automatically test the connection to verify credentials

Save Registry

Click Save to add the registry to your organization

Once added, the container registry will be available for all projects and environments in your organization.

AWS ECR with STS Assume Role

With Assume role via STS, Qovery calls sts:AssumeRole on the role you provide and gets temporary credentials. It uses them to list your images and tags in the Console and to pull images at deployment time. No long-lived AWS keys are stored on the Qovery side.

Trust Policy

The role must trust the same Qovery principal as the role used for AWS cluster credentials. You can either:

Reuse your cluster role: if you created the qovery-role-creation CloudFormation stack for your cluster, the role it creates already includes ecr:*. Use its ARN for the registry. That role also has broad cluster management permissions (iam:*, ec2:*, eks:*, kms:*, …), so the registry connection gets them too. For least privilege, create a dedicated role.
Create a dedicated role: copy the AssumeRolePolicyDocument from the Qovery CloudFormation template into your role’s trust policy, then attach the permissions policy below.

Qovery sends an external ID on every sts:AssumeRole call:

When	External ID
Deploying a service that uses this registry	The container registry’s Qovery ID
Listing images and tags in the Console	`00000000-0000-0000-0000-000000000000`

If you add an sts:ExternalId condition to the trust policy, allow the all-zeros value and the Qovery ID of every registry that uses the role. Without a registry’s ID, every deployment that pulls from that registry fails. Without the all-zeros value, the Console can’t validate the registry or list your images. The registry ID only exists once the registry is created, so set it up in this order:

Create the role with only the all-zeros value in the condition.
Create the registry in Qovery with the role ARN. The Console validates it with the all-zeros value.
Open the registry’s edit form and copy its Qovery ID.
Add that ID to the sts:ExternalId condition.

Trust policy condition

"Condition": {
  "StringEquals": {
    "sts:ExternalId": [
      "<registry-1-qovery-id>",
      "<registry-2-qovery-id>",
      "00000000-0000-0000-0000-000000000000"
    ]
  }
}

Permissions Policy

A dedicated role needs these ECR permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:DescribeRepositories"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:GetDownloadUrlForLayer",
        "ecr:ListImages"
      ],
      "Resource": "arn:aws:ecr:<region>:<aws_account_id>:repository/*"
    }
  ]
}

ecr:DescribeRepositories needs "Resource": "*" because the Console’s image search lists every repository in the registry. If the repositories live in a different AWS account than the role, this policy isn’t enough. Each repository’s policy must also allow the role ARN for the same actions. Once the role exists, select Assume role via STS in the registry form and paste the role ARN.

Modify an Existing Registry

To edit a container registry:

Locate the registry in the Container Registry list
Click the wheel button (edit icon) next to the registry
Update the registry configuration as needed
Click Save to apply changes

Updating registry credentials will affect all applications using images from this registry. Ensure new credentials are valid before saving.

Delete a Container Registry

To remove a container registry:

Locate the registry in the Container Registry list
Click the trash button (delete icon) next to the registry
Confirm the deletion

Before deleting a registry, make sure that there are no applications within your organization using images stored in this registry. Deleting a registry may prevent deployments from succeeding.

Best Practices

Organize by Environment

Consider creating separate registry connections for different environments (development, staging, production) for better security and access management.

Use Descriptive Names

Name registries clearly to indicate their purpose:

aws-ecr-production-us-east-1
docker-hub-public-images
gcr-staging-europe

Regular Credential Rotation

Periodically rotate registry credentials for security:

Create new credentials in your registry provider
Update the registry configuration in Qovery
Test with a deployment
Remove old credentials from the provider

Cloud Credentials

Manage cloud provider credentials

Applications

Deploy applications using container images

Git Repository Access

Configure Git repository access

Helm Repository

Manage Helm chart repositories

Overview

Account & Organization

Clusters & Cloud

Source Control

Projects & Environments

Services

Deployment & CI/CD

Environment Variables & Secrets

Observability

Notifications

Networking & Advanced

Container Registry

Overview

Accessing Container Registry Settings

Supported Registry Types

Create a Container Registry

AWS ECR with STS Assume Role

Trust Policy

Permissions Policy

Modify an Existing Registry

Delete a Container Registry

Best Practices

Cloud Credentials

Applications

Git Repository Access

Helm Repository

​Overview

​Accessing Container Registry Settings

​Supported Registry Types

​Create a Container Registry

​AWS ECR with STS Assume Role

​Trust Policy

​Permissions Policy

​Modify an Existing Registry

​Delete a Container Registry

​Best Practices

​Related Resources

Cloud Credentials

Applications

Git Repository Access

Helm Repository

Overview

Accessing Container Registry Settings

Supported Registry Types

Create a Container Registry

AWS ECR with STS Assume Role

Trust Policy

Permissions Policy

Modify an Existing Registry

Delete a Container Registry

Best Practices

Related Resources