イメージストリーミングを使用してコンテナイメージを pull する

Autopilot Standard

このページでは、Google Kubernetes Engine（GKE）でイメージストリーミングを使用して、アプリケーションのニーズに応じてイメージデータをストリーミングし、コンテナイメージを pull する方法を説明します。

GKE バージョン 1.25.5-gke.1000 以降を実行する新しい Autopilot クラスタは、イメージストリーミングを使用して自動的に対象イメージを pull します。このページの手順は Standard クラスタにのみ適用されます。

概要

イメージストリーミングはコンテナイメージを取得する方法で、GKE はアプリケーションからのリクエストに応じて対象イメージからデータをストリーミングします。イメージストリーミングを使用すると、イメージ全体がダウンロードされるのを待たずにワークロードを初期化できます。これにより、初期化時間を大幅に短縮できます。pull 時間の短縮には、次のような利点があります。

自動スケーリングの高速化
大きなイメージを pull する際のレイテンシの短縮
Pod の起動の高速化

イメージストリーミングでは、GKE は、対象となるコンテナイメージを使用するコンテナのルートファイルシステムとしてリモートファイルシステムを使用します。ワークロードで必要になると、リモートファイルシステムからイメージデータをストリーミングします。イメージストリーミングを使用しない場合、GKE はコンテナイメージ全体を各ノードにダウンロードし、ワークロードのルートファイルシステムとして使用します。

イメージデータをストリーミングしながら、バックグラウンドでコンテナイメージ全体をローカルディスクにダウンロードし、キャッシュに保存します。その後はキャッシュに保存されたイメージからデータ読み取りリクエストを送信します。

コンテナイメージ内の特定のファイルを読み取る必要があるワークロードをデプロイすると、イメージストリーミングバックエンドはリクエストされたファイルのみを提供します。

要件

GKE Autopilot クラスタと GKE Standard クラスタでイメージストリーミングを使用するには、次の要件を満たす必要があります。

Container File System API を有効にする必要があります。

Container File System API を有効にする
イメージストリーミングを自動的に有効にするには、新しい Autopilot クラスタで GKE バージョン 1.25.5-gke.1000 以降を実行する必要があります。手順については、新しい Autopilot クラスタのバージョンとリリースチャンネルを設定するをご覧ください。
新規および既存の GKE Standard クラスタでは、バージョン 1.18.6-gke.4801 以降を実行する必要があります。
コンテナ化されたノードイメージで、Container-Optimized OS を使用する必要があります。Autopilot ノードは常にこのノードイメージを使用します。
コンテナイメージは Artifact Registry に保存する必要があります。
Artifact Registry リポジトリは、GKE ノードと同じリージョンか、ノードを実行しているリージョンに対応するマルチリージョンに存在する必要があります。例:
- ノードが us-east1 にある場合、GKE と Artifact Registry の両方が米国内のデータセンターロケーションで実行されているため、us-east1 リージョンまたは us マルチリージョンのリポジトリでイメージストリーミングを使用できます。
- ノードが northamerica-northeast1 リージョンにある場合、ノードはカナダで実行されます。この場合、イメージストリーミングを使用できるのは、同じリージョンのリポジトリだけです。
クラスタでプライベートノードを有効にしている場合、ノードがイメージストリーミングサービスにアクセスするには、サブネットでプライベート Google アクセスを有効にする必要があります。
VPC Service Controls がコンテナイメージを保護する場合、イメージストリーミングを使用するには、サービス境界に Image Streaming API（containerfilesystem.googleapis.com）も含める必要があります。
クラスタ内の GKE ノードがデフォルトのサービスアカウントを使用していない場合は、カスタムサービスアカウントにコンテナイメージをホストするプロジェクトの Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）IAM ロールが付与されていることを確認する必要があります。

制限事項

