Bitbucket Cloud の使用を開始する
Bitbucket Cloud を初めてお使いですか? 新規ユーザー用のガイドをご利用ください。
Bitbucket Pipelines で Docker コマンドを実行する
Bitbucket Pipelines のビルド パイプラインで Docker コマンドを実行することで、リポジトリの Dockerfile から Docker イメージをビルドし、それを Docker レジストリにプッシュできます。パイプライン環境はデフォルトで提供されているため、カスタマイズをすることなくすぐに利用を開始できます。
Docker へのアクセスの有効化
Docker デーモンへのアクセスを有効化するには、docker をステップにサービスとして追加する (推奨) か、bitbucket-pipelines.yml にグローバル オプションを追加します。
ビルド ステップで Docker をサービスとして追加する (推奨)
1
2
3
4
5
6
7
pipelines:
default:
- step:
script:
- ...
services:
- dockerDocker を 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 の有効化
Bitbucket Pipelines で Docker BuildKit を使用するには、パイプライン設定 (bitbucket-pipelines.yml) で DOCKER_BUILDKIT=1 環境変数を設定します。
例:
1
2
3
4
5
6
7
8
pipelines:
default:
- step:
script:
- export DOCKER_BUILDKIT=1
- docker build .
services:
- dockerDocker 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 のサイズ制限も回避されます。
例:
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 \
"."ここで、--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 の保護された変数を使用すると、パイプライン ステップは次のようになります。
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この保護された変数は、次のような Docker の既定のシークレット ストア (/run/secrets/*) から RUN 命令にマウントできます。
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この例では、シークレットは空白行をパイプライン ログに返して、cat コマンドによってイメージ レイヤーを生成するために使用されるコンテナーに出力されます。
Bitbucket Pipelines で BuildKit によって外部ソースのシークレットを使用する
外部シークレット マネージャー (HashiCorp Vault、Azure Key Vault、Google Cloud Secret Manager など) からのシークレットは、使用前にパイプライン上のファイルに保存する必要があります。パイプライン ステップが完了してコンテナーが削除されると、ファイルは削除されます。
たとえば、MY_OTHER _SECRET を外部プロバイダーから使用するには、シークレットを外部プロバイダーから取得してファイルに保存し、--secret オプションによってビルドに渡します。この例では、外部プロバイダーからシークレットを取得する代わりに echo 'My secret API Key' を使用します。
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保護された変数は、次のようなカスタム シークレットの場所 (/my_secret_file) から RUN 命令にマウントできます。
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この例では、シークレットは空白行をパイプライン ログに返して、cat コマンドによってイメージ レイヤーを生成するために使用されるコンテナーに出力されます。
Docker BuildKit に関するトラブルシューティング
Docker BuildKit が原因で Docker ビルドの問題が発生している場合は、docker コマンドの前に DOCKER_BUILDKIT=0 を設定することで、BuildKit を無効にできます。
次に例を示します。
1
2
3
4
5
6
7
8
pipelines:
default:
- step:
script:
- export DOCKER_BUILDKIT=0
- docker build .
services:
- dockerDocker コマンドの実行
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 キャッシュも追加できます。キャッシュを追加すると、以前にビルドしたレイヤーを再使用し、ステップでは必要に応じて新しい動的なレイヤーのみを作成するため、ビルドをより速く行うことができます。
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 コマンドの実行に必要なメモリが含まれます。
Docker で利用可能なメモリを増やすには、組み込みの docker サービスのメモリ制限を変更できます。memory パラメーターは 128 MB よりも大きい整数値で、ステップで利用可能なメモリにおさまるようにする必要があります。
複数の 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
この内容はお役に立ちましたか?