Docker Hub イメージとのやり取り

Docker Hub のコンテナイメージを使用して、Cloud Build でタスクを実行できます。また、ビルドで作成したイメージを Docker Hub に push できます。このページでは、Docker Hub イメージの push と pull を行うようにビルド構成ファイルを記述する方法について説明します。ビルド構成ファイルで使用できるフィールドの概要については、ビルド構成の概要をご覧ください。

Docker Hub から一般公開のイメージを pull する

Docker Hub に格納されている公式の Docker イメージ、Docker 認定イメージ、カスタムイメージをビルドステップで pull するには、name フィールドにイメージの名前を指定します。Cloud Build は、指定されたイメージを先に Docker Hub から pull し、そのイメージを使用してビルドステップを実行します。

次の例では、Cloud Build は maven の Docker イメージを pull し、args に指定された mvn コマンドを実行します。

YAML

steps:
- name: "maven"
  args: ["mvn", "--version"]

JSON

{
   "steps": [
      {
         "name": "maven",
         "args": [
            "mvn",
            "--version"
         ]
      }
   ]
}

Secret Manager に Docker 認証情報を保存する

限定公開のイメージを pull し、一般公開のイメージと限定公開のイメージを Docker Hub に push するには、Cloud Build が認証情報を使用して Docker に対して認証する必要があります。ビルドに Docker 認証情報を含めるには、まずシークレットを Secret Manager に保存してから、Cloud Build に Secret Manager からシークレットにアクセスする権限を付与する必要があります。

Docker 認証情報を Secret Manager に保存するには:

Cloud Console の [Secret Manager] ページに移動します。

[Secret Manager] ページに移動
[シークレットマネージャー] ページで、[シークレットを作成] をクリックします。
[シークレットの作成] ページの [名前] に「docker-username」と入力します。
[シークレットの値] フィールドに、Docker のユーザー名を入力します。
[リージョン] セクションは変更しません。
[シークレットを作成] ボタンをクリックします。

上記の手順を繰り返して、Docker のパスワードを Secret Manager に保存します。

ビルドに使用しているサービスアカウントにシークレットの Secret Manager シークレットアクセサー IAM ロールを付与するには:

Google Cloud コンソールで [シークレットマネージャー] ページを開きます。

[Secret Manager] ページに移動
Docker のユーザー名とパスワードに対応するシークレットのチェックボックスをオンにします。
まだ開いていない場合は、[情報パネルを表示] をクリックしてパネルを開きます。
パネルの [権限] で、[プリンシパルを追加] をクリックします。
[新しいプリンシパル] フィールドに、サービスアカウントのメールアドレスを入力します。
[ロールを選択] プルダウンボックスで、[Secret Manager のシークレットアクセサー] のロールを選択します。
[保存] をクリックします。

Docker Hub から限定公開のイメージを pull する

Docker Hub から限定公開のイメージを pull するには:

Secret Manager に Docker 認証情報が保存されていて、Cloud Build にシークレットにアクセスする権限が付与されていることを確認します。

ビルド構成ファイルで、次のことを行います。

すべてのビルド steps の後に、シークレットのバージョンと Docker のユーザー名とパスワードの環境変数を指定する availableSecrets フィールドを追加します。
ユーザー名とパスワードを指定するビルドステップで、次のようにします。
- ビルドステップで bash ツールを使用するには、bash を指す entrypoint フィールドを追加します。これは、シークレットの環境変数を参照するために必要です。
- ユーザー名とパスワードの環境変数を指定する secretEnv フィールドを追加します。
- args フィールドに、最初の引数として -c フラグを追加します。-c の後に渡した文字列はすべてコマンドとして扱われます。-c で bash コマンドを実行する方法の詳細については、bash のドキュメントをご覧ください。
- args フィールドにシークレットを指定する場合は、$$.

The following build config file shows how to login to Docker using the Docker username and password stored in Secret Manager, and run a private image.

YAML

 steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: "gcr.io/cloud-builders/docker"
   entrypoint: 'bash'
   args: ['-c', 'docker run $$USERNAME/REPOSITORY:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   secretManager:
   - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
     env: 'PASSWORD'
   - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
     env: 'USERNAME'
 を接頭辞とする環境変数を使用して指定します。 JSON 
{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker run $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "secretManager": [{
      "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
     }]
  }
}