1.23.5-gke.1900 より前の GKE バージョンでは、Secret を使用してコンテナイメージを pull することはできません。
V2 イメージマニフェスト、スキーマバージョン 1 を使用するコンテナイメージは対象外です。
顧客管理の暗号鍵（CMEK）で暗号化されたコンテナイメージは、GKE バージョン 1.25.3-gke.1000 以降のイメージストリーミングの対象になります。以前のバージョンの GKE では、データをストリーミングせずにこれらのイメージをダウンロードします。引き続き CMEK を使用して、イメージストリーミングを使用するクラスタ内のアタッチされた永続ディスクとカスタムブートディスクを保護できます。
重複するレイヤを含むコンテナイメージはサポートされていません。GKE は、データをストリーミングせずにこれらのイメージをダウンロードします。コンテナイメージに空のレイヤまたは重複するレイヤがないか確認します。
初期化中にワークロードがイメージ内の複数のファイルを読み取る場合、リモートファイルの読み取りによってレイテンシが増加し、初期化時間が長くなることがあります。
対象イメージを初めて pull する場合は、イメージストリーミングの利点に気づかない可能性があります。ただし、イメージストリーミングでイメージがキャッシュに保存された後は、どのクラスタでもイメージの pull でイメージストリーミングの利点を実感できます。
GKE Standard クラスタは、クラスタレベルの構成を使用して、ノードの自動プロビジョニングで作成された新しいノードプールでイメージストリーミングを有効にするかどうかを決定します。ただし、クラスタレベルでイメージストリーミングが無効になっている場合、ワークロードの分離を使用して、イメージストリーミングを有効にしたノードプールを作成することはできません。
CAP_NET_RAW などの Linux ファイル機能は、GKE バージョン 1.22.6-gke.300 以降のイメージストリーミングでサポートされています。以前の GKE バージョンでは、イメージファイルのストリーミング時、またはローカルディスクへのイメージの保存時に、これらの機能は使用できません。サービスの中断を回避するため、1.22.6-gke.300 より前の GKE バージョンでは、これらの機能が適用されているコンテナにイメージストリーミングを使用しないでください。コンテナが Linux ファイル機能に依存している場合、イメージストリーミングを有効にして実行すると、権限拒否エラーにより起動が失敗する可能性があります。

始める前に

開始にあたり、次の作業が完了していることを確認してください。

Google Kubernetes Engine API を有効にする。

Google Kubernetes Engine API の有効化

このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。
注: gcloud CLI がすでにインストールされている場合には、必ず compute/region と compute/zone のプロパティを設定してください。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。

Container File System API を有効にします。

Container File System API を有効にする

クラスタでイメージストリーミングを有効にする

新規または既存の Standard クラスタでイメージストリーミングを有効にするには、gcloud CLI の --enable-image-streaming フラグを使用するか、Google Cloud コンソールを使用します。デフォルトでは、クラスタ内のノードプールはクラスタレベルでイメージストリーミングの設定を継承します。この動作を変更するには、クラスタ内のノードプールでイメージストリーミングを有効または無効にします。

GKE バージョン 1.25.5-gke.1000 以降を実行するすべての新しい Autopilot クラスタは、イメージストリーミングを使用して対象イメージを pull します。手順については、新しい Autopilot クラスタのバージョンとリリースチャンネルを設定するをご覧ください。次の手順は、GKE Standard クラスタにのみ適用されます。

新しいクラスタの場合

新しいクラスタでイメージストリーミングを有効にするには、gcloud CLI か Google Cloud コンソールを使用します。

gcloud

イメージストリーミングを有効にして新しいクラスタを作成するには、次のコマンドを実行します。

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

次のように置き換えます。

CLUSTER_NAME: 新しいクラスタの名前。
CONTROL_PLANE_LOCATION: クラスタのコントロールプレーンの Compute Engine のロケーション。リージョンクラスタの場合はリージョン、ゾーンクラスタの場合はゾーンを指定します。リージョンまたはゾーンが同じリージョンにあるか、イメージを含む Artifact Registry リポジトリのマルチリージョンにあることを確認します。

コンソール

Google Cloud コンソールで、[Kubernetes クラスタを作成する] ページに移動します。
[Kubernetes クラスタを作成する] に移動
ナビゲーションパネルの [クラスタ] の下の [機能] をクリックします。
[その他] セクションで、[イメージストリーミングを有効にする] チェックボックスをオンにします。
必要に応じてクラスタを構成し、[作成] をクリックします。

