Carvel Logo



imgpkg has multiple ways to provide authentication details to registries.

The order at which imgpkg chooses which authentication details to use is the following:

  1. Via Environment Variables
  2. Via IaaS
  3. Via Command Flags
  4. Via Docker Config

Via Environment Variables

As of v0.7.0+, imgpkg can also use following environment variables:

  • IMGPKG_REGISTRY_HOSTNAME to specify registry hostname (e.g.,,,
    • As of v0.18.0+ IMGPKG_REGISTRY_HOSTNAME also supports providing glob wildcards. for e.g. *.* will match
      • Note: if there is overlap between 2 HOSTNAMES, one using globbing and the other not, the HOSTNAME not using globbing will be applied. e.g. IMGPKG_REGISTRY_HOSTNAME_0=* vs for the image will result in auth details from IMGPKG_REGISTRY_HOSTNAME_1 being used.
    • As of v0.18.0+ IMGPKG_REGISTRY_HOSTNAME also supports providing the fully qualified repository. for e.g.
  • IMGPKG_REGISTRY_USERNAME to specify registry username
  • IMGPKG_REGISTRY_PASSWORD to specify registry password
  • IMGPKG_REGISTRY_IDENTITY_TOKEN to authenticate the user and get an access token for the registry via an oauth2 refresh token grant type.
  • IMGPKG_REGISTRY_REGISTRY_TOKEN to specify the access token to be used in the Authorization Header as a Bearer Token.

Since you may need to provide multiple registry credentials, the environment variables above may be specified multiple times with a suffix of 1+ alphanumeric characters,

e.g. If you had 2 registries you wish to provide authentication credentials for, you would require 2 sets of env variables.

For Registry #1:


For Registry #2:


When imgpkg interacts with hostname.for.registry.1, it will use the env variables with the suffix _0. And when interacting with hostname.for.registry.2, it will use the env variables with the suffix _1

Note: Credentials provided via an env variable for a specific registry will take precedence over Command Flags.

Via IaaS

By default, imgpkg will NOT attempt to authenticate itself via the underlying IaaS:

To activate this behavior you can set the environment variable IMGPKG_ACTIVE_KEYCHAINS with the keychains to the IaaS that you are currently using.

Note: To mimic the old behavior of imgpkg set the environment variable as follows export IMGPKG_ACTIVE_KEYCHAINS=gke,aks,ecr

Below is a list of IaaS providers that imgpkg can authenticate with:

  • GCP

    To activate it use export IMGPKG_ACTIVE_KEYCHAINS=gke

  • AWS

    To activate it use export IMGPKG_ACTIVE_KEYCHAINS=ecr For more information check the helper

  • Azure

    To activate it use export IMGPKG_ACTIVE_KEYCHAINS=aks For more information check this library

  • Github

    To activate use export IMGPKG_ACTIVE_KEYCHAINS=github Requires the environment variable GITHUB_TOKEN to be set to connect to

Deprecation: The environment variable IMGPKG_ENABLE_IAAS_AUTH can be used only to activate all the keychains. This behavior will be removed in a future version.

Via Command Flags

You can explicitly specify credentials via command flags or associated environment variables. See imgpkg push -h for further details.

  • --registry-username (or $IMGPKG_USERNAME)
  • --registry-password (or $IMGPKG_PASSWORD)
  • --registry-token (or $IMGPKG_TOKEN): to specify the access token to be used in the Authorization Header as a Bearer Token.
  • --registry-anon (or $IMGPKG_ANON=true): used for anonymous access (commonly for pulling)

Via Docker config

Even though imgpkg commands use registry APIs directly, by default it uses credentials stored in ~/.docker/config.json which are typically generated via a docker login command.

Example generated ~/.docker/config.json:

  "auths": {
    "": {
      "auth": "dXNlcjpwYXNzd29yZA=="
  "HttpHeaders": {
    "User-Agent": "Docker-Client/18.09.6 (darwin)"

where dXNlcjpwYXNzd29yZA== is base64("username:password").

  • Create a service account with “Storage Admin” permissions for push access
  • Download a JSON service account key and place it somewhere on filesystem (e.g. /tmp/key)
  • Run cat /tmp/key | docker login -u _json_key --password-stdin to authenticate


  • Create an ECR repository
  • Create an IAM user with an ECR policy that allows read/write
  • Run aws configure and specify access key ID, secret access key and region
  • Run eval $(aws ecr get-login --no-include-email) to authenticate

Example ECR policy from Amazon ECR:

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Action": [
      "Resource": "*"


You may have to provide --registry-ca-cert-path flag with a path to a CA certificate file for Harbor Registry API.

(Help improve our docs: edit this page on GitHub)