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 — To access your Bitbucket Pipelines SSH keys, use the --ssh option with the BITBUCKET_SSH_KEY_FILE variable, such as --ssh default=$BITBUCKET_SSH_KEY_FILE
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 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 の保護された変数を使用すると、パイプラインステップは次のようになります。

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 など) からのシークレットは、使用前にパイプライン上のファイルに保存する必要があります。パイプラインステップが完了してコンテナーが削除されると、ファイルは削除されます。

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.

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 コマンドの実行に必要なメモリが含まれます。

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 サービスにメモリ制限を設定して、ステップ要件に応じて適切なサービスを使用する方法を示す実例を以下に示します。

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

リソース制約の回避

パイプラインで Atlassian Docker サービスを使用してコンテナーを開始する場合、そのコンテナーで使用可能なメモリ量を YAML ファイルで構成できます。使用可能なメモリを設定しない場合は、その Docker サービスの既定のメモリ制限が適用されます。Docker サービスのメモリ制限の詳細については、「Bitbucket Pipelines で Docker コマンドを実行する」を参照してください。

Java 仮想マシン (JVM) などサードパーティツールの多くは、メモリ使用量に独自の制限を設けています。こうした制限のため、コンテナーのメモリにリソース制約を設定することが必要になる場合があります。Docker のリソース制約の詳細については、このトピックに関する Docker のドキュメントをチェックしてください。

次の例は、Docker サービスのメモリ制限を行うために必要な設定を示しています。これは、ビルドを正常に実行するのに役立ちます。

Docker CLI でメモリ制限を設定する例:

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

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

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

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

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

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

コミュニティに質問