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

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

Docker へのアクセスの有効化

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

1 2 3 4 5 6 7 pipelines: default: - step: script: - ... services: - docker

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

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

1 2 options: docker: true

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

動作の仕組み

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

  • Docker CLI 実行ファイルをビルド コンテナでマウント

  • Docker デーモンへのビルド アクセスの実行および提供

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

1 2 3 4 5 6 7 pipelines: default: - step: script: - docker version services: - docker

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

Docker BuildKit の有効化

To use Docker BuildKit in a Bitbucket Pipeline, set the DOCKER_BUILDKIT=1 environment variable in the pipeline configuration (bitbucket-pipelines.yml).

例:

1 2 3 4 5 6 7 8 pipelines: default: - step: script: - export DOCKER_BUILDKIT=1 - docker build . services: - docker

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

Docker BuildKit の制限

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

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

  • the --platform option (such as docker run --platform linux/arm/v7)

The following Dockerfile RUN directive options, also known as Dockerfile frontend syntaxes, have been disabled:

  • RUN --mount=type=ssh — To access your Bitbucket Pipelines SSH keys, use the --ssh option, such as: --ssh default=/opt/atlassian/pipelines/agent/ssh/id_rsa

  • RUN --network=host

  • RUN --security=insecure

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

Docker BuildKit キャッシングの制限

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

The RUN --mount=type=cache Docker frontend syntax will only retain the cache until the pipeline step is complete; it will not be available for other steps in the pipeline or new pipeline runs.

If Docker BuildKit is enabled and the build layers need to be cached, we recommend using the Docker Build --cache-from option. This allows one or more tagged images stored in an external image registry to be used as a cache source. This methods also avoids the 1GB size limit of the predefined docker cache.

例:

1 2 3 4 5 6 7 docker build \ --cache-from $IMAGE:latest \ --tag $IMAGE:$BITBUCKET_BUILD_NUMBER \ --tag $IMAGE:latest \ --file ./Dockerfile \ --build-arg BUILDKIT_INLINE_CACHE=1 \ "."

Where --cache-from $IMAGE:latest points to the previous successful deployment stored on an external registry, such as Docker Hub. For information about using the Docker build --cache-from option, visit: Docker docs — Specifying external cache sources.

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

Do not pass secrets or secure variables (such as passwords and API keys) to BuildKit using the docker build --build-arg option. This will cause the secret to be included in the resulting Docker image and the Pipeline logs.

Docker BuildKit includes secret handling; helping to keep your passwords, API keys, and other sensitive information out of the Docker images you generate. To use BuildKit secrets, use the --secret Docker Build option, and the --mount=type=secret BuildKit frontend syntax.

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

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

Bitbucket Pipelines Secure variables can be passed directly to a BuildKit build using the --secret option, then the secret can be used inside the BuildKit build using the --mount=type=secret BuildKit frontend syntax.

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

1 2 3 4 5 6 7 8 9 10 11 12 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

The secure variable then can be mounted on the RUN instruction from the Docker default secret store (/run/secrets/*) such as:

1 2 3 4 5 FROM ubuntu:latest # Mount and print MY_SECRET RUN --mount=type=secret,id=MY_SECRET \ cat /run/secrets/MY_SECRET

In this example, the secret will return a blank line in the pipeline log and would be printed in the container used to generate the image layer by the cat command.

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

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

For example, to use MY_OTHER _SECRET from an external provider; get the secret from the external provider, store it in a file, and pass it to the build using the --secret option. This example uses echo 'My secret API Key' instead of retrieving a secret from an external provider.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 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

The secure variable can then be mounted on the RUN instruction from the custom secret location (/my_secret_file), such as:

1 2 3 4 5 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

In this example, the secret will return a blank line in the pipeline log and would be printed in the container used to generate the image layer by the cat command.

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

If you are experiencing issues Docker build issues due to Docker BuildKit, you can disable BuildKit by setting DOCKER_BUILDKIT=0 before the docker command.

次に例を示します。

1 2 3 4 5 6 7 8 pipelines: default: - step: script: - export DOCKER_BUILDKIT=0 - docker build . services: - docker

Docker コマンドの実行

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

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

  • Docker Swarm 関連のコマンド

  • mapping volumes with a source outside $BITBUCKET_CLONE_DIR

  • the --platform option

  • docker run --privileged

  • docker run --mount

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

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

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

  • --cap-add

  • --device

  • --ipc

  • --mount

  • --network

  • --pid

  • --privileged

  • --security-opt

  • --userns

  • --uts

  • --volume, -v (other than /opt/atlassian/bitbucketci/agent/build/.* or /opt/atlassian/pipelines/agent/build/.*)

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

  • --devices

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

  • --privileged

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

  • --network

  • --security-opt

Docker Compose の使用

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

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

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

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

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

1 2 3 4 5 6 7 8 9 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 コマンドの実行に必要なメモリが含まれます。

To increase the memory available to Docker you can change the memory limit for the built-in docker service. The memory parameter is a whole number of megabytes greater than 128 and not larger than the available memory for the step.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 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) を割り当てています。他のサービスや、追加メモリ用に大規模なビルドを構成しているかどうかに応じて、さらに増加できます (メモリ制限の詳細についてご確認ください)。

1 2 3 4 5 6 7 8 9 10 11 pipelines: default: - step: script: - docker version services: - docker definitions: services: docker: memory: 2048

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

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

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

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

予約済みのポート

ポートの制限

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

  • 29418

その他のヘルプ