Linking an Existing Docker Registry
Porter supports linking a private Docker container registry to your project. This container registry is used to deploy Docker containers onto a cluster and push new versions of the image to your registry from CI/CD workflows. We support the following container registries:
- Amazon Elastic Container Registry (ECR)
- Google Artifact Registry (GAR)
- Google Container Registry (GCR)
- DigitalOcean Container Registry
- Docker Hub
- Other registries which implement the Registry HTTP API v2
The following guide will show you how to link your container registries depending on your registry provider. Some container registries can only be linked from the CLI, so make sure that you’ve following the installation guide for the CLI.
Amazon Elastic Container Registry (ECR)
In order to link ECR, an AWS IAM user must be created in your AWS account with access to push, pull and list images from the ECR registry. If you are logged in via the AWS CLI, Porter can generate these credentials for you automatically when you run porter connect ecr
. Alternatively, you must first create an ECR user and have those credentials ready for the next step!
You can link ECR using either the dashboard or the CLI:
Browser
CLI
In order to link an existing ECR registry from the dashboard, navigate to the Integrations tab and select Docker Registry. Then, select Add a Registry in top right, and select Elastic Container Registry. Give the registry a name, for example my-awesome-registry
:
Next, input the AWS credentials (if you do not have your AWS credentials, follow the instructions below). Then, click Save Settings.
To verify that the ECR registry was linked correctly, you can navigate to the Integrations tab, click Docker Registry, and expand a registry to make sure you see all repositories listed.
Troubleshooting
If you are unable to connect to your registry, double-check that the user exists, the region is correct, and the credentials were copied correctly.
Creating an AWS ECR User
Before linking your ECR registry, you can create an AWS IAM user that has access to ECR, and then generate AWS credentials. To create a new user, go to your AWS console and navigate to IAM -> Users and select Add user:
Give your user a name and select Programmatic access. After selecting Next, you will be prompted to set permissions for your user, choose Attach existing policies directly and search for the policy AmazonEC2ContainerRegistryFullAccess
that can push/pull images from ECR.
After creating this user, you will see an AWS Access Key and Secret — make sure you have these credentials ready, and link your ECR registry using the instructions above.
Google Artifact Registry (GAR)
Creating a GCP Service Account for GAR
Before you can connect to an existing GAR instance, you must create a service account with permission to push/pull from GAR. To do this, follow the steps below.
- First, go to your Google Cloud console and navigate to IAM & Admin -> Service Accounts:
- Select Create Service Account:
- Name your service account (for example, “porter-gar-access”), grant the service account Artifact Registry Administrator permissions, then select Done:
- After creating the service account, you will be redirected to the list of service accounts. Find the row with the newly created service account, and select “Manage keys” in the “Actions” column:
- Finally, press the “Add key” dropdown and select “Create new key”. After choosing the JSON key type, your key file will be automatically downloaded:
Linking GAR
Now that you have a service account and JSON key downloaded, linking GAR can either be done from the dashboard or the CLI:
Browser
CLI
In order to link an existing GAR registry from the dashboard, navigate to the Integrations tab and select Docker Registry. Then, select Add a Registry in top right, and select Google Artifact Registry. Give the registry a name, for example my-awesome-registry
:
Next, input the GCP credentials that you downloaded above, and enter your GAR region.
Then, click Save Settings.
Google Container Registry (GCR)
Creating a GCP Service Account for GCR
Before you can connect to an existing GCR instance, you must create a service account with permission to push/pull from GCR. To do this, follow the steps below.
- First, go to your Google Cloud console and navigate to IAM & Admin -> Service Accounts:
- Select Create Service Account:
- Name your service account (for example, “porter-gcr-access”), grant the service account Storage Admin permissions, then select Done:
- After creating the service account, you will be redirected to the list of service accounts. Find the row with the newly created service account, and select “Manage keys” in the “Actions” column:
- Finally, press the “Add key” dropdown and select “Create new key”. After choosing the JSON key type, your key file will be automatically downloaded:
Linking GCR
Now that you have a service account and JSON key downloaded, linking GCR can either be done from the dashboard or the CLI:
Browser
CLI
In order to link an existing GCR registry from the dashboard, navigate to the Integrations tab and select Docker Registry. Then, select Add a Registry in top right, and select Google Container Registry. Give the registry a name, for example my-awesome-registry
:
Next, input the GCP credentials that you downloaded above, and enter your registry URL, the the form
[GCR_DOMAIN]/[GCP_PROJECT_ID]
. For most, the GCR domain will be gcr.io
(for more information, click here).
Then, click Save Settings.
Digital Ocean Container Registry
At the moment, linking a Digital Ocean Container Registry can only be done using the Porter CLI. To connect, run the following command:
porter connect docr
If you have not yet linked a DigitalOcean account, this command will open the browser that allows you to link your DigitalOcean account. Authorize the DigitalOcean account that you’d like to give access. You will then be redirected to the dashboard, at which point you can close out of the browser tab and go back to the CLI.
The CLI will then prompt you to provide a link to the container registry, in the form registry.digitalocean.com/[REGISTRY_NAME]
. This can be found by navigating to the “Container Registry” tab in DigitalOcean and copying the registry name:
Please provide the registry URL, in the form registry.digitalocean.com/[REGISTRY_NAME]. For example, registry.digitalocean.com/porter-test.
Registry URL: registry.digitalocean.com/porter-hi
That’s it! If you navigate to the “Launch” tab in the dashboard, you should see your existing DigitalOcean Container Registry images in the “Registry” section.
Docker Hub
In order to connect to a Docker Hub image repository, you must first generate a personal access token in the Docker Hub dashboard. Navigate to the “Security” tab in your account settings, and select “New Access Token”:
Name this access token something like “Porter,” and copy the access token to the clipboard.
Then type porter connect dockerhub
into the CLI. You will first be prompted to enter the path to the Docker Hub image repository that you would like to link. The image repository path can be found by going to the “Repositories” tab in Docker Hub and copying the username/organization and repository name. For example, for an organization called “porter1” and an image repository name called “porter”, the repo name would be “porter1/porter”:
Provide the Docker Hub image path, in the form of ${org_name}/${repo_name}. For example, porter1/porter.
Image path: porter1/porter
You should then enter your Docker Hub username and the access token you just copied.
That’s it! If you navigate to the “Launch” tab in the dashboard, you should see your existing Docker Hub image repository in the “Registry” section.
Multiple Docker Hub Repositories
This flow only links a single Docker Hub repository at a time. If you’d like to link multiple repositories, you must run porter connect dockerhub
for each repository.
Custom/Private Registries
Other Docker container registries are supported, as long as they implement the Registry HTTP API v2 specification. To link these, type porter connect registry
into the CLI. You will then be asked to input the URL of your image repository:
Provide the image registry URL (include the protocol). For example, https://my-custom-registry.getporter.dev.
Image registry URL: https://my-custom-registry.getporter.dev
If your registry is public, you can simply press enter when asked to input the username/password. Otherwise, enter the username/password that you would use for docker login
.
That’s it! If you navigate to the “Launch” tab in the dashboard, you should see your existing image repositories in the “Registry” section.