既存クラスタの場合

gcloud CLI または Google Cloud コンソールを使用して、要件を満たす既存のクラスタでイメージストリーミングを有効にできます。

gcloud

イメージストリーミングを使用するように既存のクラスタを更新するには、gcloud CLI を使用して次のコマンドを実行します。

gcloud container clusters update CLUSTER_NAME \
    --enable-image-streaming

コンソール

Google Cloud コンソールで [Google Kubernetes Engine] ページに移動します。

Google Kubernetes Engine に移動
変更するクラスタの名前をクリックします。
[クラスタ] ページの [機能] セクションで、[イメージストリーミング] の横にあるをクリックします。
[イメージストリーミングの編集] ダイアログボックスで、[イメージストリーミングを有効にする] チェックボックスをオンにします。
[保存] をクリックします。

クラスタを変更すると、GKE はデフォルトで既存のノードプールのイメージストリーミングを自動的に有効にします。個々のノードプールでイメージストリーミングを明示的に有効または無効にした場合、それらのノードプールはクラスタレベルの設定に対する変更を継承しません。

イメージストリーミングの設定を変更する場合、クラスタレベルで更新するとメンテナンスの可用性が考慮されますが、ノードプールレベルでは考慮されません。

この変更を行うにはノードの再作成が必要になり、実行中のワークロードが中断する可能性があります。この変更の詳細については、ノードアップグレード戦略とメンテナンスポリシーに従ってノードを再作成する手動変更の表で対応する行をご覧ください。ノードの更新の詳細については、ノードの更新による中断の計画をご覧ください。

クラスタでイメージストリーミングが有効になっていることを確認する

クラスタレベルでイメージストリーミングが有効になっているかどうかを確認するには、gcloud CLI または Google Cloud コンソールを使用します。

gcloud

次のコマンドを実行します。

gcloud container clusters describe CLUSTER_NAME \
    --flatten "nodePoolDefaults.nodeConfigDefaults"

出力が次のようになっている場合、設定は有効になっています。

gcfsConfig:
  enabled: true
...

出力が次のようになっている場合、設定は無効になっています。

gcfsConfig: {}
...

コンソール

Google Cloud コンソールで [Google Kubernetes Engine] ページに移動します。

Google Kubernetes Engine に移動
確認するクラスタの名前をクリックします。
[クラスタ] ページの [機能] セクションにある [イメージストリーミング] の横に、設定が有効になっているかどうかが表示されます。

ノードプールでイメージストリーミングを有効にする

デフォルトでは、ノードプールはクラスタレベルでイメージストリーミングの設定を継承します。特定のノードプールでイメージストリーミングを有効または無効にするには、gcloud CLI を使用します。

新しいノードプールの場合

イメージストリーミングを有効にして新しいノードプールを作成するには、次のコマンドを実行します。

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

次のように置き換えます。

NODE_POOL_NAME: 新しいノードプールの名前。
CLUSTER_NAME: ノードプールのクラスタの名前。
CONTROL_PLANE_LOCATION: クラスタのコントロールプレーンの Compute Engine のロケーション。リージョンクラスタの場合はリージョン、ゾーンクラスタの場合はゾーンを指定します。

既存のノードプールの場合

要件を満たす既存のノードプールでイメージストリーミングを有効にできます。

イメージストリーミングを使用するように既存のノードプールを更新するには、次のコマンドを実行します。

gcloud container node-pools update POOL_NAME \
    --cluster=CLUSTER_NAME \
    --enable-image-streaming

この変更を行うにはノードの再作成が必要になり、実行中のワークロードが中断する可能性があります。この変更の詳細については、メンテナンスポリシーを遵守せずにノードアップグレード戦略に従ってノードを再作成する手動変更の表で対応する行をご覧ください。ノードの更新の詳細については、ノードの更新による中断の計画をご覧ください。

ノードプールでイメージストリーミングが有効になっていることを確認する

ノードプールでイメージストリーミングが有効になっていることを確認します。

gcloud container node-pools describe POOL_NAME \
    --cluster=CLUSTER_NAME \

出力が次のようになっている場合、設定は有効になっています。

