Bitbucket Pipelines で Docker コマンドを実行する

Bitbucket Pipelines のビルドパイプラインで Docker コマンドを実行することで、リポジトリの Dockerfile から Docker イメージをビルドし、それを Docker レジストリにプッシュできます。パイプライン環境はデフォルトで提供されているため、カスタマイズをすることなくすぐに利用を開始できます。

Docker へのアクセスの有効化

Docker デーモンへのアクセスを有効化するには、docker をステップにサービスとして追加する (推奨) か、bitbucket-pipelines.yml にグローバルオプションを追加します。

ビルドステップで Docker をサービスとして追加する (推奨)

pipelines:
  default:
    - step:
        script:
          - ...
        services:
          - docker

Docker を definitions セクションでサービスとして宣言する必要はありません。Docker は定義なしで利用できる、Pipelines で提供されるデフォルトサービスです。

リポジトリのすべてのビルドステップに Docker を追加する

options:
  docker: true

ここで Docker を宣言した場合も、引き続き Pipelines のサービスとして扱われ、1 GB メモリの制限を持ち、ビルドステップでは 2 つのサービスとの同時実行が許可されます。この設定は過去のサポートのために提供されたもので、パイプラインで実行できるサービス数の確認で混乱が生じる可能性があるため、ステップレベルでの設定を行うことをおすすめします。

動作の仕組み

Docker をサービスとして構成すると、次のようになります。

Docker CLI 実行ファイルをビルドコンテナでマウント
Docker デーモンへのビルドアクセスの実行および提供

これは、docker version を実行することで確認できます。

pipelines:
  default:
    - step:
        script:
          - docker version
        services:
          - docker

オンラインバリデーターを使用して bitbucket-pipelines.yml ファイルをチェックすることができます。

Docker BuildKit の有効化

Bitbucket Pipelines で Docker BuildKit を使用するには、パイプライン設定 (bitbucket-pipelines.yml) で DOCKER_BUILDKIT=1 環境変数を設定します。

例:

pipelines:
  default:
    - step:
        script:
          - export DOCKER_BUILDKIT=1
          - docker build .
        services:
          - docker

Docker BuildKit に関する情報は「Docker Docs — BuildKit でイメージをビルドする」をご参照ください。

Docker BuildKit の制限

ユーザーのセキュリティを保護するため、次の Docker BuildKit 機能が「Docker コマンドの実行」にリストされている機能に加えて無効になっています。

マルチアーキテクチャビルド
--platform オプション (docker run --platform linux/arm/v7 など)
Docker BuildKit Buildx のプラグイン

次の Dockerfile RUN 指示文オプションは Dockerfile フロントエンド構文とも呼ばれ、無効になっています。

RUN --mount=type=ssh — Bitbucket Pipelines SSH キーにアクセスするには、--ssh default=$BITBUCKET_SSH_KEY_FILE のように、BITBUCKET_SSH_KEY_FILE 変数を指定して --ssh オプションを使用します。
RUN --security=insecure

BuildKit Dockerfile フロントエンド構文の詳細については「Docker BuildKit GitHub リポジトリ - Dockerfile フロントエンド構文」をご覧ください。

Docker BuildKit キャッシングの制限

Docker Build 操作中に生成されるレイヤーのキャッシュに使用される定義済みの docker キャッシュは、BuildKit の使用時に生成されるレイヤーをキャッシュしません。

RUN --mount=type=cache Docker フロントエンド構文は、そのパイプラインステップが完了するまでのみキャッシュを保持します。パイプラインの他のステップや新しいパイプラインの実行では使用できません。

Docker BuildKit が有効になっていて、ビルドレイヤーをキャッシュする必要がある場合は、Docker Build --cache-from オプションを使用することをお勧めします。これにより、外部イメージレジストリに保存されている 1 つ以上のタグ付き画像をキャッシュソースとして使用できます。この方法では、定義済みの Docker キャッシュの 1 GB のサイズ制限も回避されます。

現在、--cache-to オプションなどの BuildKit の高度な機能はサポートされていません。

例:

docker build \
--cache-from $IMAGE:latest \
--tag $IMAGE:$BITBUCKET_BUILD_NUMBER \
--tag $IMAGE:latest \
--file ./Dockerfile \
--build-arg BUILDKIT_INLINE_CACHE=1 \
"."

ここで、--cache-from $IMAGE:latest は、Docker Hub などの外部レジストリに保存されている以前の成功したデプロイを指します。Docker build --cache-from オプションの使用方法については、「Docker Docs — 外部キャッシュソースの指定」を参照してください。

Docker BuildKit でシークレット変数と保護された変数を使用

docker build --build-arg オプションによって、シークレット変数または保護された変数 (パスワードや API キーなど) を BuildKit に渡さないでください。渡すと、生成される Docker イメージと Pipeline ログにシークレットが含まれます。

