Historically, when using the Pipelines Docker service, the step would automatically have the Docker CLI executable mounted into the build container. While this approach was initially convenient and helped onboard new customers, it limited flexibility in several areas.

For example, customers couldn’t easily use the latest docker buildx features because the CLI version was pinned. Additionally, some customers also expressed the need to use their own Docker-in-Docker (DinD) image for greater control.

However, recent improvements to our security posture allowed us to relax some Docker API restrictions, making new use cases possible. With these changes, which we are labelling Runtime 3, you can now safely run Docker with –privileged, use the latest Docker CLI, and bring your own DinD image.

How to use it

For detailed instructions on how to use all the new capabilities in the new runtime, check out the documentation.

For all steps

options:
  runtime:
    cloud:
      version: "3"

For a single step

- step:
    runtime:
      cloud:
        version: "3"

New capabilities

Privileged containers

Example of a Docker run with –privileged

privileged-docker-run:
  - step:
      runtime:
        cloud:
          version: "3"
      image: "<my-image-with-docker-cli>:latest"
      services:
        - docker
      script:
        - docker run --privileged alpine:3 sh -c "echo 20 > /proc/sys/vm/swappiness && cat /proc/sys/vm/swappiness"

Buildx multiarch builds

Example of a build on platforms amd64 and arm64

multi-arch-build:
  - step:
      runtime:
        cloud:
          version: "3"
      image: "<my-image-with-docker-cli-and-buildx>:latest"
      services:
        - docker
      script:
        - docker buildx create --name multiarch-builder --driver docker-container --use
        - docker buildx inspect --bootstrap
        - docker run --rm --privileged tonistiigi/binfmt --install all
        - docker buildx build -t test:local --platform=linux/amd64,linux/arm64 .

Buildx remote caches

Example using AWS S3 as remote cache on a fictional AWS account/role

remote-cache:
  - step:
      runtime:
        cloud:
          version: "3"
      image: "<my-image-with-docker-cli-and-buildx>:latest"
      services:
        - docker
      name: "upload cache"
      oidc: true
      script:
        - export AWS_DEFAULT_REGION="us-west-2"
        - export AWS_ROLE_ARN="arn:aws:iam::123456789012:role/pipeline-role"
        - export AWS_WEB_IDENTITY_TOKEN_FILE="$(pwd)/web-identity-token"
        - echo $BITBUCKET_STEP_OIDC_TOKEN > $(pwd)/web-identity-token
        - docker buildx create --name dc --driver docker-container --use
        - docker buildx build -t test:local --builder=dc --load --platform=linux/amd64 --cache-to type=s3,region=us-west-2,bucket=my-s3-bucket,name=${BITBUCKET_BUILD_NUMBER} .
        - docker run test:local
  - step:
      runtime:
        cloud:
          version: "3"
      image: "<my-image-with-docker-cli-and-buildx>:latest"
      services:
        - docker
      name: "use cache on build"
      oidc: true
      script:
        - export AWS_DEFAULT_REGION="us-west-2"
        - export AWS_ROLE_ARN="arn:aws:iam::123456789012:role/pipeline-role"
        - export AWS_WEB_IDENTITY_TOKEN_FILE="$(pwd)/web-identity-token"
        - echo $BITBUCKET_STEP_OIDC_TOKEN > $(pwd)/web-identity-token
        - docker buildx create --name dc --driver docker-container --use
        - docker buildx build -t test:local --builder=dc --load --platform=linux/amd64 --cache-from type=s3,region=us-west-2,bucket=my-s3-bucket,name=${BITBUCKET_BUILD_NUMBER} .
        - docker run test:local

BYO dind image

Example using a fictional AWS ECR repository and IAM Role

definitions:
  services:
    docker:
      image:
        name: 0123456789012.dkr.ecr.us-west-2.amazonaws.com/my-image-from-ecr:latest
        aws:
          oidc-role: arn:aws:iam::0123456789012:role/my-pipeline-role
      type: docker
options:
  runtime:
    cloud:
      version: "3"

Limitations

Docker CLI

As mentioned earlier, the Docker CLI is no longer automatically mounted in the build container. Therefore, to use Docker in Runtime v3, make sure the CLI is either included in the image or installed during the build step.

Docker cache

The Bitbucket Pipelines Docker cache feature has been deprecated. This means that if a step tries to use it, such as in the example below, it will be ignored and a warning message will be displayed.

caches:
  - docker

Instead, we recommend using Buildx caching for this purpose.

Feedback

We value your input. Please share any questions or suggestions about this feature in the Pipelines community space.