Runtime v3 を有効にして使用する

Bitbucket Pipelines ランタイム v3 では、Docker サービスをより柔軟に使用できます。最近のセキュリティ改善により、以前の Docker 制限の一部が緩和されました。

ランタイム v3 の機能

Pipelines 内で Docker API へのより直接的なアクセスが可能になります。これには、privileged コンテナーの使用も含まれます。特権コンテナーのセクションを参照してください。
顧客が docker buildx にアクセスできるようになり、マルチアーキテクチャイメージを構築する際の効率が大幅に向上します。Docker Buildx のセクションを参照してください。
Docker CLI を直接制御できるため、顧客は、Pipelines によって提供されるバージョンに依存せずに、ビルドに必要な CLI の正確なバージョンを指定できます。BYO Docker CLI のセクションを参照してください。
顧客が独自の Docker-in-Docker (DinD) イメージを持ち込むことができるため、ビルド環境をより細かく制御できるようになります。BYO DinD のセクションを参照してください。

ランタイム v3 を有効にする

ランタイム v3 を有効にするには、パイプライン設定でランタイムバージョンを指定して、この機能にオプトインする必要があります。bitbucket-pipelines.yml ファイルに次の行を追加します。

options:
  runtime:
    cloud:
      version: 3

特定のステップで有効にするには、bitbucket-pipelines.yml ファイルに次の行を追加します。

- step:
    runtime:
      cloud:
        version: 3

次に挙げるのは、ランタイム v3 で導入された主な変更点、その詳細情報、およびそれらを効果的に活用する方法の例です。

制限事項

Docker CLI のマウントの取り止め

前述のとおり、Docker CLI はビルドコンテナーに自動的にマウントされなくなりました。したがって、ランタイム v3 で Docker を使用するには、CLI がイメージに含まれているか、ビルドステップ中にインストールされていることを確認してください。

Docker キャッシュの廃止

Bitbucket Pipelines の Docker キャッシュ機能は廃止されました。つまり、ステップでこの機能を使用しようとすると無視され、警告メッセージが表示されます。

この目的には Buildx キャッシュを使用することをお勧めします。

特権コンテナー

Docker で特権コンテナーを利用することで、より高度なコンテナーワークフローを実行できます。

docker run は、--privileged フラグを含む任意の引数で使用できます。以前のランタイムバージョンでは、共有環境内での潜在的なセキュリティリスクを防ぐためにこれが制限されていました。ただし、最近の変更により、コンテナーの分離が改善され、サンドボックスが強化されたため、ビルドステップで特権モードを安全に使用できるようになりました。

これが重要な理由

--privileged を使用すると、次のようないくつかの高度な Docker 機能が利用可能になります。

Docker-in-Docker (DinD) を制限なく実行できる
コンテナー内の低レベルのシステム操作にアクセスできる
loopback デバイスやカスタムカーネルモジュールなど、完全な機能やマウントを必要とするソフトウェアを使用できる

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

特権モードは現在サポートされていますが、注意して使用する必要があります。絶対に必要な場合にのみ使用し、実行するイメージが信頼できるものであることを確認してください。

--privileged を有効にすると、ランタイム v3 では、ローカル開発環境に合わせたり、これまで Pipelines でサポートされていなかった複雑なツールを実行したりするための柔軟性がユーザーにもたらされます。

Docker Buildx

Bitbucket Pipelines ランタイム v3 では、マルチプラットフォームイメージのビルド、高度なキャッシュ、およびきめ細かい Docker ビルドのための強力な拡張機能である Docker Buildx が完全にサポートされています。Buildx により、より高速で柔軟なビルドが可能になり、Docker BuildKit の機能を最大限に活用できるようになります。

パイプラインで Buildx を有効にする

Buildx を使用するには、まずパイプラインイメージに Docker CLI と Buildx プラグインがインストールされていることを確認してください。有効にすると、ステップ内で高度な docker buildx build コマンドを直接実行できるようになります。

Docker CLI と Buildx をインストールする

ビルドコンテナーに Docker CLI を配置するには、次の 2 つの方法があります。

一方のオプションは、スクリプトセクションの一部としてインストールすることです。
ただし、ビルドイメージの一部としてインストールする方が効率的です。

次の例では、Dockerfile を通じて、Docker CLI とともに、docker-compose や docker-buildx プラグインなどのその他の便利な依存関係をコピーしています。

