1. はじめに
概要
Cloud Run functions では、トラフィックを受信するリビジョンと、リビジョンが受信するトラフィックの割合を指定できます。リビジョンを使用すると、以前のリビジョンへのロールバック、リビジョンの段階的なロールアウト、複数のリビジョン間でのトラフィックの分割が可能になります。
この Codelab では、リビジョンを使用して Cloud Run functions へのトラフィックを管理する方法について説明します。リビジョンの詳細については、Cloud Run のドキュメントをご覧ください。
学習内容
- Cloud Run functions の 2 つ以上のリビジョン間でトラフィックを分割する方法
- 新しいリビジョンを段階的にロールアウトする方法
- 以前のリビジョンにロールバックする方法
2. 設定と要件
前提条件
- Cloud コンソールにログインしていること。
- Cloud Run functions の関数をデプロイ済みであること。たとえば、Cloud Run functions の関数をデプロイするに沿って作業を開始できます。
Cloud Shell をアクティブにする
- Cloud Console で、[Cloud Shell をアクティブにする ] をクリックします
。
Cloud Shell を初めて起動した場合は、その内容を説明する画面が表示されます。その場合は、[続行] をクリックしてください。
すぐにプロビジョニングが実行され、Cloud Shell に接続されます。
この仮想マシンには、必要な開発ツールがすべて用意されています。仮想マシンは Google Cloud で稼働し、永続的なホーム ディレクトリが 5 GB 用意されているため、ネットワークのパフォーマンスと認証が大幅に向上しています。 この 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 functions を 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
次に、背景色が tan の 2 つ目のリビジョンをデプロイします。
Cloud Run functions を 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 を実行すると、背景色が tan になります。
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
トラフィックを 50 対 50 に分割する
deep sea green リビジョンと tan リビジョン間でトラフィックを分割するには、基盤となる 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
次のコマンドを実行すると、2 つのリビジョン間でトラフィックを 50 対 50 に分割できます。
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
半分は dark sea green リビジョン、もう半分は tan リビジョンが表示されます。出力にはリビジョン名も表示されます（例:）。
<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 functions を 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 の新しいリビジョンを段階的にロールアウトするとします。
まず、現在のリビジョン beige が 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 functions を 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
次に、SERVICE_URL 環境変数を更新して gradual-rollouts-gcf 関数を使用します。
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
lavender が最後にデプロイされたリビジョンであっても、beige 色が表示されます。
<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 の背景色が使用されていることを確認する必要があります。
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>
結果に lavender 色が表示されます。
<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
lavender を完全にロールアウトする準備ができたら、lavender を 100% に設定して beige を置き換えます。
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100
gradual-rollouts-gcf 関数のサービス URL にアクセスするか、curl を実行すると、
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
lavender のみが表示されます。
<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>
5. ロールバック
初期の UX フィードバックで、お客様が lavender よりも beige を好んでいることが判明し、beige にロールバックする必要があるとします。
このコマンドを実行すると、以前のリビジョン（beige）にロールバックできます。
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-revisions $BEIGE_REVISION=100
関数の URL エンドポイントに対して curl を実行するか、アクセスすると、
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
beige が返されます。
<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>
ロールバックの詳細については、ドキュメントをご覧ください。
6. 完了
以上で、この Codelab は完了です。
ロールアウト、ロールバック、トラフィック移行に関するドキュメントを確認することをおすすめします。
学習した内容
- Cloud Run functions の 2 つ以上のリビジョン間でトラフィックを分割する方法
- 新しいリビジョンを段階的にロールアウトする方法
- 以前のリビジョンにロールバックする方法
7. クリーンアップ
意図しない料金が発生しないように（たとえば、この Cloud Run functions が無料枠の月間 Cloud Functions 呼び出し割り当てよりも多く呼び出された場合）、Cloud Run functions を削除するか、ステップ 2 で作成したプロジェクトを削除します。
Cloud Run にデプロイされた Cloud Run functions を削除するには、Cloud コンソールの Cloud Run（https://console.cloud.google.com/functions/）に移動し、この Codelab で作成した関数を削除します。
第 2 世代関数としてデプロイされた Cloud Run functions を削除するには、Cloud コンソールの Cloud Functions（https://console.cloud.google.com/functions/）に移動し、この Codelab で作成した関数を削除します。
プロジェクト全体を削除する場合は、https://console.cloud.google.com/cloud-resource-manager に移動し、ステップ 2 で作成したプロジェクトを選択して [削除] を選択します。プロジェクトを削除する場合は、Cloud SDK でプロジェクトを変更する必要があります。gcloud projects list を実行すると、使用可能なすべてのプロジェクトのリストが表示されます。