Docker BuildKit にはシークレット処理が含まれています。生成する Docker イメージ中のパスワード、API キー、その他の機密情報を保護するのに役立ちます。BuildKit シークレットを使用するには、--secret Docker Build オプションと--mount=type=secret BuildKit フロントエンド構文を使用します。

次の例は、BuildKit シークレットを次のものと併用する方法を示しています。

Bitbucket Pipelines の保護された変数を BuildKit と併用する

Bitbucket Pipelines の保護された変数は、--secret オプションによって BuildKit ビルドに直接渡せます。次に、--mount=type=secret BuildKit フロントエンド構文によってシークレットを BuildKit ビルド内で使用できます。

たとえば、MY_SECRET という名前の Bitbucket Pipelines の保護された変数を使用すると、パイプラインステップは次のようになります。

pipelines:
  default:
    - step:
        name: 'Using secure variables with BuildKit'
        script:
        # Enable Docker BuildKit
        - export DOCKER_BUILDKIT=1
        # Pass the MY_SECRET variable into the BuildKit docker build
        #   and prevent it from being cached.
        - docker image build -t latest --secret id=MY_SECRET --progress=plain --no-cache dockerfile
        services:
        - docker

この保護された変数は、次のような Docker の既定のシークレットストア (/run/secrets/*) から RUN 命令にマウントできます。

FROM ubuntu:latest

# Mount and print MY_SECRET
RUN --mount=type=secret,id=MY_SECRET \
  cat /run/secrets/MY_SECRET

この例では、シークレットは空白行をパイプラインログに返して、cat コマンドによってイメージレイヤーを生成するために使用されるコンテナーに出力されます。

Bitbucket Pipelines で BuildKit によって外部ソースのシークレットを使用する

外部シークレットマネージャー (HashiCorp Vault、Azure Key Vault、Google Cloud Secret Manager など) からのシークレットは、使用前にパイプライン上のファイルに保存する必要があります。パイプラインステップが完了してコンテナーが削除されると、ファイルは削除されます。

たとえば、MY_OTHER _SECRET を外部プロバイダーから使用するには、シークレットを外部プロバイダーから取得してファイルに保存し、--secret オプションによってビルドに渡します。この例では、外部プロバイダーからシークレットを取得する代わりに echo 'My secret API Key' を使用します。

pipelines:
  default:
    - step:
        name: 'Using secrets with BuildKit'
        script:
        # Enable Docker BuildKit
        - export DOCKER_BUILDKIT=1
        # Store external secret to a file on the pipeline, remember that the file and container are deleted at the end of the step.
        - echo 'My secret API key' > /my_secret_file
        # Pass MY_OTHER_SECRET into the BuildKit docker build
        #   and prevent it from being cached.
        - docker image build -t latest --secret id=MY_OTHER_SECRET,src=/my_secret_file --progress=plain --no-cache .
        services:
        - docker

保護された変数は、次のようなカスタムシークレットの場所 (/my_secret_file) から RUN 命令にマウントできます。

FROM ubuntu:latest

# Mount and print MY_OTHER_SECRET
RUN --mount=type=secret,id=MY_OTHER_SECRET,dst=/my_secret_file \
  cat /run/secrets/MY_OTHER_SECRET

Docker BuildKit に関するトラブルシューティング

Docker BuildKit が原因で Docker ビルドの問題が発生している場合は、docker コマンドの前に DOCKER_BUILDKIT=0 を設定することで、BuildKit を無効にできます。

次に例を示します。

pipelines:
  default:
    - step:
        script:
          - export DOCKER_BUILDKIT=0
          - docker build .
        services:
          - docker

Docker コマンドの実行

Pipelines スクリプトでは、ほとんどの Docker コマンドを実行できます。これらのコマンドの使用方法については「Docker コマンドラインのリファレンス」を参照してください。

以下にリストされた制限されたコマンドを含め、これらの制限は、クラウドインフラストラクチャで実行されるパイプラインにのみ適用されます。これらの制限は、自社ホストのパイプラインである [ランナー] には適用されません。

セキュリティ上の理由から、次のようないくつかの制限が必要になっています。

Docker Swarm 関連のコマンド
$BITBUCKET_CLONE_DIR 外のソースでボリュームをマッピングする
--platform オプション
docker run --privileged
docker run --mount

制限されるコマンドの完全な一覧

アトラシアンでは、お客様のデータのセキュリティを非常に重視しています。クラウドにデータを保管している場合は特に注意します。ユーザーデータを保護するため、以下が制限されています。

docker container run/docker run では、以下は禁止されています。

--cap-add
--device
--ipc
--mount
--pid
--privileged
--security-opt
--userns
--uts
--volume、-v (/opt/atlassian/bitbucketci/agent/build/.* または /opt/atlassian/pipelines/agent/build/.* 以外)

docker container update/docker update では、以下は禁止されています。

--devices

docker container exec/docker exec では、以下は禁止されています。

--privileged

docker image build / docker build では、以下は禁止されています。

--security-opt

Docker Compose の使用

コンテナで Docker Compose を使用したい場合は、自身のビルドコンテナと互換性のあるバイナリをインストールする必要があります。

外部の Docker デーモンを使用する

他の場所にホストされている独自の Docker デーモンに対してコマンドを実行するようにビルドを構成している場合、それを引き続き利用できます。この場合、Pipelines 内で Docker を有効化するのではなく、独自の CLI 実行ファイルをビルドイメージの一部として提供することをおすすめします。これにより、実行しているデーモンバージョンと CLI バージョンとの互換性を確保します。

Docker レイヤーのキャッシュについて

サービスとして Docker を追加した場合は、ステップに Docker キャッシュも追加できます。キャッシュを追加すると、以前にビルドしたレイヤーを再使用し、ステップでは必要に応じて新しい動的なレイヤーのみを作成するため、ビルドをより速く行うことができます。

pipelines:
  default:
    - step:
        script:
          - docker build ...
        services:
          - docker
        caches:
          - docker # adds docker layer caching 

Docker キャッシュの一般的な使用事例として、イメージのビルドがあります。キャッシュを有効化することでパフォーマンスが低下する場合、dockerfile のレイヤーが無効化されていないことを確認します。

Docker レイヤーキャッシュは、「キャッシュの依存関係」で説明されている通常のキャッシュと同様の制限および挙動を持ちます。

Docker のメモリ制限

既定では、Pipelines の Docker デーモンの合計メモリの上限は 1024 MB です。この割り当てには、docker run コマンド経由で実行するすべてのコンテナと、docker build コマンドの実行に必要なメモリが含まれます。

Docker で利用可能なメモリを増やすには、組み込みの docker サービスのメモリ制限を変更できます。memory パラメーターは 128 MB よりも大きい整数値で、ステップで利用可能なメモリにおさまるようにする必要があります。

複数の Docker サービスにメモリ制限を設定して、ステップ要件に応じて適切なサービスを使用する方法を示す実例を以下に示します。

definitions:
  services:
    docker:
      memory: 512
    docker-with-more-memory:
      memory: 2048
      type: docker
    docker-with-large-memory:
      memory: 5120
      type: docker

pipelines: 
  custom:
    pipeline1:
      - step:
         services: [docker]
         script:
           - echo "Docker service with 512 MB memory"
    pipeline2:
      - step:
         services: [docker-with-more-memory]
         script:
           - echo "Docker service with 2048 MB memory"
    pipeline3:
      - step:
         services: [docker-with-large-memory]
         size: 2x
         script:
           - echo "Docker service with 5120 MB memory"

以下の例では、Docker サービスに初期設定の割り当てである 1024MB の 2 倍 (2048MB) を割り当てています。他のサービスや、追加メモリ用に大規模なビルドを構成しているかどうかに応じて、さらに増加できます (メモリ制限の詳細についてご確認ください)。

pipelines:
  default:
    - step:
        script:
          - docker version
        services:
          - docker
definitions:
  services:
    docker:
      memory: 2048

Avoid resource constraints

If your pipeline uses an Atlassian Docker service to start a container, you can configure the amount of memory available to that container in your YAML file. If you don’t configure the memory available, the default memory limit for that Docker service will apply. For more details on memory limits in your Docker service, refer to Run Docker commands in Bitbucket Pipelines.

Many third-party tools you may be using, such as Java Virtual Machine (JVM), set their own limits on memory usage. Because of these limitations, you may need to set resource constraints on your container’s memory. For more information on resource constraints in Docker, check out the Docker doc on this exact topic.

The following examples provide what you need for setting memory limits for your Docker service which will help ensure your builds run successfully.

Example of setting memory limit via Docker CLI:

docker run --memory 1G your-image-name:image-tag echo 1

Example of setting memory limit via Docker Compose:

version: '3.7'
services:
  echo:
    image: your-image-name:image-tag
    entrypoint: ["echo", "1"]
    deploy:
      resources:
        limits:
          memory: 1G

レジストリへのプッシュ時の認証

レジストリにイメージをプッシュするには、docker login を使用して認証を行ってから docker push を呼び出す必要があります。ユーザー名とパスワードは変数を使用して設定することをおすすめします。

たとえば、パイプラインのスクリプトに次のテキストを追加します。

docker login --username $DOCKER_USERNAME --password $DOCKER_PASSWORD

予約済みのポート

ポートの制限

予約済みの使用できないポートがあります。

29418

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

正確ではなかった

明確ではなかった

関係なかった

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

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

コミュニティに質問