Cloud Deploy と CI システムの統合

このドキュメントでは、継続的インテグレーション（CI）システムから Cloud Deploy デリバリー パイプラインを呼び出す方法について説明します。

Cloud Deploy と CI システムの統合は、Cloud Deploy gcloud CLI への呼び出しを追加するだけで簡単です。この呼び出しは、CI パイプラインでアプリケーションをデプロイする準備ができた時点で発生します。

注: CI プロセスにより、イメージのビルドと配置が行われます。これにより、Cloud Deploy は、デプロイのためにイメージを参照できます。

始める前に

このページで説明する手順は、次の条件を満たしていることを前提としています。

• 該当する API を有効にしている。

• 1 つ以上のデリバリー パイプラインが Cloud Deploy で定義され、登録されている。

• 少なくとも 1 つのターゲットが定義され、そのターゲットを参照しているデリバリー パイプラインを参照している。

CI パイプラインから Cloud Deploy を呼び出す

注: このコマンドを呼び出すプリンシパルは、clouddeploy.releaser IAM ロールまたは同等の権限セットを使用する必要があり、最初のターゲットへのデプロイに使用するサービス アカウントと、レンダリング オペレーションを実行するために使用するサービス アカウントに対する actAs 権限を持っている必要があります。

次のコマンドで新しいリリースが作成され、デリバリー パイプライン インスタンスが呼び出されます。

gcloud deploy releases create RELEASE_NAME \
  --delivery-pipeline=PIPELINE_NAME \
  --region=REGION \
  --annotations=[KEY=VALUE,...] \
  --images=[IMAGE_LIST]

ここで...

• RELEASE_NAME

  は、このリリースに付ける名前です。この値は必須です。

  動的リリース名は、'$DATE' と '$TIME' のいずれか、または両方を含めることで指定できます。たとえば、このコマンドを午後 3 時 7 分（UTC）に呼び出した場合、'rel-$TIME' は rel-1507 として解決されます。'$DATE' と '$TIME' は単一引用符で囲む必要があります。

• PIPELINE_NAME

  は、登録されたデリバリー パイプラインの名前です。この値は必須です。

• REGION

  は、このリリースを作成するリージョンです。ここで指定するリージョンは、最終的にアプリケーションをデプロイするリージョンと同じにする必要はありません。

• [KEY=VALUE,...]

  は、リリースに適用する 1 つ以上のアノテーションのリストです（省略可）。Key-Value ペアの形式で指定します。

  アノテーションを使用して、リリースの出所を追跡できます。たとえば、commitId=0065ca0 などのアノテーションを渡します。リリースのすべてのアノテーションは、リリースに対して list または get を実行すると返され、Google Cloud Console にリリースと一緒に表示されるため、リリースの出所も確認できます。

• [IMAGE_LIST]

  image-name-to-image-path の置換のカンマ区切りリストです。例: --images=image1=path/to/image1:v1@sha256:45db24,image2=path/to/image2:v1@sha256:55xy18。

  この値は、Skaffold ビルド アーティファクト出力ファイルを識別する --build-artifacts を渡す場合は不要です。

  Cloud Deploy でマニフェストがレンダリングされると、レンダリングされていないマニフェストのイメージ名は、レンダリングされたマニフェストの完全なイメージ参照に置き換えられます。つまり、この例の image1 はレンダリングされていないマニフェストにあり、レンダリングされたマニフェストでは path/to/image1:v1@sha256:45db24 に置き換えられます。

直接イメージ参照の使用例

次のコマンドは、ビルド アーティファクト ファイルではなく、イメージ参照を直接渡す、新しいリリースを作成します。

gcloud deploy releases create my-release \
  --delivery-pipeline=web-app \
  --region=us-central1 \
  --images=image1=path/to/image1:v1@sha256:45db24

この例では、my-release はリリース名です。日時に基づいてリリース名を生成する場合は、'$DATE' または 'TIME'、あるいはその両方を含めることができます。時刻は、コマンドを呼び出したマシンの UTC 時間です。'$DATE' と '$TIME' は単一引用符で囲む必要があります。

次に例を示します。

gcloud deploy releases create rel-'$DATE'-'$TIME' \
  --delivery-pipeline=web-app \
  --region=us-central1 \
  --images=image1=path/to/image1:v1@sha256:45db24

この例では、コマンドによって、接頭辞 rel- と日時（rel-20220131-1507 など）が付いたリリース名が生成されます。

リリース名で Git SHA を使用するのも一般的です。このドキュメントの Cloud Build と Docker の例をご覧ください。

ビルド アーティファクトとイメージ