gcfsConfig:
  enabled: true
...

出力が次のようになっている場合、設定は無効になっています。

gcfsConfig: {}
...

イメージストリーミングを使用してワークロードをスケジュールする

クラスタでイメージストリーミングを有効にすると、GKE は Artifact Registry から有効なコンテナイメージを pull するときに自動的にイメージストリーミングを使用します。追加の構成を行う必要はありません。

イメージストリーミングが有効になっているノードプールのノードには cloud.google.com/gke-image-streaming: "true" ラベルが追加されます。GKE Standard では、特定のノードプールでイメージストリーミングを有効または無効にして、イメージストリーミングを使用するノードと使用しないノードが混在する場合は、Deployment でノードセレクタを使用して、イメージストリーミングを使用するノードで GKE がワークロードをスケジュールするかどうかを制御できます。

次の例では、イメージストリーミングが有効になっているクラスタで、大きなコンテナイメージを使用する Deployment をスケジュールします。後で、イメージストリーミングを有効にせずにイメージを pull する場合とパフォーマンスを比較します。

イメージストリーミングを有効にして新しいクラスタを作成します。

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-image-streaming \
    --image-type="COS_CONTAINERD"

クラスタの認証情報を取得します。

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

次のマニフェストを frontend-deployment.yaml として保存します。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 1
  selector:
    matchLabels:
      app: guestbook
      tier: frontend
  template:
    metadata:
      labels:
        app: guestbook
        tier: frontend
    spec:
      containers:
      - name: php-redis
        image: us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5
        env:
        - name: GET_HOSTS_FROM
          value: "dns"
        resources:
          requests:
            cpu: 100m
            memory: 100Mi
        ports:
        - containerPort: 80

gb-frontend コンテナイメージのサイズは 327 MB です。

マニフェストをクラスタに適用します。
```
kubectl apply -f frontend-deployment.yaml
```

GKE が Deployment を作成したことを確認します。

kubectl get pods -l app=guestbook

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

NAMESPACE    NAME                          READY    STATUS       RESTARTS    AGE
default      frontend-64bcc69c4b-pgzgm     1/1      Completed    0           3s

Kubernetes のイベントログを取得して、イメージの pull イベントを確認します。
```
kubectl get events --all-namespaces
```
出力は次のようになります。
```
NAMESPACE  LAST SEEN  TYPE    REASON          OBJECT                                                 MESSAGE
default    11m        Normal  Pulling         pod/frontend-64bcc69c4b-pgzgm                          Pulling image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5"
default    11m        Normal  Pulled          pod/frontend-64bcc69c4b-pgzgm                          Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 1.536908032s
default    11m        Normal  ImageStreaming  node/gke-riptide-cluster-default-pool-f1552ec4-0pjv    Image us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5 is backed by image streaming.
...
```
この出力で:
- Pulled イベントは、イメージストリーミングによるイメージの pull にかかった時間を示しています。
- ImageStreaming イベントは、ノードがイメージストリーミングを使用してコンテナイメージを提供していることを示しています。
  
  注: 1.20.9-gke.1000 より前の GKE バージョンを実行しているクラスタでは、Reason フィールドに ImageStreaming ではなく BackedByGCFS が表示されます。BackedByGCFS は、イメージがイメージストリーミングを使用していることも示しています。
  注: 同じノードで同じイメージを使用するワークロードを実行する場合、GKE はイメージのストリーミングではなく、イメージのローカルキャッシュを使用します。Pod Pulled イベントの Message フィールドに Container image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" already present on machine が表示されます。イメージストリーミングのパフォーマンスを再度テストするには、ノードを削除して新しいノードを作成します。

標準的なイメージの pull とパフォーマンスを比較する

この例では、イメージストリーミングを無効にして新しいクラスタを作成し、frontend Deployment をデプロイしてイメージストリーミングのパフォーマンスを比較します。

イメージストリーミングを無効にして新しいクラスタを作成します。
```
gcloud container clusters create CLUSTER2_NAME\
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD"
```
注: デフォルトでは、GKE はイメージストリーミングを無効にしてクラスタを作成します。

