Skip to content

Latest commit

 

History

History
471 lines (327 loc) · 15.3 KB

registry.md

File metadata and controls

471 lines (327 loc) · 15.3 KB
Raw

registry authentication

nerdctl uses ${DOCKER_CONFIG}/config.json for the authentication with image registries.

$DOCKER_CONFIG defaults to $HOME/.docker.

Using insecure registry

If you face http: server gave HTTP response to HTTPS client and you cannot configure TLS for the registry, try --insecure-registry flag:

e.g.,

$ nerdctl --insecure-registry run --rm 192.168.12.34:5000/foo

Specifying certificates

⚡ Requirement nerdctl >= 0.16

Create ~/.config/containerd/certs.d/<HOST:PORT>/hosts.toml (or /etc/containerd/certs.d/... for rootful) to specify ca certificates.

# An example of ~/.config/containerd/certs.d/192.168.12.34:5000/hosts.toml
# (The path is "/etc/containerd/certs.d/192.168.12.34:5000/hosts.toml" for rootful)

server = "https://192.168.12.34:5000"
[host."https://192.168.12.34:5000"]
  ca = "/path/to/ca.crt"

See https://github.com/containerd/containerd/blob/main/docs/hosts.md for the syntax of hosts.toml .

Docker-style directories are also supported. The path is ~/.config/docker/certs.d for rootless, /etc/docker/certs.d for rootful.

Accessing 127.0.0.1 from rootless nerdctl

Currently, rootless nerdctl cannot pull images from 127.0.0.1, because the pull operation occurs in RootlessKit's network namespace.

See #86 for the discussion about workarounds.

Using managed registry services

Amazon Elastic Container Registry (ECR)

See also https://aws.amazon.com/ecr

Logging in

$ aws ecr get-login-password --region <REGION> | nerdctl login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com
Login Succeeded
Alternative method: docker-credential-ecr-login

This methods is more secure but needs an external dependency.

Install docker-credential-ecr-login from https://github.com/awslabs/amazon-ecr-credential-helper , and create the following files:

~/.docker/config.json:

{
  "credHelpers": {
    "public.ecr.aws": "ecr-login",
    "<AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com": "ecr-login"
  }
}

~/.aws/credentials:

[default]
aws_access_key_id = ...
aws_secret_access_key = ...

Note: If you are running nerdctl inside a VM (including Lima, Colima, Rancher Desktop, and WSL2), docker-credential-ecr-login has to be installed inside the guest, not the host. Same applies to the path of ~/.docker/config.json and ~/.aws/credentials, too.

Creating a repo

You have to create a repository via https://console.aws.amazon.com/ecr/home/ .

Pushing an image

$ nerdctl tag hello-world <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO>
$ nerdctl push <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO>

The pushed image appears in the repository you manually created in the previous step.

Azure Container Registry (ACR)

See also https://azure.microsoft.com/en-us/services/container-registry/#overview

Creating a registry

You have to create a "Container registry" resource manually via the Azure portal.

Logging in

$ nerdctl login -u <USERNAME> <REGISTRY>.azurecr.io
Enter Password: ********[Enter]

Login Succeeded

The login credentials can be found as "Access keys" in the Azure portal. See also https://docs.microsoft.com/en-us/azure/container-registry/container-registry-authentication .

Note: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.

Creating a repo

You do not need to create a repo explicitly.

Pushing an image

$ nerdctl tag hello-world <REGISTRY>.azurecr.io/hello-world
$ nerdctl push <REGISTRY>.azurecr.io/hello-world

The pushed image appears in the Azure portal. Private as default.

Docker Hub

See also https://hub.docker.com/

Logging in

$ nerdctl login -u <USERNAME>
Enter Password: ********[Enter]

Login Succeeded

Note: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.

Creating a repo

You do not need to create a repo explicitly, for public images.

To create a private repo, see https://hub.docker.com/repositories .

Pushing an image

$ nerdctl tag hello-world <USERNAME>/hello-world
$ nerdctl push <USERNAME>/hello-world