FROM docker:28.1.1-cli AS docker-cli
FROM ubuntu:24.04
# Copy Docker CLI, Buildx plugin and docker-compose
COPY --from=docker-cli /usr/local/bin/docker /usr/local/bin/docker
COPY --from=docker-cli /usr/local/libexec/docker/cli-plugins/docker-buildx /usr/local/libexec/docker/cli-plugins/docker-buildx
COPY --from=docker-cli /usr/local/bin/docker-compose /usr/local/bin/docker-compose
# etc..

マルチアーキテクチャビルド

Docker Buildx を利用して、パイプライン内で直接マルチプラットフォーム Docker イメージをビルドできるようになりました。Docker Buildx は Docker のビルド機能の拡張機能であり、単一のパイプライン実行から複数のアーキテクチャ (x86_64、arm64、armv7 など) のイメージをビルドできるため、クロスプラットフォーム開発のための強力なツールとなります。

Docker Buildx では、強化されたキャッシュ機能、優れたパフォーマンス、より高度なビルドオプションとの連携 (BuildKit を使用したイメージのビルドなど) も提供されます。

options:
  runtime:
    cloud:
      version: "3"
pipelines:
  custom:
    multi-arch-build:
      - step:
          image: "<my-image-with-docker-cli-and-buildx>"
          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 によるビルドキャッシュ

Buildx は、パイプラインを高速化し、冗長な計算を削減し、クロスステップのパフォーマンスを向上させる高度なキャッシュ戦略にも対応しています。Bitbucket Pipelines では次のキャッシュタイプがサポートされています。

リモート S3 キャッシュ

S3 バケットを使用して、ビルド、ランナー、さらにはリポジトリ間でキャッシュレイヤーを永続化します。

options:
  runtime:
    cloud:
      version: "3"
pipelines:
  custom:
    remote-cache:
      - step:
          image: "<my-image-with-docker-cli-and-buildx>"
          services:
            - docker
          name: "upload cache"
          oidc: true
          script:
            - export AWS_DEFAULT_REGION="us-east-1"
            - 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:
          image: "<my-image-with-docker-cli-and-buildx>"
          services:
            - docker
          name: "use cache on build"
          oidc: true
          script:
            - export AWS_DEFAULT_REGION="us-east-1"
            - 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

ビルド環境には、S3 バケットにアクセスする権限を持つ AWS 認証情報が必要です。

ローカルキャッシュ

ローカルキャッシュでは、パイプラインステップ間 (同じランナー上) で共有できるディレクトリにビルドレイヤーが保存されます。

options:
  runtime:
    cloud:
      version: "3"
pipelines:
  custom:
    local-cache:
      - step:
          image: "<my-image-with-docker-cli-and-buildx>"
          services:
            - docker
          script:
            - docker buildx create --use
            - docker buildx build --tag my-image:latest --cache-to=type=local,dest=/tmp/.buildx-cache --cache-from=type=local,src=/tmp/.buildx-cache .

このキャッシュディレクトリをステップ間で永続化する場合は、パイプラインで artifacts セクションを使用します。

レート制限を回避する

Buildx ビルド中にレート制限に達するのを回避するための一般的な方法は、Docker レジストリにログインすることです。

options:
  runtime:
    cloud:
      version: "3"
pipelines:
  custom:
    docker-hub-login:
      - step:
          script:
            - echo "$DOCKERHUB_PASSWORD" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            - docker buildx create --name mybuilder --driver docker-container --use
            - docker buildx build -t myimage:latest .

もう 1 つの方法は、カスタム Docker レジストリミラーを設定することです。アトラシアンのサーバーは AWS us-east-1 で実行されるため、レイテンシーを削減し、最適なパフォーマンスを確保するために、同じリージョンまたは近くにミラーを設定することをお勧めします。

options:
  runtime:
    cloud:
      version: "3"
pipelines:
  custom:
    custom-registry-mirror:
      - step:
          script:
            - |
              cat <<EOF > buildkitd.toml
              debug = true
              [registry."docker.io"]
                mirrors = ["<your-registry-mirror>"]
              EOF
            - docker buildx create --config ./buildkitd.toml --name mybuilder --driver docker-container --use
            - docker buildx build -t myimage:latest .
            - docker logs buildx_buildkit_mybuilder0

docker logs コマンドは、それが機能したことを確認するためのものです。

独自の (BYO) Docker CLI を持ち込む

以前のランタイムでは、固定バージョンの Docker CLI がビルドコンテナーに自動的にマウントされていました。現在はそれが取り止められています。代わりに、ランタイム v3 で Docker を使用するには、CLI がイメージに含まれているか、ビルドステップ中にインストールされていることを確認してください。これにより、新しい Docker 機能の使用を希望するユーザーにとって柔軟性が向上します。