クラスタの認証情報を取得します。

gcloud container clusters get-credentials CLUSTER2_NAME \
    --location=CONTROL_PLANE_LOCATION

上記の例の frontend Deployment をデプロイします。
```
kubectl apply -f frontend-deployment.yaml
```
Kubernetes イベントログを取得します。
```
kubectl get events --all-namespaces
```
出力は次のようになります。
```
 NAMESPACE  LAST SEEN  TYPE    REASON     OBJECT                             MESSAGE
 default    87s        Normal  Pulled     pod/frontend-64bcc69c4b-qwmfp      Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 23.929723476s
```
GKE がイメージ全体を pull するまでにかかった時間に注目してください。この出力例では、24 秒ほどかかっています。イメージストリーミングを有効にすると、GKE はワークロードの開始に必要なイメージデータを pull するのに 1.5 秒しかかかりません。

クリーンアップ

料金が発生しないようにするには、上記の例で作成したクラスタを削除します。

gcloud container clusters delete CLUSTER_NAME CLUSTER2_NAME

イメージストリーミングを無効にする

GKE Autopilot を使用する場合、個々のクラスタでイメージストリーミングを無効にすることはできません。Container File System API を無効にすると、プロジェクト全体でイメージストリーミングが無効になります。

GKE Standard クラスタを使用する場合は、以降のセクションで説明するように、個々のクラスタまたは特定のノードプールでイメージストリーミングを無効にできます。

GKE Standard クラスタでイメージストリーミングを無効にする

既存の GKE Standard クラスタでイメージストリーミングを無効にするには、gcloud CLI またはGoogle Cloud コンソールを使用します。

gcloud

既存のクラスタでイメージストリーミングを無効にするには、次のコマンドを実行します。

gcloud container clusters update CLUSTER_NAME \
    --no-enable-image-streaming

コンソール

Google Cloud コンソールで [Google Kubernetes Engine] ページに移動します。

Google Kubernetes Engine に移動
変更するクラスタの名前をクリックします。
[クラスタ] ページの [機能] で、[イメージストリーミング] の横にあるをクリックします。
[イメージストリーミングの編集] ダイアログボックスで、[イメージストリーミングを有効にする] チェックボックスをオフにします。
[変更を保存] をクリックします。

新しいノードプールの場合

新しいノードプールを作成するときにイメージストリーミングを無効にするには、次のようなコマンドで --no-enable-image-streaming フラグを指定します。

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-image-streaming

既存のノードプールの場合

既存のノードプールでイメージストリーミングを無効にするには、次のコマンドを実行します。

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --no-enable-image-streaming

イメージストリーミングのメモリ予約

GKE は、ノードシステムコンポーネントの実行用に予約されているメモリに加えて、イメージストリーミング用のメモリリソースを予約します。イメージストリーミング用に追加の CPU リソースは予約しません。GKE Standard クラスタでは、この予約により、Pod でリクエストできるメモリリソースが変更されます。GKE Autopilot では、GKE がシステム割り当てを管理するため、ワークロードのスケジューリングには影響しません。

GKE がノードコンポーネント用に行うメモリ予約の詳細については、Standard クラスタのアーキテクチャをご覧ください。

イメージストリーミングを使用するノードでは、GKE は新しい予約用に次の追加メモリを予約します。

メモリが 1 GiB 未満のマシンの場合は追加メモリなし
最初の 4 GiB のメモリの 1%
次の 4 GiB のメモリの 0.8%（最大 8 GiB）
次の 8 GiB のメモリの 0.4%（最大 16 GB）
次の 112 GiB のメモリの 0.24%（最大 128 GiB）
128 GiB を超えるメモリの 0.08%

トラブルシューティング

以降のセクションでは、イメージストリーミングのトラブルシューティングに関するアドバイスを紹介します。標準的なイメージの pull のトラブルシューティングについては、イメージの pull のトラブルシューティングをご覧ください。

GKE がイメージストリーミングファイルシステムを使用しない