Replace the placeholder values in the above commands with the following:

PROJECT_ID: The ID of the Google Cloud project where you've stored your secrets.
DOCKER_USERNAME_SECRET_NAME: The secret name corresponding to your Docker username.
DOCKER_USERNAME_SECRET_VERSION: The secret version of your Docker username.
DOCKER_PASSWORD_SECRET_NAME: The secret name corresponding to your Docker password.
DOCKER_PASSWORD_SECRET_VERSION: The secret version of your Docker password.
REPOSITORY: The name of your Docker repository from where you're pulling the image.
TAG: The tag name of your image.

Use the build config file to manually start a build or to automate builds using triggers.

Pushing images to Docker Hub

To push public and private images to Docker Hub:

Make sure you've stored your Docker credentials in Secret Manager and granted permissions for Cloud Build to access the secret.

In the build config file:

After all the build steps, add an availableSecrets field specifying the secret version and the env variable for the Docker username and password.
In the build step where you want to specify the username and password:
- Add an entrypoint field pointing to bash to use the bash tool in the build step. This is required to refer to the environment variable for the secret.
- Add a secretEnv field specifying the environment variable for username and password.
- In the args field, add a -c flag as the first argument. Any string you pass after -c is treated as a command. For more information on running bash commands with -c, see the bash documentation.
- When specifying the secret in the args field, specify it using the environment variable prefixed with $$.

The following example build config file shows how to login to Docker, build an image with source code stored locally, and then push the image to Docker repository.

YAML

 steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker build -t $$USERNAME/REPOSITORY:TAG .']
   secretEnv: ['USERNAME']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker push $$USERNAME/REPOSITORY:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   secretManager:
   - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
     env: 'PASSWORD'
   - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
     env: 'USERNAME'

JSON

{
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker build -t $$USERNAME/REPOSITORY:TAG ."
     ],
     "secretEnv": [
      "USERNAME"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker push $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "secretManager": [{
      "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
     }]
  }
}

上記のコマンドのプレースホルダ値を次のように置き換えます。

PROJECT_ID: シークレットを保存している Google Cloud プロジェクトの ID。
DOCKER_USERNAME_SECRET_NAME: Docker ユーザー名に対応するシークレット名。
DOCKER_USERNAME_SECRET_VERSION: Docker ユーザー名のシークレットバージョン。
DOCKER_PASSWORD_SECRET_NAME: Docker パスワードに対応するシークレット名。
DOCKER_PASSWORD_SECRET_VERSION: Docker パスワードのシークレットバージョン。
REPOSITORY: イメージを push する Docker リポジトリの名前。
TAG: イメージのタグ名。

ビルド構成ファイルを使用して、ビルドを手動で開始するか、トリガーを使用してビルドを自動化します。

Docker クライアントバージョンの操作

Cloud Build でサポートされている Docker ビルダー gcr.io/cloud-builders/docker は、Docker 20.10.14 を使用します。このバージョンでは、Docker にイメージを push するときにタグを指定しない場合、Docker は latest タグを持つイメージのみを push します。latest タグが存在しない場合、push が失敗します。

特定のタグを持つイメージを Docker に push するには、docker push ビルドステップでタグを指定します。次の例では、prod タグが付いたイメージを push します。

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push", 
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

イメージのすべてのタグを Docker に push するには、docker push ビルドステップの引数のリストに -a フラグを追加します。

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '-a', '$$USERNAME/myrepo']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push",
      "-a",
      "$$USERNAME/myrepo"
      ],
  }
  ...
}

Docker クライアント 19.03.9 を使用するには、Docker ビルダーのバージョンをタグ付けします。

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker:19.03.9'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker:19.03.9",
    "args": [
      "docker",
      "push",
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

次のステップ

基本的なビルド構成ファイルを作成する方法を学習する。
手動でビルドを実行する方法やビルドトリガーで自動化する方法を学習する。

Docker Hub イメージとのやり取り

Docker Hub から一般公開のイメージを pull する

YAML

JSON

Secret Manager に Docker 認証情報を保存する

Docker Hub から限定公開のイメージを pull する

YAML

JSON

Pushing images to Docker Hub

YAML

JSON

Docker クライアント バージョンの操作

YAML

JSON

YAML

JSON

YAML

JSON

次のステップ

Docker クライアントバージョンの操作