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 つのサービスとの同時実行が許可されます。この設定は過去のサポートのために提供されたもので、パイプラインで実行できるサービス数の確認で混乱が生じる可能性があるため、ステップレベルでの設定を行うことをおすすめします。

動作の仕組み

Enable and use Runtime v3 to avoid having to rely on and mount the Docker CLI version provided by Pipelines. See the Runtime v3 documentation for more detailed information.

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

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

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

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

オンラインバリデーターによって bitbucket-pipelines.yml ファイルをチェックできます。

Docker BuildKit

BuildKit is enabled by default in Pipelines builds.

Disable Docker BuildKit

Runtime v3 supports all Docker Buildkit and Buildx features. See the Runtime v3 documentation for more detailed information.

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

次に例を示します。

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

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

Docker BuildKit の制限

Consider using Runtime v3 as these restrictions do not apply. See the Runtime v3 documentation for more detailed information.

ユーザーのセキュリティを保護するため、次の 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 --build-arg オプションによって、シークレット変数または保護された変数 (パスワードや API キーなど) を BuildKit に渡さないでください。渡すと、生成される Docker イメージと Pipeline ログにシークレットが含まれます。

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

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

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

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

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

Consider using Runtime v3 as these restrictions do not apply. See the Runtime v3 documentation for more detailed information.

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

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 レイヤーのキャッシュについて

This feature has been deprecated in Runtime v3. Consider using Runtime v3 to have more control over your builds. See the help documentation for more detailed information.

サービスとして 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

Allocate available memory or set memory limits

パイプラインで 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

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

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

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

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

コミュニティに質問