For the complete documentation index, see llms.txt. This page is also available as Markdown.

Build and Push to ACR

Use a CI pipeline to build and push an image to ACR.

What you will learn from this topic

  • How to add a Build and Push to ACR step to a Harness CI pipeline

  • How to configure step settings including repository, tags, and caching options

  • How to set plugin runtime flags for Kaniko

Before you begin

  • ACR access: You need access to ACR and an ACR repo where you can upload your image.

  • Azure Cloud Provider connector: You need an Azure Cloud Provider connector.

  • Harness CI pipeline: You need a Harness CI pipeline with a Build stage that uses a Linux platform on a Kubernetes cluster build infrastructure.

This topic explains how to configure the Build and Push to ACR step in a Harness CI pipeline. This step is used to build and push to Azure Container Registry (ACR).

Kubernetes cluster build infrastructure is required

The Build and Push to ACR step is supported for Linux platforms on Kubernetes cluster build infrastructures only. For other platforms and build infrastructures, use the Build and Push to Docker Registry step to push to ACR.

Root access is required

With Kubernetes cluster build infrastructures, all Build and Push steps use Chainguard's maintained Kaniko fork. Kaniko can run as non-root in many cases. Root access is only required when your Dockerfile performs privileged operations (e.g., installing system packages, modifying root-owned directories).

If your build runs as non-root (runAsNonRoot: true), and you want to run the Build and Push step as root, you can set Run as User to 0 on the Build and Push step to use the root user for that individual step only.

If your security policy does not allow running as root, go to Build and push with non-root users.

KANIKO ROOT REQUIREMENTS

With Kubernetes infrastructure, Build and Push steps use Kaniko which requires root user access. Set runAsUser: 0 on the step only when your Dockerfile performs privileged operations like installing system packages or modifying system files. For enhanced security, keep your stage running as non-root and elevate only the Build and Push step when necessary.

Add a build and push to ACR step

In your pipeline's Build stage, add a Build and Push to ACR step and configure the settings accordingly.

Here is a YAML example of a Build and Push to ACR step.

When you run a pipeline, you can observe the step logs on the build details page. If the Build and Push to ACR step succeeds, you can find the uploaded image on ACR.

Build and push to ACR step settings

The Build and Push to ACR step has the following settings. Some settings are located under Optional Configuration in the visual pipeline editor.

Name

Enter a name summarizing the step's purpose. Harness automatically assigns an Id (Entity Identifier) based on the Name. You can change the Id.

Azure Connector

The Harness Azure Cloud connector to use to connect to your ACR. This step supports Azure Cloud connectors that use access key authentication. This step does not support Azure Cloud connectors that inherit delegate credentials.

Go to Add a Microsoft Azure Cloud Provider connector for Azure connectors, including details about required permissions.

Repository

The URL for the target ACR repository where you want to push your artifact. You must use this format: CONTAINER-REGISTRY-NAME.azurecr.io/IMAGE-NAME.

Subscription Id

Name or ID of an ACR subscription. This field is required for artifacts to appear in the build's Artifacts tab.

Go to the Microsoft documentation about How to manage Azure subscriptions with the Azure CLI.

Tags

Add Docker build tags. This is equivalent to the -t flag.

Add each tag separately.

When you push an image to a repo, you tag the image so you can identify it later. For example, in one pipeline stage, you push the image, and, in a later stage, you use the image name and tag to pull it and run integration tests on it.

Harness expressions are a useful way to define tags. For example, you can use the expression <+pipeline.sequenceId> as a tag. This expression represents the incremental build identifier, such as 9. By using a variable expression, rather than a fixed value, you do not have to use the same image name every time.

For example, if you use <+pipeline.sequenceId> as a tag, after the pipeline runs, you can see the Build Id in the output.

And you can see where the Build Id is used to tag your image:

Later in the pipeline, you can use the same expression to pull the tagged image, such as myrepo/myimage:<+pipeline.sequenceId>.

Base Image Connector

Select an authenticated connector to download base images from a Docker-compliant registry. If you do not specify a Base Image Connector, the step downloads base images without authentication. Specifying a Base Image Connector is recommended because unauthenticated downloads generally have a lower rate limit than authenticated downloads.

When you use a base image connector, you can't push to or pull from multiple Docker registries that share the same URL prefix (for example, https://index.docker.io). This is because the second registry's credentials overwrite the first in the Docker config file.