GKE イベントログにイメージストリーミングイベントがない場合は、イメージがリモートファイルシステムでバックアップされていません。GKE が以前にイメージをノードで pull していた場合、以降の pull でイメージストリーミングではなく、イメージのローカルキャッシュが使用されるため、これは想定された動作です。この状態を確認するには、Pod の Pulled イベントの Message フィールドで Container image IMAGE_NAME already present on machine を探します。

ノードの最初のイメージ pull でイメージストリーミングイベントがない場合は、イメージストリーミングの要件を満たしていることを確認してください。要件を満たしている場合は、イメージストリーミングサービス（gcfsd）のログを確認することで問題を診断できます。

Google Cloud コンソールの [ログエクスプローラ] ページに移動します。

[ログエクスプローラ] に移動
[クエリ] フィールドに次のクエリを指定します。
```
logName="projects/PROJECT_ID/logs/gcfsd"
resource.labels.cluster_name="CLUSTER_NAME"
```
次のように置き換えます。
- PROJECT_ID: プロジェクトの名前。
- CLUSTER_NAME: クラスタの名前。
[クエリを実行] をクリックします。

ログエクスプローラを使用して gcfsd ログを確認することもできます。

Google Cloud コンソールでログエクスプローラに移動します。

[ログエクスプローラ] に移動
[クエリ] フィールドに次のクエリを指定します。
```
logName="projects/PROJECT_ID/logs/gcfsd"
```
PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

PermissionDenied

gcfsd ログに次のようなエラーメッセージが表示される場合、ノードに正しい API スコープがありません。GKE は、イメージストリーミングを使用せずに、ワークロード用のコンテナイメージを pull します。

level=fatal msg="Failed to create a Container File System client: rpc error:
code = PermissionDenied desc = failed to probe endpoint: rpc error: code = PermissionDenied
desc = Request had insufficient authentication scopes."

この問題は、ノードに正しいスコープを設定してイメージストリーミングを使用できるようにすることで解決できます。次のコマンドのように、devstorage.read_only スコープをクラスタまたはノードプールに追加します。

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming \
    --scopes="https://www.googleapis.com/auth/devstorage.read_only"

FailedPrecondition

code = FailedPrecondition というエラーメッセージが表示された場合は、イメージがイメージストリーミングリモートファイルシステムにインポートされていません。

このエラーは、既存のノードプールでイメージストリーミングを使用しようとしたときに発生することがあります。ノードプール内のノードにコンテナイメージがすでに存在する場合、GKE はイメージストリーミングを使用してローカルイメージを取得するのではなく、ローカルにあるイメージを使用します。

この問題を解決するには、次のことを行います。

数分待ってから、ワークロードを再度デプロイします。
新しいノードまたはノードプールを追加し、そのノードでワークロードをスケジュールします。

InvalidArgument

code=InvalidArgument というエラーメッセージが表示された場合は、ワークロードが使用しているコンテナイメージがイメージストリーミングの対象ではありません。イメージが要件を満たしていることを確認します。イメージが Artifact Registry にない場合は、Artifact Registry への移行を試してください。

`backend.FileContent failed`

イメージストリーミングを有効にしてコンテナファイルを読み取ると、次のエラーが表示されることがあります。

level=error msg="backend.FileContent failed" error="rpc error: code = ResourceExhausted desc = Quota exceeded for quota metric 'Content requests per project per region' and limit 'Content requests per project per region per minute per region' of service 'containerfilesystem.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'." layer_id="sha256:1234567890" module=gcfs_backend offset=0 path=etc/passwd size=4096

このエラーは、プロジェクトがリモートコンテナファイルシステムサービスからファイルを読み取るために必要な割り当てを超えたことを示します。この問題を解決するには、次の割り当てを増やします。

1 リージョン、1 分、1 プロジェクトあたりのコンテンツリクエスト数
1 リージョン、1 プロジェクトあたりのコンテンツリクエスト数

GKE によるデータのストリーミングなしでのイメージダウンロード

顧客管理の暗号鍵（CMEK）を使用したコンテナイメージは、GKE バージョン 1.25.3-gke.1000 以降でのみイメージストリーミングの対象になります。重複するレイヤを含むコンテナイメージは、イメージストリーミングの対象になりません。詳細については、制限事項をご覧ください。