Docker CLI をインストールする

ビルドコンテナーに Docker CLI を配置するには、次の 2 つの方法があります。

一方のオプションは、スクリプトセクションの一部としてインストールすることです。
ただし、ビルドイメージの一部としてインストールする方が効率的です。

次の例では、Dockerfile を通じて、Docker CLI とともに、docker-compose や docker-buildx プラグインなどのその他の便利な依存関係をコピーしています。

FROM docker:28.1.1-cli AS docker-cli
FROM ubuntu:24.04
# Copy Docker CLI, Buildx plugin and docker-compose
COPY --from=docker-cli /usr/local/bin/docker /usr/local/bin/docker
COPY --from=docker-cli /usr/local/libexec/docker/cli-plugins/docker-buildx /usr/local/libexec/docker/cli-plugins/docker-buildx
COPY --from=docker-cli /usr/local/bin/docker-compose /usr/local/bin/docker-compose
# etc..

新しい既定のイメージ

新しい atlassian/default-image:5 には Docker CLI が含まれています。ただし、このイメージが将来も変更されないことは保証できないため、独自のカスタムイメージを使用することを強くお勧めします。

BYO Docker-in-Docker (DinD)

ランタイム v3 では、独自の (BYO) Docker-in-Docker (DinD) イメージの持ち込みがサポートされています。この機能により、特定のニーズに合ったカスタム Docker イメージを指定できるようになり、柔軟性が向上します。公式の Docker DinD イメージを使用することも、AWS ECR などのコンテナーレジストリ、または任意の別のレジストリでホストされている非公開イメージを使用することもできます。

公式の Docker DinD イメージを使用する

次の例では、Docker サービス用の公式の docker:28-dind イメージを使用しています。これはパイプライン内で DinD を設定する最も簡単な方法です。

definitions:
  services:
    docker:
      image:
        name: docker:28-dind
      type: docker

AWS ECR からのカスタム Docker イメージを使用する

この例では、OIDC ベースの認証用の適切な AWS IAM ロールとともに、AWS ECR でホストされているカスタム Docker イメージを指定できます。

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

既定の DinD イメージ

Pipelines の以前のランタイム環境では、セキュリティ上の理由から、アトラシアンの非公開 DinD イメージを使用していましたが、これは古くなることがありました。現在は、イメージの指定がなければ、既定で docker:dind が使用されます。ただし、Docker サービスを使用する場合は、常に Docker イメージを固定することをお勧めします。そのための方法については、上記の「BYO Docker-in-Docker (DinD)」セクションで説明されています。

既定の DinD 引数

以前のランタイムバージョンでは、DinD は次の引数を使用して実行されていました。

--authorization-plugin=pipelines \
--storage-driver=overlay2 \
--registry-mirror http://${DOCKER_REGISTRY_MIRROR_HOST}:5000 \
--insecure-registry ${DOCKER_REGISTRY_MIRROR_HOST}:5000 \
--userns-remap=default \
--tls=false \
--log-level info

ランタイム v3 では、次の引数が使用されます。次の例では、DOCKER_REGISTRY_MIRROR_HOST 環境変数は内部 Docker レジストリミラー IP を指しています。

--storage-driver=overlay2
--registry-mirror http://${DOCKER_REGISTRY_MIRROR_HOST}:5000
--insecure-registry ${DOCKER_REGISTRY_MIRROR_HOST}:5000
--tls=false
--log-level info

現時点では、これらの引数を上書きすることはできません。

ユーザー名前空間の再マッピングの無効化

ユーザー名前空間の再マッピング (つまり、--userns-remap) は Docker サービスでは既定で無効になっています。これにより、一貫したユーザー ID またはコンテナー内での書き込みアクセスを必要とするビルドプロセスとの互換性が向上します。

これが重要な理由

この変更により、ボリュームの権限が簡素化され、ボリュームをマウントする際やコンテナー内で useradd を実行する際に発生する問題を回避できます。
Dind ビルド内の UID/GID マッピングについて心配する必要がなくなりました。

Dind ルートファイルシステムへの書き込みアクセス

以前のバージョンとは異なり、DinD コンテナーのルートファイルシステムへの書き込みアクセスが許可されます。

これによって可能になること

DinD コンテナー内で直接パッケージをインストールしたり、ファイルを変更したりできます。
ビルド中に DinD イメージをその場で簡単にカスタマイズできます。

この内容はお役に立ちましたか?

正確ではなかった明確ではなかった関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問