このページは Cloud Translation API によって翻訳されました。

トラフィック分割、段階的なロールアウト、ロールバックに Cloud Run 関数のリビジョンを使用する

1. はじめに

概要

Cloud Run Function を使用すると、トラフィックを受信するリビジョンと、リビジョンが受信するトラフィックの割合を指定できます。リビジョンを使用すると、前のリビジョンにロールバックしたり、リビジョンを段階的にロールアウトしたり、複数のリビジョン間でトラフィックを分割したりできます。

この Codelab では、リビジョンを使用して Cloud Run 関数へのトラフィックを管理する方法について説明します。リビジョンの詳細については、Cloud Run のドキュメントをご覧ください。

学習内容

Cloud Run 関数の複数のリビジョン間でトラフィックを分割する方法
新しいリビジョンを段階的にロールアウトする方法
以前のリビジョンにロールバックする方法

2. 設定と要件

前提条件

Cloud コンソールにログインしています。
以前に Cloud Run 関数をデプロイしました。たとえば、Cloud Run 関数のデプロイの手順に沿って開始します。

Cloud Shell をアクティブにする

Cloud Console で、[Cloud Shell をアクティブにする] をクリックします。

Cloud Shell を初めて起動する場合、その内容を説明する中間画面が表示されます。中間画面が表示された場合は、[続行] をクリックします。

Cloud Shell のプロビジョニングと接続に少し時間がかかる程度です。

この仮想マシンには、必要な開発ツールがすべて用意されています。5 GB の永続的なホームディレクトリが用意されており、Google Cloud で稼働するため、ネットワークのパフォーマンスと認証が大幅に向上しています。この Codelab での作業のほとんどはブラウザを使って行うことができます。

Cloud Shell に接続すると、認証が完了し、プロジェクトに各自のプロジェクト ID が設定されていることがわかります。

Cloud Shell で次のコマンドを実行して、認証されたことを確認します。

gcloud auth list

コマンド出力

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

コマンド出力

[core]
project = <PROJECT_ID>

上記のようになっていない場合は、次のコマンドで設定できます。

gcloud config set project <PROJECT_ID>

コマンド出力

Updated property [core/project].

3. トラフィック分割

このサンプルでは、色の環境変数を読み取り、その背景色を使用してリビジョン名を返す関数を作成する方法を示します。

この Codelab では node.js を使用しますが、任意のランタイムを使用できます。

環境変数の設定

この Codelab 全体で使用する環境変数を設定できます。

REGION=<YOUR_REGION>
PROJECT_ID=<YOUR-PROJECT-ID>
BG_COLOR=darkseagreen

関数の作成

まず、ソースコードのディレクトリを作成し、そのディレクトリに移動します。

mkdir revisions-gcf-codelab && cd $_

次に、次の内容の package.json ファイルを作成します。

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

次に、次の内容の index.js ソースファイルを作成します。

const functions = require('@google-cloud/functions-framework');

const BG_COLOR = process.env.BG_COLOR;
const K_REVISION = process.env.K_REVISION;

functions.http('helloWorld', (req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<html><body style="background-color:' + BG_COLOR + ';"' + '><div><p>' + 'Hello from ' + K_REVISION + ' using color ' + BG_COLOR + '</p></div></body>' + '</html>');
});

Cloud Run 関数を Cloud Run に直接デプロイするには、次のコマンドを実行します。

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --set-env-vars BG_COLOR=$BG_COLOR

Cloud Functions（第 2 世代）としてデプロイする場合は、次のコマンドを使用します。

gcloud functions deploy traffic-splitting-gcf \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars BG_COLOR=$BG_COLOR

この関数をテストするには、既存のエンドポイントを curl して HTML で darkseagreen 色を確認するか、ブラウザを使用してエンドポイントに直接アクセスして背景色を確認します。

SERVICE_URL=$(gcloud run services describe traffic-splitting-gcf --platform managed --region $REGION --format 'value(status.url)')

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

次に、タン色の背景色の 2 つ目のリビジョンをデプロイします。

Cloud Run 関数を Cloud Run に直接デプロイするには、次のコマンドを実行します。

# update the env var
BG_COLOR=tan

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

