イメージの事前ウォーミングでレイテンシを短縮する

イメージの事前ウォーミングを行うと、ランタイム クライアントがコンテナ イメージをリクエストする前に、イメージ ストリーミング キャッシュへのコンテナ イメージのダウンロードを明示的にトリガーできます。 これにより、イメージ ストリーミングを使用するワークロードの新しいイメージ バージョンの最初の pull に関連する「コールド スタート」レイテンシが効果的に解消されます。

概要

イメージを Artifact Registry に push すると、基盤となるストレージ システムに保存されます。レイテンシの短いアクセスを実現するため、Artifact Registry は イメージ ストリーミング キャッシュも使用します。通常、このキャッシュは、イメージ ストリーミングが有効になっているクライアントからの最初の pull で入力されます。Google Kubernetes Engine クラスタのスケーリングなど、レイテンシの影響を受けやすいワークロードの場合、このキャッシュがウォームアップするまで待機すると遅延が発生する可能性があります。 事前ウォーミングは、イメージをイメージ ストリーミング キャッシュに事前に取り込むのに役立ちます。

Prewarm Artifact API を使用すると、特定のイメージ バージョンまたはタグを事前にキャッシュに保存するように手動でリクエストできます。また、イメージが指定された期間キャッシュに残るように保持期間を指定することもできます。

制限事項

  • API のみ: 事前ウォーミングは Artifact Registry REST API を使用してのみ利用できます。 gcloud CLI または Google Cloud コンソールを使用して事前ウォーミングを行うことはできません。
  • GKE のみ: 事前ウォーミングは、 イメージ ストリーミング が有効になっている GKE クラスタでのみ有効です。イメージ ストリーミングには、クライアント ノードで実行される特定のソフトウェアが必要です。
  • 単一アーティファクト: API リクエストごとに事前ウォーミングできるアーティファクトは 1 つ（バージョンまたはタグ）のみです。
  • マルチ アーキテクチャ イメージ: 対象外です。アーキテクチャ イメージには特定のバージョンを使用してください。

始める前に

  1. Artifact Registry API を有効にします。詳細については、Artifact Registry を有効にするをご覧ください。
  2. gcloud CLI をインストールして、REST API リクエストの認証トークンを取得します。

必要なロール

事前ウォーミングされたイメージの管理に必要な権限を取得するには、リポジトリに対する次の IAM ロールの付与を管理者に依頼してください。

  • キャッシュからアーティファクトを事前ウォーミングまたは削除する（artifactregistry.repositories.prewarmArtifact、artifactregistry.repositories.removePrewarmedArtifact）: Artifact Registry 書き込み （roles/artifactregistry.writer）
  • 事前ウォーミングされたアーティファクトを確認または一覧表示する（artifactregistry.repositories.checkPrewarmedArtifact、artifactregistry.repositories.listPrewarmedArtifacts）: Artifact Registry 読み取り （roles/artifactregistry.reader）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタム ロールや他の事前定義 ロールから取得することもできます。

この権限モデルにより、書き込みアクセス権を持つユーザーのみがキャッシュの状態を管理できるため、承認されていないユーザーがキャッシュをオーバーフローさせるのを防ぐことができます。 一方、読み取りアクセス権を持つユーザーは、ストリーミングに使用できるアーティファクトを確認できます。

イメージを事前ウォーミングする

イメージを事前ウォーミングするには、リポジトリの :prewarmArtifact メソッドに POST リクエストを送信します。

REST API

参照: projects.locations.repositories.prewarmArtifact

リクエストの本文は以下の構造になります。

{
  "version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION",
  "retention_days": 3
}

または、タグを使用します。

{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
フィールド 説明
tag （省略可）事前ウォーミングする特定のアーティファクト タグ。version または tag のいずれかを指定する必要があります。
version （省略可）事前ウォーミングする特定のアーティファクト バージョン。version または tag のいずれかを指定する必要があります。
retention_days （省略可）アーティファクトをキャッシュに保持する日数。このフィールドを指定しない場合、デフォルトは 3 日です。
force （省略可）true の場合、このアーティファクトのスペースを確保するために、古いアーティファクトが削除されることがあります。

例: 特定のバージョンを事前ウォーミングする

次の例では、my-repo リポジトリの nginx パッケージのバージョン sha256:52e... を事前ウォーミングします。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "retention_days": 7
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

例: タグを事前ウォーミングする

次の例では、my-app パッケージの production というタグが付いたイメージを事前ウォーミングします。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "projects/my-project/locations/us-central1/repositories/my-repo/packages/my-app/tags/production",
    "force": true
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

事前ウォーミングのステータスを確認する

アーティファクトが事前ウォーミングされているかどうかを確認するには、:checkPrewarmedArtifact メソッドを使用します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"

事前ウォーミングされたアーティファクトを一覧表示する

リポジトリ内の事前ウォーミングされたアーティファクトをすべて一覧表示するには、prewarmedArtifacts コレクションで GET メソッドを使用します。

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo/prewarmedArtifacts"

キャッシュから削除する

事前ウォーミング キャッシュからアーティファクトを明示的に削除するには、:removePrewarmedArtifact メソッドを使用します。このメソッドは、スペースを解放する場合や、特定のイメージ バージョンがキャッシュに不要になった場合に使用します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:removePrewarmedArtifact"

次のステップ