Registries with completely different URLs, such as two separate JFrog instances, aren't affected.

This limitation also doesn't apply to the Build and Push to ACR, GAR, and ECR steps when they run on Kubernetes.

Optimize

Select this option to enable --snapshotMode=redo. This setting causes file metadata to be considered when creating snapshots, and it can reduce the time it takes to create snapshots. Go to the Kaniko documentation for the snapshotMode flag.

Go to Environment variables for setting other kaniko runtime flags.

Dockerfile

The name of the Dockerfile. If you do not provide a name, Harness assumes that the Dockerfile is in the root folder of the codebase.

Context

Enter a path to a directory containing files that make up the build's context. When the pipeline runs, the build process can refer to any files found in the context. For example, a Dockerfile can use a COPY instruction to reference a file in the context.

Labels

Specify Docker object labels to add metadata to the Docker image.

Build Arguments

The Docker build-time variables. This is equivalent to the --build-arg flag.

Target

The Docker target build stage, equivalent to the --target flag, such as build-env.

Docker layer caching and Remote cache image

There are two ways in which you can leverage Docker Layer Caching: Enable Docker layer caching ('caching' property) or Remote cache image ('remoteCacheRepo' property). Go to Enable Docker layer caching for your build to configure this setting.

Environment Variables (plugin runtime flags)

Build and Push steps use plugins to complete build and push operations. With Kubernetes cluster build infrastructures, these steps use Chainguard's maintained Kaniko fork. With other build infrastructures, these steps use drone-docker.

These plugins have a number of additional runtime flags that you might need for certain use cases. Go to the Kaniko plugin documentation and the drone-docker plugin documentation for the flags.

In Environment Variables for your step, add the environment variable PLUGIN_BUILDX_OPTIONS to pass any supported options to the buildx command used by the build and push steps.

How you configure plugin runtime flags depends on your build infrastructure.

Set plugin runtime flags with Kubernetes cluster build infrastructure

When using the built-in Build and Push steps with a Kubernetes cluster build infrastructure, you can use the Environment Variables setting to set kaniko plugin runtime flags.

In Environment Variables, you must input a Name and Value for each variable. Format the name as PLUGIN_FLAG_NAME.

For example, to set --skip-tls-verify, add an environment variable named PLUGIN_SKIP_TLS_VERIFY and set the variable value to true.

To build without pushing, use the no-push kaniko flag.

STAGE VARIABLES

Previously, you could set some kaniko runtime flags as stage variables. If you had done this and you are using Kubernetes cluster build infrastructure, then Harness recommends moving these kaniko plugin stage variables to the Environment Variables in your Build and Push step. Do not change non-kaniko plugin variables, such as PLUGIN_USER_ROLE_ARN.

For other types of environment variables (that are not Build and Push plugin runtime flags), stage variables are still inherently available to steps as environment variables. However, where you declare environment variables depends on their usage and purpose in your build. You might need to set them in your Dockerfile, build args, or otherwise.

However some flags still require using a stage variable:

  • ignore-path: Set this flag to ignore a comma separated list of file paths when taking an image snapshot. Required when ignoring multiple paths.

Format these stage variables as PLUGIN_FLAG_NAME.

Set plugin runtime flags with other build infrastructures

With Harness Cloud, self-managed VM, or local runner build infrastructures, you can set some drone-docker plugin runtime flags as stage variable.

Currently, Harness supports the following drone-docker flags:

  • auto_tag: Enable auto-generated build tags.

  • auto_tag_suffix: Auto-generated build tag suffix.

  • custom_labels: Additional arbitrary key-value labels.

  • artifact_file: Harness uses this to show links to uploaded artifacts on the Artifacts tab.

  • dry_run: Disables pushing to the registry. Used to build without pushing.

  • custom_dns: Provide your custom CNS address.

To set these flags in your Build and Push steps, add stage variables formatted as PLUGIN_FLAG_NAME.

For example, to set custom_dns, add a stage variable named PLUGIN_CUSTOM_DNS and set the variable value to your custom DNS address.

Mounting Docker Secrets

Harness now allows mounting Docker build secrets securely in 'Build and Push' steps. This feature enables you to pass sensitive data such as credentials or configuration files during Docker builds, either as environment variables or file-based secrets. It ensures secure handling of secrets, reducing the risk of exposing sensitive information.

