Container jobs in YAML pipelines

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

This article explains container jobs in Azure Pipelines. Containers are lightweight abstractions from the host operating system that provide all the necessary elements to run a job in a specific environment.

By default, Azure Pipelines jobs run directly on agents installed on host machines. Hosted agent jobs are convenient, require little initial setup or infrastructure maintenance, and are well-suited for basic projects. For more control over task context, you can define and run pipeline jobs in containers to get the exact versions of operating systems, tools, and dependencies you want.

For a container job, the agent first fetches and starts the container, and then runs each step of the job inside the container. If you need finer-grained control of individual build steps, you can use step targets to choose a container or host for each step.

Requirements for container jobs

• A YAML-based pipeline. Classic pipelines don't support container jobs.
• A Windows or Ubuntu hosted agent. MacOS agents don't support containers. To use non-Ubuntu Linux agents, see Nonglibc-based containers.
• Docker installed on the agent, with permission to access the Docker daemon.
• Agent running directly on the host, not already inside a container. Nested containers aren't supported.

Single job

The following example defines a Windows or Linux single-job container.

pool:
  vmImage: 'ubuntu-latest'

container: ubuntu:18.04

steps:
- script: printenv

pool:
  vmImage: 'windows-2019'

container: mcr.microsoft.com/windows/servercore:ltsc2019

steps:
- script: set

Multiple jobs

You can use containers to run the same step in multiple jobs. The following example runs the same step in multiple versions of Ubuntu Linux. You don't have to use the jobs keyword, because only a single job is defined.

pool:
  vmImage: 'ubuntu-latest'

strategy:
  matrix:
    ubuntu16:
      containerImage: ubuntu:16.04
    ubuntu18:
      containerImage: ubuntu:18.04
    ubuntu20:
      containerImage: ubuntu:20.04

container: $[ variables['containerImage'] ]

steps:
- script: printenv

Multiple jobs on a single agent host

A container job uses the underlying host agent's Docker configuration file for image registry authorization. This file signs out at the end of the Docker registry container initialization.

Registry image pulls for container jobs could be denied for unauthorized authentication if another job running in parallel on the agent already signed out the Docker configuration file. The solution is to set a Docker environment variable called DOCKER_CONFIG for each agent pool running on the hosted agent.

Export the DOCKER_CONFIG in each agent pool's runsvc.sh script as follows:

export DOCKER_CONFIG=./.docker

Startup options

You can use the options property to specify options for container startup.

container:
  image: ubuntu:18.04
  options: --hostname container-test --ip 192.168.0.1

steps:
- script: echo hello

Run docker create --help to get the list of options you can pass to Docker invocation. Not all these options are guaranteed to work with Azure Pipelines. Check first to see if you can use a container property for the same purpose.

For more information, see the docker container create command reference and the resources.containers.container definition in the YAML schema reference for Azure Pipelines.

Reusable container definition

The following YAML example defines the containers in the resources section, and then references them by their assigned aliases. The jobs keyword is used for clarity.

resources:
  containers:
  - container: u16
    image: ubuntu:16.04

  - container: u18
    image: ubuntu:18.04

  - container: u20
    image: ubuntu:20.04

jobs:
- job: RunInContainer
  pool:
    vmImage: 'ubuntu-latest'

  strategy:
    matrix:
      ubuntu16:
        containerResource: u16
      ubuntu18:
        containerResource: u18
      ubuntu20:
        containerResource: u20

  container: $[ variables['containerResource'] ]

  steps:
  - script: printenv

Service endpoints

You can host containers on registries other than public Docker Hub. To host an image on Azure Container Registry or another private container registry, including a private Docker Hub registry, add a service connection to access the registry. Then you can reference the endpoint in the container definition.

Private Docker Hub connection:

container:
  image: registry:ubuntu1804
  endpoint: private_dockerhub_connection

Azure Container Registry connection:

container:
  image: myprivate.azurecr.io/windowsservercore:1803
  endpoint: my_acr_connection

Nonglibc-based containers

The hosted Azure Pipelines agents supply Node.js, which is required to run tasks and scripts. The Node.js version compiles against the C runtime used in the hosted cloud, typically glibc. Some Linux variants use other C runtimes. For instance, Alpine Linux uses musl. For more information, see Microsoft-hosted agents.

If you want to use a nonglibc-based container in a pipeline, you must:

• Supply your own copy of Node.js.
• Add a label to your image pointing to the location of the Node.js binary.
• Provide the bash, sudo, which, and groupadd Azure Pipelines dependencies.

Supply your own Node.js

If you use a nonglibc-based container, you must add a Node binary to your container. Node.js 18 is a safe choice. Start from the node:18-alpine image.

Direct the agent to Node.js

The agent reads the container label "com.azure.dev.pipelines.handler.node.path". If this label exists, it must be the path to the Node.js binary.

For example, in an image based on node:18-alpine, add the following line to your Dockerfile:

LABEL "com.azure.dev.pipelines.agent.handler.node.path"="/usr/local/bin/node"

Add required packages

Azure Pipelines requires a Bash-based system to have common administrative packages installed. Alpine Linux doesn't have several of the needed packages. Install bash, sudo, and shadow to cover basic needs.

RUN apk add bash sudo shadow

If you depend on any built-in or Marketplace tasks, also supply the binaries they require.

Full Dockerfile example

FROM node:18-alpine

RUN apk add --no-cache --virtual .pipeline-deps readline linux-pam \
  && apk add bash sudo shadow \
  && apk del .pipeline-deps

LABEL "com.azure.dev.pipelines.agent.handler.node.path"="/usr/local/bin/node"

CMD [ "node" ]

Related content

• Azure Pipelines jobs
• Azure Pipelines agents
• YAML schema resources.containers.container definition