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

Bitbucket Pipelines allows you to build a Docker image from a Dockerfile in your repository and to push that to a Docker registry, by running Docker commands within your build pipeline. Dive straight in – the pipeline environment is provided by default and you don't need to customize it!

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

Pipelines のビルドでは、BuildKit が既定で有効になっています。

Docker BuildKit の無効化

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

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

次に例を示します。

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

For information on Docker BuildKit, visit: Docker Docs — Build images with BuildKit.

Docker BuildKit の制限

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

To protect the security of our users, the following Docker BuildKit features have been disabled in addition to the features listed in Running Docker commands:

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

次の 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

For information on BuildKit Dockerfile frontend syntaxes, visit: Docker BuildKit GitHub repository — Dockerfile frontend syntaxes.

Docker BuildKit キャッシングの制限

The predefined docker cache used for caching the layers produced during Docker Build operations does not cache layers produced when using 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.

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 によって外部ソースのシークレットを使用する

Secrets from external secret managers (such as HashiCorp Vault, Azure Key Vault, and Google Cloud Secret Manager) need to be stored into a file on the pipeline before they can be used. The file will be deleted once the pipeline step in complete and the container is removed.

たとえば、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 コマンドの実行

Inside your Pipelines script you can run most Docker commands. See the Docker command line reference for information on how to use these commands.

These restrictions, including the restricted commands listed below, only apply to the pipelines executed on our cloud infrastructure. These restrictions don't apply to the self-hosted pipeline Runners.

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

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 デーモンを使用する

If you have configured your build to run commands against your own Docker daemon hosted elsewhere, you can continue to do so. In this case, you should provide your own CLI executable as part of your build image (rather than enabling Docker in Pipelines), so the CLI version is compatible with the daemon version you are running.

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 

A common use case for Docker cache is when you are building images. However, if you find that performance slows with the cache enabled, check you are not invalidating the layers in your dockerfile.

Docker layer caches have the same limitations and behaviors as regular caches as described on Caching Dependencies.

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"

In the example below, we are are giving the docker service twice the default allocation of 1024 MB (2048). Depending on your other services and whether you have configured large builds for extra memory, you can increase this even further (learn more about memory limits).

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

使用可能なメモリの割り当て、またはメモリ制限の設定

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.

次の例は、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

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

To push images to a registry, you need to use docker login to authenticate prior to calling docker push. You should set your username and password using variables.

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

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

予約済みのポート

ポートの制限

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

29418

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

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

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

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

コミュニティに質問