Cloud Functions（第 2 世代）としてデプロイする場合は、次のコマンドを使用します。

# update the env var
BG_COLOR=tan

gcloud functions deploy traffic-splitting-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR

これで、エンドポイントを curl すると、茶色の背景色が表示されます。

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

トラフィックを 50% ずつ分割する

ディープシーグリーンとタンのリビジョン間でトラフィックを分割するには、基盤となる Cloud Run サービスのリビジョン ID を見つける必要があります。リビジョン ID を確認するには、次のコマンドを実行します。

gcloud run revisions list --service traffic-splitting-gcf \
  --region $REGION --format 'value(REVISION)'

次のような結果が表示されます。

traffic-splitting-gcf-00003-qoq
traffic-splitting-gcf-00002-zag

次のコマンドを実行して、トラフィックを 50/50 で 2 つのリビジョンに分割できます。

gcloud run services update-traffic traffic-splitting-gcf \
  --region $REGION \
  --to-revisions <REVISION1>=50,<REVISION2>=50

トラフィック分割をテストする

関数をテストするには、公開 URL にアクセスします（curl を使用するか、ブラウザで直接アクセスします）。

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL

半分の時間ではダークシーグリーンリビジョン、もう半分はタンリビジョンが表示されます。また、出力にリビジョン名が表示されます。

<html><body style="background-color:tan;"><div><p>Hello traffic-splitting-gcf-00006-qoq</p></div></body></html>

4. 段階的なロールアウト

このセクションでは、新しい Cloud Functions リビジョンに変更を段階的にロールアウトする方法について説明します。段階的なロールアウトについて詳しくは、こちらのドキュメントをご覧ください。

前のセクションと同じコードを使用しますが、新しい Cloud Functions の関数としてデプロイします。

まず、背景色を beige に設定し、gradual-rollouts-gcf という名前の関数をデプロイします。

Cloud Run 関数を Cloud Run に直接デプロイするには、次のコマンドを実行します。

# update the env var
BG_COLOR=beige

gcloud beta run deploy gradual-rollouts-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

Cloud Functions 第 2 世代としてデプロイする場合は、次のコマンドを使用します。

# update the env var
BG_COLOR=beige

# deploy the function
gcloud functions deploy gradual-rollouts-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR

次に、背景色が Lavender の新しいリビジョンを段階的にロールアウトするとします。

まず、現在のリビジョン（ベージュ）に 100% のトラフィックを受信するように設定します。これにより、今後の Cloud Functions のデプロイでトラフィックが受信されなくなります。デフォルトでは、Cloud Functions は latest フラグを使用して 100% のトラフィックをリビジョンに設定します。この現在のリビジョン beige がすべてのトラフィックを受信するように手動で指定すると、latest フラグを持つリビジョンは 100% のトラフィックを受信しなくなります。詳しくは、こちらのドキュメントをご覧ください。

# get the revision name

BEIGE_REVISION=$(gcloud run revisions list --service gradual-rollouts-gcf \
  --region $REGION --format 'value(REVISION)')

# now set 100% traffic to that revision

gcloud run services update-traffic gradual-rollouts-gcf --to-revisions=$BEIGE_REVISION=100 --region $REGION

Traffic: 100% gradual-rollouts-gcf2-00001-yox のような出力が表示されます。

これで、トラフィックを受信しない新しいリビジョンをデプロイできるようになりました。コードを変更する代わりに、このリビジョンの BG_COLOR 環境変数を更新できます。

Cloud Run 関数を Cloud Run に直接デプロイするには、次のコマンドを実行します。

# update color

BG_COLOR=lavender

# deploy the function that will not receive any traffic
gcloud beta run deploy gradual-rollouts-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

Cloud Functions（第 2 世代）としてデプロイする場合は、次のコマンドを使用します。

# update color

BG_COLOR=lavender

# deploy the function that will not receive any traffic
gcloud functions deploy gradual-rollouts-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR \
  --tag $BG_COLOR

次に、gradual-rollouts-gcf 関数を使用するように SERVICE_URL 環境変数を更新します。

SERVICE_URL=$(gcloud run services describe gradual-rollouts-gcf --platform managed --region $REGION --format 'value(status.url)')

サービスに対して curl を実行すると、

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