The pushed image appears in https://hub.docker.com/repositories . Public by default.

GitHub Container Registry (GHCR)

See also https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry

Logging in

$ nerdctl login ghcr.io -u <USERNAME>
Enter Password: ********[Enter]

Login Succeeded

The <USERNAME> is your GitHub username but in lower characters.

The "Password" here is a GitHub Personal access token, with read:packages and write:packages scopes.

Note: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.

Creating a repo

You do not need to create a repo explicitly.

Pushing an image

$ nerdctl tag hello-world ghcr.io/<USERNAME>/hello-world
$ nerdctl push ghcr.io/<USERNAME>/hello-world

The pushed image appears in the "Packages" tab of your GitHub profile. Private as default.

GitLab Container Registry

See also https://docs.gitlab.com/ee/user/packages/container_registry/

Logging in

$ nerdctl login registry.gitlab.com -u <USERNAME>
Enter Password: ********[Enter]

Login Succeeded

The <USERNAME> is your GitLab username.

The "Password" here is either a GitLab Personal access token or a GitLab Deploy token. Both options require minimum scope of read_registry for pull access and both write_registry and read_registry scopes for push access.

Note: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.

Creating a repo

Container registries in GitLab are created at the project level. A project in GitLab must exist first before you begin working with its container registry.

Pushing an image

In this example we have created a GitLab project named myproject.

$ nerdctl tag hello-world registry.gitlab.com/<USERNAME>/myproject/hello-world:latest
$ nerdctl push registry.gitlab.com/<USERNAME>/myproject/hello-world:latest

The pushed image appears under the "Packages & Registries -> Container Registry" tab of your project on GitLab.

Google Artifact Registry (pkg.dev)

See also https://cloud.google.com/artifact-registry/docs/docker/quickstart

Logging in

Create a GCP Service Account, grant Artifact Registry Reader and Artifact Registry Writer roles, and download the key as a JSON file.

Then run the following command:

$ cat <GCP_SERVICE_ACCOUNT_KEY_JSON> | nerdctl login -u _json_key --password-stdin https://<REGION>-docker.pkg.dev
WARNING! Your password will be stored unencrypted in /home/<USERNAME>/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

See also https://cloud.google.com/artifact-registry/docs/docker/authentication

Alternative method: docker-credential-gcloud (gcloud auth configure-docker)

This methods is more secure but needs an external dependency.

Run gcloud auth configure-docker <REGION>-docker.pkg.dev, e.g.,

$ gcloud auth configure-docker asia-northeast1-docker.pkg.dev
Adding credentials for: asia-northeast1-docker.pkg.dev
After update, the following will be written to your Docker config file located at [/home/<USERNAME>/.docker/config.json]:
 {
  "credHelpers": {
    "asia-northeast1-docker.pkg.dev": "gcloud"
  }
}

Do you want to continue (Y/n)?  y

Docker configuration file updated.

Google Cloud SDK (gcloud, docker-credential-gcloud) has to be installed, see https://cloud.google.com/sdk/docs/quickstart .

Note: If you are running nerdctl inside a VM (including Lima, Colima, Rancher Desktop, and WSL2), the Google Cloud SDK has to be installed inside the guest, not the host.

Creating a repo

You have to create a repository via https://console.cloud.google.com/artifacts . Choose "Docker" as the repository format.

Pushing an image

$ nerdctl tag hello-world <REGION>-docker.pkg.dev/<GCP_PROJECT_ID>/<REPO>/hello-world
$ nerdctl push <REGION>-docker.pkg.dev/<GCP_PROJECT_ID>/<REPO>/hello-world

The pushed image appears in the repository you manually created in the previous step.

Google Container Registry (GCR) [DEPRECATED]

See also https://cloud.google.com/container-registry/docs/advanced-authentication

Logging in

Create a GCP Service Account, grant Storage Object Admin role, and download the key as a JSON file.

Then run the following command:

$ cat <GCP_SERVICE_ACCOUNT_KEY_JSON> | nerdctl login -u _json_key --password-stdin https://asia.gcr.io
WARNING! Your password will be stored unencrypted in /home/<USERNAME>/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

See also https://cloud.google.com/container-registry/docs/advanced-authentication

Alternative method: docker-credential-gcloud (gcloud auth configure-docker)

This methods is more secure but needs an external dependency.

$ gcloud auth configure-docker
Adding credentials for all GCR repositories.
WARNING: A long list of credential helpers may cause delays running 'docker build'. We recommend passing the registry name to configure only the registry you are using.
After update, the following will be written to your Docker config file located at [/home/<USERNAME>/.docker/config.json]:
 {
  "credHelpers": {
    "gcr.io": "gcloud",
    "us.gcr.io": "gcloud",
    "eu.gcr.io": "gcloud",
    "asia.gcr.io": "gcloud",
    "staging-k8s.gcr.io": "gcloud",
    "marketplace.gcr.io": "gcloud"
  }
}

Do you want to continue (Y/n)?  y

Docker configuration file updated.

Google Cloud SDK (gcloud, docker-credential-gcloud) has to be installed, see https://cloud.google.com/sdk/docs/quickstart .

Note: If you are running nerdctl inside a VM (including Lima, Colima, Rancher Desktop, and WSL2), the Google Cloud SDK has to be installed inside the guest, not the host.

Creating a repo

You do not need to create a repo explicitly.

Pushing an image

$ nerdctl tag hello-world asia.gcr.io/<GCP_PROJECT_ID>/hello-world
$ nerdctl push asia.gcr.io/<GCP_PROJECT_ID>/hello-world

The pushed image appears in https://console.cloud.google.com/gcr/ . Private by default.

JFrog Artifactory (Cloud/On-Prem)

See also https://www.jfrog.com/confluence/display/JFROG/Getting+Started+with+Artifactory+as+a+Docker+Registry

Logging in

$ nerdctl login <SERVER_NAME>.jfrog.io -u <USERNAME>
Enter Password: ********[Enter]

Login Succeeded

Login using the default username: admin, and password: password for the on-prem installation, or the credentials provided to you by email for the cloud installation. JFrog Platform is integrated with OAuth allowing you to delegate authentication requests to external providers (the provider types supported are Google, OpenID Connect, GitHub Enterprise, and Cloud Foundry UAA)

Note: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.

Creating a repo

  1. Add local Docker repository
    1. Add a new Local Repository with the Docker package type via https://<server-name>.jfrog.io/ui/admin/repositories/local/new.
  2. Add virtual Docker repository
    1. Add a new virtual repository with the Docker package type via https://<server-name>.jfrog.io/ui/admin/repositories/virtual/new.
    2. Add the local docker repository you created in Steps 1 (move it from Available Repositories to Selected Repositories using the arrow buttons).
    3. Set local repository as a default local deployment repository.

Pushing an image

$ nerdctl tag hello-world <SERVER_NAME>.jfrog.io/<VIRTUAL_REPO_NAME>/hello-world
$ nerdctl push <SERVER_NAME>.jfrog.io/<VIRTUAL_REPO_NAME>/hello-world

The SERVER_NAME is the first part of the URL given to you for your environment: https://<SERVER_NAME>.jfrog.io

The VIRTUAL_REPO_NAME is the name “docker” that you assigned to your virtual repository in 2.i .

The pushed image appears in https://<SERVER_NAME>.jfrog.io/ui/repos/tree/General/<VIRTUAL_REPO_NAME> . Private by default.

Quay.io

See also https://docs.quay.io/solution/getting-started.html

Logging in

$ nerdctl login quay.io -u <USERNAME>
Enter Password: ********[Enter]

Login Succeeded

Note: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.

Creating a repo

You do not need to create a repo explicitly.

Pushing an image

$ nerdctl tag hello-world quay.io/<USERNAME>/hello-world
$ nerdctl push quay.io/<USERNAME>/hello-world

The pushed image appears in https://quay.io/repository/ . Private as default.