gcloud deploy releases create コマンドでは、イメージ参照のセットまたはビルド アーティファクト ファイル参照のいずれかを渡すことができます。

• --images=[NAME=TAG,...] を使用して 1 つ以上の個々のコンテナ イメージを参照します。

  この値は、イメージのフルパスの置換への個々のイメージ名のコレクションへの参照です。次に例を示します。

  gcloud deploy releases create my-release --images=image1=path/to/image1:v1@sha256:45db24

• --build-artifacts= を使用して、Skaffold ビルド アーティファクト出力ファイルを指定する。

ビルド アーティファクト ファイルを渡す Cloud Build の例

注: Cloud Build トリガーを実行するサービス アカウントは、clouddeploy.releaser IAM ロールまたは同等の権限のセットを使用する必要があります。最初のターゲットにデプロイするには、actAs 権限が必要です。

Docker ビルドの例

次の YAML ファイルは、Docker ビルドイメージの push 用の Cloud Build を示し、最終的に Cloud Deploy リリースを作成します。

この例では、イメージをビルドしてアーティファクト リポジトリに push し、短い commit SHA に基づいてリリース名を指定して、リリースを作成するコマンドを作成します。$COMMIT_SHA 変数に依存しているため、この例は Cloud Build SCM トリガーとして使用する必要があります。

この例では、ソース リポジトリの commit ハッシュと同じ Docker タグにイメージを push します。次に、Docker タグとして同じ commit ハッシュが release-command 引数から参照されます。

steps:
# Build and tag using commit sha
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '.', '-t', 'REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}', '-f', 'Dockerfile']
# Push the container image
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}']
# Create release in Google Cloud Deploy
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args:
    [
      "deploy", "releases", "create", "rel-${SHORT_SHA}",
      "--delivery-pipeline", "PIPELINE_NAME",
      "--region", "us-central1",
      "--annotations", "commitId=${REVISION_ID}",
      "--images", "IMAGE_NAME=REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}"
    ]

この例の最後にあるイメージ名 "--images", "IMAGE_NAME= はレンダリングされたマニフェストで、完全なイメージ参照に置き換えられていることに注意してください。

Skaffold を使用した Cloud Build の構成例

次の YAML ファイルは、リリースを作成する Cloud Deploy の呼び出し（日付に基づくリリース名）を含む Cloud Build ビルド構成の内容です。この例は、ビルドに使用される Skaffold も示しています。

steps:
- name: gcr.io/k8s-skaffold/skaffold
  args:
    - skaffold
    - build
    - '--interactive=false'
    - '--file-output=/workspace/artifacts.json'
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args:
    [
      "deploy", "releases", "create", "rel-${SHORT_SHA}",
      "--delivery-pipeline", "PIPELINE_NAME",
      "--region", "us-central1",
      "--annotations", "commitId=${REVISION_ID}",
      "--build-artifacts", "/workspace/artifacts.json"
    ]

注: この例に含まれている gcloud コマンドでは、リリース名が rel-${SHORT_SHA} として渡されます。この動的な名前付けにより、commit された変更ごとに一意のリリース名が保証されます。

GitHub Actions を Cloud Deploy に接続する

継続的インテグレーションやその他のソフトウェア デリバリー関連のアクティビティに GitHub Actions を使用している場合は、create-cloud-deploy-release GitHub Action を使用して Cloud Deploy に接続して継続的デリバリーを実現できます。

GitLab を Cloud Deploy に接続する

プレビュー

このプロダクトには、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 一般提供前のプロダクトは「現状のまま」ご利用いただけますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

継続的インテグレーションに GitLab を使用する場合は、GitLab Cloud Deploy コンポーネント create-cloud-deploy-release を使用して Cloud Deploy リリースを作成できます。

Google Cloud で GitLab を使用する方法のエンドツーエンドのチュートリアルを試すこともできます。

詳細については、GitLab on Google Cloud の概要をご覧ください。

アノテーションを使用してリリースの出所を追跡する

--annotations= フラグを使用すると、1 つ以上の任意の Key-Value ペアを、このコマンドによって作成されるリリースに適用できます。このフラグを gcloud deploy releases create コマンドに追加します。

たとえば、次の Key-Value ペアを使用して、デプロイするイメージのソースを追跡できます。

次に例を示します。

gcloud deploy releases create web-app-1029rel \
  --delivery-pipeline=web-app \
  --region=us-central1 \
  --annotations=commitId=0065ca0,author=[e-mail] \
  --images=image1=path/to/image1:v1@sha256:45db24

たとえば、値が pull リクエストを指す URL のアノテーションを作成することもできます。詳細については、Cloud Deploy でのラベルとアノテーションの使用をご覧ください。