USE CACHING AND KUBERNETES REQUIREMENTS

  • This feature is currently configurable only through YAML.

  • On non-Kubernetes build infrastructures (Harness Cloud, self-managed VM, local runner), you must set caching: true on the step. With caching: false (the default), the step uses the plain docker plugin, which silently drops envDockerSecrets and fileDockerSecrets without emitting any --secret flag. Setting caching: true activates the buildx plugin, which supports secret mounts.

  • In Kubernetes, unlike other build infrastructures (e.g., Harness Cloud), "Build and Push" steps default to Kaniko rather than Buildx. To enable this feature in Kubernetes, you must enable the feature flag CI_USE_BUILDX_ON_K8. Additionally, note that Kubernetes build infrastructure using Buildx requires privileged access.

Using Local Tar Output

In scenarios where pushing a Docker image to a registry is not feasible, you can generate a local tarball of the built image instead. This approach is particularly useful for situations like local testing or when registry access is unavailable during the build process.

Once the tarball is generated, you can use a Security Testing Orchestration (STO) step, such as Aqua Trivy, to scan the image for vulnerabilities. This workflow ensures that images are built and scanned effectively, even without access to a remote registry.

Here is a sample partial pipeline that demonstrates how build the image, generate the tarball, and push it to the registry:

The PLUGIN_NO_PUSH: "true" environment variable prevents the image from being pushed to the registry.Here is a sample partial pipeline that demonstrates how build the image, generate the tarball, but skip pushing it to the registry:

  • The local tar output feature is available only when using Kaniko as the build tool, which is commonly used in Kubernetes environments.

  • While the above examples show a push to a Docker registry, you can easily repurpose it for other registries by updating the step type, connector, and other relevant fields.

Run as User

Specify the user ID to use to run all processes in the pod if running in containers. Go to Set the security context for a pod in the Kubernetes docs.

Because the Build and Push to ACR step requires root access, use the Run as User setting if your build runs as non-root (runAsNonRoot: true) and you can run the Build and Push to ACR step as root. To do this, set Run as User to 0 on the Build and Push to ACR step to use the root user for this individual step only.

If your security policy does not allow running as root, go to Build and push with non-root users.

Set Container Resources

Set maximum resource limits for the resources used by the container at runtime:

  • Limit Memory: The maximum memory that the container can use. You can express memory as a plain integer or as a fixed-point number using the suffixes G or M. You can also use the power-of-two equivalents Gi and Mi. The default is 500Mi.

  • Limit CPU: The maximum number of cores that the container can use. CPU limits are measured in CPU units. Fractional requests are allowed; for example, you can specify one hundred millicpu as 0.1 or 100m. The default is 400m. Go to Resource units in Kubernetes in the Kubernetes docs.

Timeout

Set the timeout limit for the step. Once the timeout limit is reached, the step fails and pipeline execution continues. To set skip conditions or failure handling for steps, go to:

Conditions, looping, and failure strategies

You can find the following settings on the Advanced tab in the step settings pane:

You can securely perform SSH-based operations in your Docker builds, such as cloning private Git repositories, by mounting an SSH key into the build using Docker BuildKit's --ssh feature. The SSH key is mounted only during the build process and is never baked into the final image.

Below is a full working Harness CI pipeline example:

Key points:

Keep the following in mind when using SSH-based operations in a Docker build:

  • --mount=type=ssh,id=sshkey in the Dockerfile matches --ssh=sshkey=/harness/id_ed25519 in PLUGIN_BUILDX_OPTIONS.

  • The SSH key comes from the Harness Secrets Manager, as shown in the SSH Key Prep step above where a file secret is used to create /harness/id_ed25519. It is mounted only during the build.

  • In this example, cloneCodebase is set to false because the Dockerfile is created in the pipeline itself. In your own pipelines, set this to true if your Dockerfile (or other build context files) is stored in a repository that Harness needs to clone before the build.

Troubleshooting

What drives the Build and Push steps? What is kaniko?
Does a kaniko build use images cached locally on the node? Can I enable caching for kaniko?
Can I run Build and Push steps as root if my build infrastructure runs as non-root?
Can I set kaniko and drone-docker runtime flags, such as skip-tls-verify or custom-dns?
Can I build without pushing?
Is remote caching supported in Build and Push steps?
How do I fix the kaniko container runtime error: kaniko should only be run inside of a container?
Why does the parallel execution of Build and Push steps fail when using Buildx on Kubernetes?

Next steps

Last updated

Was this helpful?