空のレイヤまたは重複するレイヤの確認

コンテナイメージに空のレイヤまたは重複するレイヤがあるかどうかを確認するには、次のコマンドを実行します。

docker inspect IMAGE_NAME

IMAGE_NAME は、コンテナイメージの名前に置き換えます。

コマンドの出力で、"Layers" のエントリを確認します。

いずれかのエントリが次の "sha256" 出力と完全に一致する場合、コンテナイメージには空のレイヤがあり、イメージストリーミングの対象になりません。

"Layers": [
  ...
  "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
  ...
]

次の例のような重複するエントリがある場合、コンテナイメージには重複するレイヤがあり、イメージストリーミングの対象になりません。

"Layers": [
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
]

シンボリックリンクファイルで `mv` コマンドと `renameat2` システムの呼び出しが失敗する

バージョン 1.25 以降を実行している GKE ノードでは、イメージストリーミングが有効になっていると、コンテナイメージのシンボリックリンクファイルで mv コマンドと renameat2 システムの呼び出しが行えず、「デバイスまたはアドレスがありません」というエラーメッセージが返される場合があります。この問題は、最近の Linux カーネルの回帰が原因で発生します。

これらのシステム呼び出しは一般的ではないため、大部分のイメージはこの問題の影響を受けません。通常、この問題は、アプリケーションの実行とファイル移動の準備ができているコンテナの初期化ステージで発生します。イメージをローカルでテストすることはできないため、テスト環境でイメージストリーミングを使用して、本番環境でイメージを使用する前に問題を見つけることをおすすめします。

この修正は、次の GKE パッチバージョンで入手できます。

1.25: 1.25.14-gke.1351000 以降
1.26: 1.26.9-gke.1345000 以降
1.27: 1.27.6-gke.100 以降
1.28: 1.28.1-gke.1157000 以降

また、該当のワークロードでこの問題の影響を軽減するには、renameat2 システム呼び出しにつながるコードの置き換えを試してください。コードを変更できない場合は、ノードプールでイメージストリーミングを無効にすることで、問題を軽減する必要があります。

イメージ ストリーミングを使用してコンテナ イメージを pull する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

要件

制限事項

始める前に

クラスタでイメージ ストリーミングを有効にする

新しいクラスタの場合

gcloud

コンソール

既存クラスタの場合

gcloud

コンソール

クラスタでイメージ ストリーミングが有効になっていることを確認する

gcloud

コンソール

ノードプールでイメージ ストリーミングを有効にする

新しいノードプールの場合

既存のノードプールの場合

ノードプールでイメージ ストリーミングが有効になっていることを確認する

イメージ ストリーミングを使用してワークロードをスケジュールする

標準的なイメージの pull とパフォーマンスを比較する

クリーンアップ

イメージ ストリーミングを無効にする

GKE Standard クラスタでイメージ ストリーミングを無効にする

gcloud

コンソール

新しいノードプールの場合

既存のノードプールの場合

イメージ ストリーミングのメモリ予約

トラブルシューティング

GKE がイメージ ストリーミング ファイル システムを使用しない

PermissionDenied

FailedPrecondition

InvalidArgument

backend.FileContent failed

GKE によるデータのストリーミングなしでのイメージ ダウンロード

空のレイヤまたは重複するレイヤの確認

シンボリック リンク ファイルで mv コマンドと renameat2 システムの呼び出しが失敗する

イメージストリーミングを使用してコンテナイメージを pull する

クラスタでイメージストリーミングを有効にする

クラスタでイメージストリーミングが有効になっていることを確認する

ノードプールでイメージストリーミングを有効にする

ノードプールでイメージストリーミングが有効になっていることを確認する

イメージストリーミングを使用してワークロードをスケジュールする

イメージストリーミングを無効にする

GKE Standard クラスタでイメージストリーミングを無効にする

イメージストリーミングのメモリ予約

GKE がイメージストリーミングファイルシステムを使用しない

`backend.FileContent failed`

GKE によるデータのストリーミングなしでのイメージダウンロード

シンボリックリンクファイルで `mv` コマンドと `renameat2` システムの呼び出しが失敗する