1. はじめに
概要
Cloud Run Function を使用すると、トラフィックを受信するリビジョンと、リビジョンが受信するトラフィックの割合を指定できます。リビジョンを使用すると、前のリビジョンにロールバックしたり、リビジョンを段階的にロールアウトしたり、複数のリビジョン間でトラフィックを分割したりできます。
この Codelab では、リビジョンを使用して Cloud Run 関数へのトラフィックを管理する方法について説明します。リビジョンの詳細については、Cloud Run のドキュメントをご覧ください。
学習内容
- Cloud Run 関数の 2 つ以上のリビジョン間でトラフィックを分割する方法
- 新しいリビジョンを段階的にロールアウトする方法
- 以前のリビジョンにロールバックする方法
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 対 50 で分割
トラフィックをディープ シーグリーンと 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
次のコマンドを実行して、トラフィックを 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% のトラフィックをリビジョンに設定します。この現在のリビジョン（ベージュ）がすべてのトラフィックを受信するように手動で指定すると、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 を実行すると、
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 を実行すると、使用可能なすべてのプロジェクトのリストが表示されます。