Carvel Logo


Via Docker config

Even though kbld commands use registry APIs directly, by default it uses credentials stored in ~/.docker/config.json which are typically generated via 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").

Via Environment Variables

As of v0.23.0+, kbld can also use following environment variables:

  • KBLD_REGISTRY_HOSTNAME to specify registry hostname (e.g.,
  • KBLD_REGISTRY_USERNAME to specify registry username
  • KBLD_REGISTRY_PASSWORD to specify registry password

Since you may need to provide multiple registry credentials, above environment variables multiple times with a suffix like so KBLD_REGISTRY_HOSTNAME_0 (suffix can be 1+ alphanumeric characters). Use same suffix for hostname, username and password.

Currently credentials provided via environment variables do not apply when building images with Docker. Continue using docker login to authenticate Docker daemon.

  • Create service account with “Storage Admin” for push access
  • Download 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

Amazon Web Services Elastic Container Registry (AWS ECR)

  • Create an ECR repository
    (see Amazon ECR User Guide: Getting started)

  • Create an IAM user with an ECR policy that allows to read/write
    (see Amazon ECR User Guide: Private repository policies)

      "Version": "2012-10-17",
      "Statement": [
              "Effect": "Allow",
              "Action": [
              "Resource": "*"
  • To authenticate from the command line, use the AWS CLI to generate a docker authentication token.
    (see Amazon ECR User Guide: Private registry authentication)

    $ aws ecr get-login-password --region us-east-1 \
        | docker login \
            --username AWS \
  • To authenticate from a GitHub Action, setup Carvel, AWS authentication, and ECR login.
    (see Amazon ECR “Login” Action for GitHub Actions)

     - name: carvel-setup-action
       uses: carvel-dev/setup-action@v1.3.0
     - name: Configure AWS credentials
       uses: aws-actions/configure-aws-credentials@v1
         aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
         aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         aws-region: us-east-1
     - name: Login to Amazon ECR
       id: login-ecr
       uses: aws-actions/amazon-ecr-login@v1


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)