ラベンダーが最後にデプロイされたリビジョンであっても、ベージュ色が表示されます。

<html><body style="background-color:beige;"><div><p>Hello from gradual-rollouts-gcf-24jan16-staging-2-00001-kop using color beige</p></div></body></html>

0% のトラフィックを処理するリビジョンをテストする

リビジョンが正常にデプロイされ、トラフィックを 0% 処理していることを確認したとします。ヘルスチェックに合格しても、このリビジョンの背景色がラベンダー色であることを確認する必要があります。

Lavender リビジョンをテストするには、そのリビジョンにタグを適用します。タグを使用すると、トラフィックを処理することなく、特定の URL で新しいリビジョンを直接テストできます。

まず、そのリビジョンの画像 URL を取得します。

IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')

次に、その画像に関連する色のタグを付けます。

gcloud run deploy gradual-rollouts-gcf --image $IMAGE_URL --no-traffic --tag $BG_COLOR --region $REGION --no-allow-unauthenticated

出力は次のようになります。

The revision can be reached directly at https://lavender---gradual-rollouts-gcf-k6msmyp47q-lz.a.run.app

これで、このリビジョンを直接 curl できます

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>

結果でラベンダー色を確認します。

<html><body style="background-color:lavender;"><div><p>Hello from gradual-rollouts-gcf-24jan16-00003-xik using color lavender</p></div></body></html>

トラフィックが徐々に増加

これで、Lavender リビジョンへのトラフィックの送信を開始できます。次の例は、トラフィックの 1% を lavender に送信する方法を示しています。

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=1

トラフィックの 50% を lavender に送信するには、同じコマンドを使用しますが、代わりに 50% を指定します。

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=50

各リビジョンが受信しているトラフィックの量のリストが表示されます。

Traffic:
  50% gradual-rollouts-gcf-00001-hos
  50% gradual-rollouts-gcf-00004-mum
        lavender: https://lavender---gradual-rollouts-gcf-k6msmyp47q-uc.a.run.app

ラベンダーを完全にロールアウトする準備ができたら、ラベンダーを 100% に設定してベージュに置き換えることができます。

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100

gradual-rollouts-gcf 関数のサービス URL にアクセスし、

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

ラベンダーしか見えません。

<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>

5. ロールバック

初期の UX フィードバックが届き、ユーザーがラベンダーよりもベージュを好んでいることが判明し、ベージュにロールバックする必要がある場合を考えてみましょう。

このコマンドを実行すると、前のリビジョン（ベージュ）にロールバックできます。

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-revisions $BEIGE_REVISION=100

これで、curl を実行するか、関数の URL エンドポイントにアクセスすると、

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

返された値はベージュになります。

<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>

ロールバックの詳細については、ドキュメントをご覧ください。

6. 完了

以上で、この Codelab は完了です。

ロールアウト、ロールバック、トラフィックの移行に関するドキュメントを確認することをおすすめします。

学習した内容

Cloud Run 関数の 2 つ以上のリビジョン間でトラフィックを分割する方法
新しいリビジョンを段階的にロールアウトする方法
以前のリビジョンにロールバックする方法

7. クリーンアップ

不注意による料金の発生（たとえば、この Cloud Run 関数が無料枠の毎月の Cloud Functions 呼び出しの割り当てよりも頻繁に呼び出された場合）を避けるために、Cloud Run 関数を削除するか、ステップ 2 で作成したプロジェクトを削除します。

Cloud Run にデプロイされた Cloud Run 関数を削除するには、Cloud コンソールの Cloud Run（https://console.cloud.google.com/functions/）に移動し、この Codelab で作成した関数を削除します。

第 2 世代の関数としてデプロイされた Cloud Run 関数を削除するには、Cloud コンソールの Cloud Functions（https://console.cloud.google.com/functions/）に移動し、この Codelab で作成した関数を削除します。

プロジェクト全体を削除する場合は、https://console.cloud.google.com/cloud-resource-manager に移動し、ステップ 2 で作成したプロジェクトを選択して、[削除] を選択します。プロジェクトを削除する場合は、Cloud SDK でプロジェクトを変更する必要があります。使用可能なすべてのプロジェクトのリストを表示するには、gcloud projects list を実行します。