github.com/containerd/nerdctl@v1.7.7/docs/registry.md (about)

     1  # registry authentication
     2  
     3  nerdctl uses `${DOCKER_CONFIG}/config.json` for the authentication with image registries.
     4  
     5  `$DOCKER_CONFIG` defaults to `$HOME/.docker`.
     6  
     7  ## Using insecure registry
     8  
     9  If you face `http: server gave HTTP response to HTTPS client` and you cannot configure TLS for the registry, try `--insecure-registry` flag:
    10  
    11  e.g.,
    12  ```console
    13  $ nerdctl --insecure-registry run --rm 192.168.12.34:5000/foo
    14  ```
    15  
    16  ## Specifying certificates
    17  
    18  
    19  | :zap: Requirement | nerdctl >= 0.16 |
    20  |-------------------|-----------------|
    21  
    22  
    23  Create `~/.config/containerd/certs.d/<HOST:PORT>/hosts.toml` (or `/etc/containerd/certs.d/...` for rootful) to specify `ca` certificates.
    24  
    25  ```toml
    26  # An example of ~/.config/containerd/certs.d/192.168.12.34:5000/hosts.toml
    27  # (The path is "/etc/containerd/certs.d/192.168.12.34:5000/hosts.toml" for rootful)
    28  
    29  server = "https://192.168.12.34:5000"
    30  [host."https://192.168.12.34:5000"]
    31    ca = "/path/to/ca.crt"
    32  ```
    33  
    34  See https://github.com/containerd/containerd/blob/main/docs/hosts.md for the syntax of `hosts.toml` .
    35  
    36  Docker-style directories are also supported.
    37  The path is `~/.config/docker/certs.d` for rootless, `/etc/docker/certs.d` for rootful.
    38  
    39  ## Accessing 127.0.0.1 from rootless nerdctl
    40  
    41  Currently, rootless nerdctl cannot pull images from 127.0.0.1, because
    42  the pull operation occurs in RootlessKit's network namespace.
    43  
    44  See https://github.com/containerd/nerdctl/issues/86 for the discussion about workarounds.
    45  
    46  - - -
    47  
    48  # Using managed registry services
    49  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
    50  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
    51  
    52  
    53  - [Amazon Elastic Container Registry (ECR)](#amazon-elastic-container-registry-ecr)
    54    - [Logging in](#logging-in)
    55    - [Creating a repo](#creating-a-repo)
    56    - [Pushing an image](#pushing-an-image)
    57  - [Azure Container Registry (ACR)](#azure-container-registry-acr)
    58    - [Creating a registry](#creating-a-registry)
    59    - [Logging in](#logging-in-1)
    60    - [Creating a repo](#creating-a-repo-1)
    61    - [Pushing an image](#pushing-an-image-1)
    62  - [Docker Hub](#docker-hub)
    63    - [Logging in](#logging-in-2)
    64    - [Creating a repo](#creating-a-repo-2)
    65    - [Pushing an image](#pushing-an-image-2)
    66  - [GitHub Container Registry (GHCR)](#github-container-registry-ghcr)
    67    - [Logging in](#logging-in-3)
    68    - [Creating a repo](#creating-a-repo-3)
    69    - [Pushing an image](#pushing-an-image-3)
    70  - [GitLab Container Registry](#gitlab-container-registry)
    71    - [Logging in](#logging-in-4)
    72    - [Creating a repo](#creating-a-repo-4)
    73    - [Pushing an image](#pushing-an-image-4)
    74  - [Google Artifact Registry (pkg.dev)](#google-artifact-registry-pkgdev)
    75    - [Logging in](#logging-in-5)
    76    - [Creating a repo](#creating-a-repo-5)
    77    - [Pushing an image](#pushing-an-image-5)
    78  - [Google Container Registry (GCR) [DEPRECATED]](#google-container-registry-gcr-deprecated)
    79    - [Logging in](#logging-in-6)
    80    - [Creating a repo](#creating-a-repo-6)
    81    - [Pushing an image](#pushing-an-image-6)
    82  - [JFrog Artifactory (Cloud/On-Prem)](#jfrog-artifactory-cloudon-prem)
    83    - [Logging in](#logging-in-7)
    84    - [Creating a repo](#creating-a-repo-7)
    85    - [Pushing an image](#pushing-an-image-7)
    86  - [Quay.io](#quayio)
    87    - [Logging in](#logging-in-8)
    88    - [Creating a repo](#creating-a-repo-8)
    89    - [Pushing an image](#pushing-an-image-8)
    90  
    91  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    92  
    93  ## Amazon Elastic Container Registry (ECR)
    94  
    95  See also https://aws.amazon.com/ecr
    96  
    97  ### Logging in
    98  
    99  ```console
   100  $ aws ecr get-login-password --region <REGION> | nerdctl login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com
   101  Login Succeeded
   102  ```
   103  
   104  <details>
   105  <summary>Alternative method: <code>docker-credential-ecr-login</code></summary>
   106  
   107  This methods is more secure but needs an external dependency.
   108  
   109  <p>
   110  
   111  Install `docker-credential-ecr-login` from https://github.com/awslabs/amazon-ecr-credential-helper , and create the following files:
   112  
   113  `~/.docker/config.json`:
   114  ```json
   115  {
   116    "credHelpers": {
   117      "public.ecr.aws": "ecr-login",
   118      "<AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com": "ecr-login"
   119    }
   120  }
   121  ```
   122  
   123  `~/.aws/credentials`:
   124  ```
   125  [default]
   126  aws_access_key_id = ...
   127  aws_secret_access_key = ...
   128  ```
   129  
   130  > **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.
   131  > Same applies to the path of `~/.docker/config.json` and `~/.aws/credentials`, too.
   132  
   133  </p>
   134  </details>
   135  
   136  ### Creating a repo
   137  
   138  You have to create a repository via https://console.aws.amazon.com/ecr/home/ .
   139  
   140  ### Pushing an image
   141  
   142  ```console
   143  $ nerdctl tag hello-world <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO>
   144  $ nerdctl push <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO>
   145  ```
   146  
   147  The pushed image appears in the repository you manually created in the previous step.
   148  
   149  ## Azure Container Registry (ACR)
   150  See also https://azure.microsoft.com/en-us/services/container-registry/#overview
   151  
   152  ### Creating a registry
   153  
   154  You have to create a "Container registry" resource manually via [the Azure portal](https://portal.azure.com/).
   155  
   156  ### Logging in
   157  ```console
   158  $ nerdctl login -u <USERNAME> <REGISTRY>.azurecr.io
   159  Enter Password: ********[Enter]
   160  
   161  Login Succeeded
   162  ```
   163  
   164  The login credentials can be found as "Access keys" in [the Azure portal](https://portal.azure.com/).
   165  See also https://docs.microsoft.com/en-us/azure/container-registry/container-registry-authentication .
   166  
   167  > **Note**: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.
   168  
   169  ### Creating a repo
   170  You do not need to create a repo explicitly.
   171  
   172  ### Pushing an image
   173  
   174  ```console
   175  $ nerdctl tag hello-world <REGISTRY>.azurecr.io/hello-world
   176  $ nerdctl push <REGISTRY>.azurecr.io/hello-world
   177  ```
   178  
   179  The pushed image appears in [the Azure portal](https://portal.azure.com/).
   180  Private as default.
   181  
   182  ## Docker Hub
   183  See also https://hub.docker.com/
   184  
   185  ### Logging in
   186  ```console
   187  $ nerdctl login -u <USERNAME>
   188  Enter Password: ********[Enter]
   189  
   190  Login Succeeded
   191  ```
   192  
   193  > **Note**: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.
   194  
   195  ### Creating a repo
   196  You do not need to create a repo explicitly, for public images.
   197  
   198  To create a private repo, see https://hub.docker.com/repositories .
   199  
   200  ### Pushing an image
   201  
   202  ```console
   203  $ nerdctl tag hello-world <USERNAME>/hello-world
   204  $ nerdctl push <USERNAME>/hello-world
   205  ```
   206  
   207  The pushed image appears in https://hub.docker.com/repositories .
   208  **Public** by default.
   209  
   210  ## GitHub Container Registry (GHCR)
   211  See also https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry
   212  
   213  ### Logging in
   214  
   215  ```console
   216  $ nerdctl login ghcr.io -u <USERNAME>
   217  Enter Password: ********[Enter]
   218  
   219  Login Succeeded
   220  ```
   221  
   222  The `<USERNAME>` is your GitHub username but in lower characters.
   223  
   224  The "Password" here is a [GitHub Personal access token](https://github.com/settings/tokens), with `read:packages` and `write:packages` scopes.
   225  
   226  > **Note**: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.
   227  
   228  ### Creating a repo
   229  You do not need to create a repo explicitly.
   230  
   231  ### Pushing an image
   232  
   233  ```console
   234  $ nerdctl tag hello-world ghcr.io/<USERNAME>/hello-world
   235  $ nerdctl push ghcr.io/<USERNAME>/hello-world
   236  ```
   237  
   238  The pushed image appears in the "Packages" tab of your GitHub profile.
   239  Private as default.
   240  
   241  ## GitLab Container Registry
   242  See also https://docs.gitlab.com/ee/user/packages/container_registry/
   243  
   244  ### Logging in
   245  
   246  ```console
   247  $ nerdctl login registry.gitlab.com -u <USERNAME>
   248  Enter Password: ********[Enter]
   249  
   250  Login Succeeded
   251  ```
   252  
   253  The `<USERNAME>` is your GitLab username.
   254  
   255  The "Password" here is either a [GitLab Personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) or a [GitLab Deploy token](https://docs.gitlab.com/ee/user/project/deploy_tokens/index.html). Both options require minimum scope of `read_registry` for pull access and both `write_registry` and `read_registry` scopes for push access.
   256  
   257  > **Note**: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.
   258  
   259  ### Creating a repo
   260  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.
   261  
   262  ### Pushing an image
   263  
   264  In this example we have created a GitLab project named `myproject`.
   265  
   266  ```console
   267  $ nerdctl tag hello-world registry.gitlab.com/<USERNAME>/myproject/hello-world:latest
   268  $ nerdctl push registry.gitlab.com/<USERNAME>/myproject/hello-world:latest
   269  ```
   270  
   271  The pushed image appears under the "Packages & Registries -> Container Registry" tab of your project on GitLab.
   272  
   273  ## Google Artifact Registry (pkg.dev)
   274  See also https://cloud.google.com/artifact-registry/docs/docker/quickstart
   275  
   276  ### Logging in
   277  
   278  Create a [GCP Service Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating), grant
   279  `Artifact Registry Reader` and `Artifact Registry Writer` roles, and download the key as a JSON file.
   280  
   281  Then run the following command:
   282  
   283  ```console
   284  $ cat <GCP_SERVICE_ACCOUNT_KEY_JSON> | nerdctl login -u _json_key --password-stdin https://<REGION>-docker.pkg.dev
   285  WARNING! Your password will be stored unencrypted in /home/<USERNAME>/.docker/config.json.
   286  Configure a credential helper to remove this warning. See
   287  https://docs.docker.com/engine/reference/commandline/login/#credentials-store
   288  
   289  Login Succeeded
   290  ```
   291  
   292  See also https://cloud.google.com/artifact-registry/docs/docker/authentication
   293  
   294  
   295  <details>
   296  <summary>Alternative method: <code>docker-credential-gcloud</code> (<code>gcloud auth configure-docker</code>)</summary>
   297  
   298  This methods is more secure but needs an external dependency.
   299  
   300  <p>
   301  
   302  Run `gcloud auth configure-docker <REGION>-docker.pkg.dev`, e.g.,
   303  
   304  ```console
   305  $ gcloud auth configure-docker asia-northeast1-docker.pkg.dev
   306  Adding credentials for: asia-northeast1-docker.pkg.dev
   307  After update, the following will be written to your Docker config file located at [/home/<USERNAME>/.docker/config.json]:
   308   {
   309    "credHelpers": {
   310      "asia-northeast1-docker.pkg.dev": "gcloud"
   311    }
   312  }
   313  
   314  Do you want to continue (Y/n)?  y
   315  
   316  Docker configuration file updated.
   317  ```
   318  
   319  Google Cloud SDK (`gcloud`, `docker-credential-gcloud`) has to be installed, see https://cloud.google.com/sdk/docs/quickstart .
   320  
   321  > **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.
   322  
   323  </p>
   324  </details>
   325  
   326  ### Creating a repo
   327  
   328  You have to create a repository via https://console.cloud.google.com/artifacts .
   329  Choose "Docker" as the repository format.
   330  
   331  ### Pushing an image
   332  
   333  ```console
   334  $ nerdctl tag hello-world <REGION>-docker.pkg.dev/<GCP_PROJECT_ID>/<REPO>/hello-world
   335  $ nerdctl push <REGION>-docker.pkg.dev/<GCP_PROJECT_ID>/<REPO>/hello-world
   336  ```
   337  
   338  The pushed image appears in the repository you manually created in the previous step.
   339  
   340  ## Google Container Registry (GCR) [DEPRECATED]
   341  See also https://cloud.google.com/container-registry/docs/advanced-authentication
   342  
   343  ### Logging in
   344  
   345  Create a [GCP Service Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating), grant
   346  `Storage Object Admin` role, and download the key as a JSON file.
   347  
   348  Then run the following command:
   349  
   350  ```console
   351  $ cat <GCP_SERVICE_ACCOUNT_KEY_JSON> | nerdctl login -u _json_key --password-stdin https://asia.gcr.io
   352  WARNING! Your password will be stored unencrypted in /home/<USERNAME>/.docker/config.json.
   353  Configure a credential helper to remove this warning. See
   354  https://docs.docker.com/engine/reference/commandline/login/#credentials-store
   355  
   356  Login Succeeded
   357  ```
   358  
   359  See also https://cloud.google.com/container-registry/docs/advanced-authentication
   360  
   361  <details>
   362  <summary>Alternative method: <code>docker-credential-gcloud</code> (<code>gcloud auth configure-docker</code>)</summary>
   363  
   364  This methods is more secure but needs an external dependency.
   365  
   366  <p>
   367  
   368  ```console
   369  $ gcloud auth configure-docker
   370  Adding credentials for all GCR repositories.
   371  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.
   372  After update, the following will be written to your Docker config file located at [/home/<USERNAME>/.docker/config.json]:
   373   {
   374    "credHelpers": {
   375      "gcr.io": "gcloud",
   376      "us.gcr.io": "gcloud",
   377      "eu.gcr.io": "gcloud",
   378      "asia.gcr.io": "gcloud",
   379      "staging-k8s.gcr.io": "gcloud",
   380      "marketplace.gcr.io": "gcloud"
   381    }
   382  }
   383  
   384  Do you want to continue (Y/n)?  y
   385  
   386  Docker configuration file updated.
   387  ```
   388  
   389  Google Cloud SDK (`gcloud`, `docker-credential-gcloud`) has to be installed, see https://cloud.google.com/sdk/docs/quickstart .
   390  
   391  > **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.
   392  
   393  </p>
   394  </details>
   395  
   396  ### Creating a repo
   397  You do not need to create a repo explicitly.
   398  
   399  ### Pushing an image
   400  
   401  ```console
   402  $ nerdctl tag hello-world asia.gcr.io/<GCP_PROJECT_ID>/hello-world
   403  $ nerdctl push asia.gcr.io/<GCP_PROJECT_ID>/hello-world
   404  ```
   405  
   406  The pushed image appears in https://console.cloud.google.com/gcr/ .
   407  Private by default.
   408  
   409  ## JFrog Artifactory (Cloud/On-Prem)
   410  See also https://www.jfrog.com/confluence/display/JFROG/Getting+Started+with+Artifactory+as+a+Docker+Registry
   411  
   412  ### Logging in
   413  ```console
   414  $ nerdctl login <SERVER_NAME>.jfrog.io -u <USERNAME>
   415  Enter Password: ********[Enter]
   416  
   417  Login Succeeded
   418  ```
   419  
   420  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.
   421  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)
   422  
   423  > **Note**: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.
   424  
   425  ### Creating a repo
   426  1. Add local Docker repository
   427     1. Add a new Local Repository with the Docker package type via `https://<server-name>.jfrog.io/ui/admin/repositories/local/new`.
   428  2. Add virtual Docker repository
   429     1. Add a new virtual repository with the Docker package type via `https://<server-name>.jfrog.io/ui/admin/repositories/virtual/new`.
   430     2. Add the local docker repository you created in Steps 1 (move it from Available Repositories to Selected Repositories using the arrow buttons).
   431     3. Set local repository as a default local deployment repository.
   432  
   433  ### Pushing an image
   434  ```console
   435  $ nerdctl tag hello-world <SERVER_NAME>.jfrog.io/<VIRTUAL_REPO_NAME>/hello-world
   436  $ nerdctl push <SERVER_NAME>.jfrog.io/<VIRTUAL_REPO_NAME>/hello-world
   437  ```
   438  
   439  The `SERVER_NAME` is the first part of the URL given to you for your environment: `https://<SERVER_NAME>.jfrog.io`
   440  
   441  The `VIRTUAL_REPO_NAME` is the name “docker” that you assigned to your virtual repository in 2.i .
   442  
   443  The pushed image appears in `https://<SERVER_NAME>.jfrog.io/ui/repos/tree/General/<VIRTUAL_REPO_NAME>` .
   444  Private by default.
   445  
   446  ## Quay.io
   447  See also https://docs.quay.io/solution/getting-started.html
   448  
   449  ### Logging in
   450  
   451  ```console
   452  $ nerdctl login quay.io -u <USERNAME>
   453  Enter Password: ********[Enter]
   454  
   455  Login Succeeded
   456  ```
   457  
   458  > **Note**: nerdctl prior to v0.16.1 had a bug that required pressing the Enter key twice.
   459  
   460  ### Creating a repo
   461  You do not need to create a repo explicitly.
   462  
   463  ### Pushing an image
   464  
   465  ```console
   466  $ nerdctl tag hello-world quay.io/<USERNAME>/hello-world
   467  $ nerdctl push quay.io/<USERNAME>/hello-world
   468  ```
   469  
   470  The pushed image appears in https://quay.io/repository/ .
   471  Private as default.