이미지 스트리밍을 사용하여 컨테이너 이미지 가져오기

Autopilot Standard

이 페이지에서는 Google Kubernetes Engine(GKE)에서 이미지 스트리밍을 사용하여 애플리케이션에 필요할 때 이미지 데이터를 스트리밍하여 컨테이너 이미지를 가져오는 방법을 보여줍니다.

GKE 버전 1.25.5-gke.1000 이상을 실행하는 새 Autopilot 클러스터는 자동으로 이미지 스트리밍을 사용하여 적합한 이미지를 가져옵니다. 이 페이지의 안내는 Standard 클러스터에만 적용됩니다.

개요

이미지 스트리밍은 GKE가 애플리케이션의 요청에 따라 적합한 이미지에서 데이터를 스트리밍하는 컨테이너 이미지를 가져오는 방법입니다. 이미지 스트리밍을 사용하면 전체 이미지가 다운로드될 때까지 기다리지 않고 워크로드를 초기화할 수 있으므로 초기화 시간이 크게 단축됩니다. 가져오기 시간을 단축하면 다음과 같은 이점이 있습니다.

빠른 자동 확장
대용량 이미지를 가져올 때 지연 시간 감소
빠른 포드 시작

GKE에서는 이미지 스트리밍을 통해 원격 파일 시스템을 대상 컨테이너 이미지를 사용하는 컨테이너의 루트 파일 시스템으로 사용합니다. 워크로드에서 필요한 경우 GKE에서 원격 파일 시스템의 이미지 데이터를 스트리밍합니다. 이미지 스트리밍이 없으면 GKE는 전체 컨테이너 이미지를 각 노드에 다운로드하여 이를 워크로드의 루트 파일 시스템으로 사용합니다.

이미지 데이터를 스트리밍하는 동안 GKE는 백그라운드에서 전체 컨테이너 이미지를 로컬 디스크에 다운로드하고 캐시합니다. 그런 다음 GKE에서 캐시된 이미지의 이후 데이터 읽기 요청을 처리합니다.

컨테이너 이미지에서 특정 파일을 읽어야 하는 워크로드를 배포하면 이미지 스트리밍 백엔드가 요청된 파일만 제공합니다.

요구사항

GKE Autopilot 및 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에 저장되어야 합니다.
비공개 클러스터를 사용하는 경우 이미지 스트리밍 서비스에 액세스하려면 노드의 서브넷에 비공개 Google 액세스를 사용 설정해야 합니다.
VPC 서비스 제어에서 컨테이너 이미지를 보호하며 이미지 스트리밍을 사용하는 경우 서비스 경계에 이미지 스트리밍 API(containerfilesystem.googleapis.com)도 포함해야 합니다.
클러스터의 GKE 노드에서 기본 서비스 계정을 사용하지 않는 경우 커스텀 서비스 계정에 컨테이너 이미지를 호스팅하는 프로젝트의 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer) IAM 역할이 있는지 확인해야 합니다.

제한사항

1.23.5-gke.1900 이전의 GKE 버전에서는 보안 비밀을 사용하여 컨테이너 이미지를 가져올 수 없습니다.
V2 이미지 매니페스트, 스키마 버전 1을 사용하는 컨테이너 이미지는 적합하지 않습니다.
고객 관리 암호화 키(CMEK)로 암호화된 컨테이너 이미지는 GKE 버전 1.25.3-gke.1000 이상에서 이미지 스트리밍에 적합합니다. 이전 버전에서는 GKE가 데이터를 스트리밍하지 않고 이러한 이미지를 다운로드합니다. CMEK를 사용하여 이미지 스트리밍을 사용하는 클러스터에서 연결된 영구 디스크와 커스텀 부팅 디스크를 계속 보호할 수 있습니다.
중복된 레이어가 있는 컨테이너 이미지는 지원되지 않습니다. GKE는 데이터를 스트리밍하지 않고 이러한 이미지를 다운로드합니다. 컨테이너 이미지에서 빈 레이어 또는 중복 레이어를 확인합니다.
Artifact Registry 저장소는 GKE 노드와 동일한 리전 또는 노드가 실행 중인 리전에 해당하는 멀티 리전에 있어야 합니다. 예를 들면 다음과 같습니다.
- 노드가 us-east1에 있는 경우 GKE 및 Artifact Registry가 모두 미국 내 데이터 센터 위치에서 실행되므로 us-east1 리전 또는 us 멀티 리전의 저장소에 이미지 스트리밍을 사용할 수 있습니다.
- 노드가 northamerica-northeast1 리전에 있으면 노드는 캐나다에서 실행 중인 것입니다. 이 경우 이미지 스트리밍은 동일한 리전의 저장소에서만 사용할 수 있습니다.
초기화 중에 워크로드가 이미지에서 파일을 여러 개 읽는 경우 원격 파일 읽기에 의해 추가된 지연 시간으로 인해 초기화 시간이 늘어날 수 있습니다.
대상 이미지를 처음 가져올 때는 이미지 스트리밍의 이점을 느끼지 못할 수 있습니다. 하지만 이미지 스트리밍이 이미지를 캐시하고 나면 클러스터의 이후 이미지 가져오기에서 이미지 스트리밍의 이점을 누릴 수 있습니다.
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 사용 설정

클러스터에 이미지 스트리밍 사용 설정

gcloud CLI --enable-image-streaming 플래그를 사용하거나 Google Cloud 콘솔을 사용하여 새 클러스터 또는 기존 Standard 클러스터에서 이미지 스트리밍을 사용 설정할 수 있습니다. 기본적으로 클러스터의 노드 풀은 클러스터 수준에서 이미지 스트리밍 설정을 상속합니다. 클러스터의 노드 풀에서 이미지 스트리밍을 사용 설정하거나 중지하여 이 동작을 변경할 수 있습니다.

GKE 버전 1.25.5-gke.1000 이상을 실행하는 모든 새 Autopilot 클러스터는 이미지 스트리밍을 사용하여 적합한 이미지를 가져옵니다. 자세한 내용은 새 Autopilot 클러스터의 버전 및 출시 채널 설정을 참조하세요. 다음 안내는 GKE Standard 클러스터에만 적용됩니다.

새 클러스터

gcloud CLI 또는 Google Cloud 콘솔을 사용하여 새 클러스터에 이미지 스트리밍을 사용 설정할 수 있습니다.

gcloud

이미지 스트리밍이 사용 설정된 새 클러스터를 만들려면 다음 명령어를 실행합니다.

gcloud container clusters create CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

다음을 바꿉니다.

CLUSTER_NAME: 새 클러스터의 이름입니다.
COMPUTE_ZONE: 새 클러스터의 Compute Engine 영역입니다. 리전 클러스터의 경우 대신 --region=COMPUTE_REGION 플래그를 사용합니다. 영역이나 리전이 동일한 리전이거나 이미지를 포함하는 Artifact Registry 저장소의 멀티 리전 내에 있는지 확인합니다.

콘솔

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
만들기를 클릭합니다.
GKE Standard 섹션에서 구성을 클릭합니다.
탐색창의 클러스터에서 기능을 클릭합니다.
기타 섹션에서 이미지 스트리밍 사용 설정 체크박스를 선택합니다.
필요에 따라 클러스터를 구성한 후 만들기를 클릭합니다.

기존 클러스터에서

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 \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

다음을 바꿉니다.

NODE_POOL_NAME: 새 노드 풀의 이름입니다.
CLUSTER_NAME: 노드 풀의 클러스터 이름입니다.
COMPUTE_ZONE: 클러스터의 Compute Engine 영역입니다. 리전 클러스터의 경우 대신 --region=COMPUTE_REGION 플래그를 사용합니다.

기존 노드 풀에서

요구사항을 충족하는 기존 노드 풀에 이미지 스트리밍을 사용 설정할 수 있습니다.

이미지 스트리밍을 사용하도록 기존 노드 풀을 업데이트하려면 다음 명령어를 실행합니다.

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에서 대상 컨테이너 이미지를 가져올 때 자동으로 이미지 스트리밍을 사용합니다.

GKE에서 이미지 스트리밍이 사용 설정된 노드 풀의 노드에 cloud.google.com/gke-image-streaming: "true" 라벨을 추가합니다. GKE Standard에서는 클러스터에 이미지 스트리밍을 사용하는 노드와 사용하지 않는 노드가 혼합되도록 특정 노드 풀에서 이미지 스트리밍을 사용 설정하거나 중지한 경우 배포에서 노드 선택기를 사용해 GKE가 이미지 스트리밍을 사용하는 노드에 워크로드를 예약하는지 여부를 제어할 수 있습니다.

다음 예시에서는 이미지 스트리밍이 사용 설정된 클러스터에서 대용량 컨테이너 이미지를 사용하는 배포를 예약합니다. 그러면 원하는 경우 이미지 스트리밍을 사용 설정하지 않고도 성능을 이미지 가져오기와 비교할 수 있습니다.

이미지 스트리밍이 사용 설정된 새 클러스터를 만듭니다.

gcloud container clusters create CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --enable-image-streaming \
    --image-type="COS_CONTAINERD"

클러스터의 사용자 인증 정보를 가져옵니다.

gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE

다음 매니페스트를 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 컨테이너 이미지 크기는 327MB입니다.

매니페스트를 클러스터에 적용합니다.
```
kubectl apply -f frontend-deployment.yaml
```

GKE에서 배포를 생성했는지 확인합니다.

kubectl get pods -l app=guestbook

출력은 다음과 비슷합니다.

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

Kubernetes 이벤트 로그를 가져와 이미지 가져오기 이벤트를 확인합니다.
```
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 이벤트는 이미지 스트리밍에서 이미지를 가져오는 데 걸린 시간을 보여줍니다.
- ImageStreaming 이벤트는 노드가 이미지 스트리밍을 사용하여 컨테이너 이미지를 제공함을 알려줍니다.
  
  참고: Reason 필드에는 GKE 버전이 1.20.9-gke.1000 이하인 클러스터에서 ImageStreaming 대신 BackedByGCFS가 표시됩니다. BackedByGCFS는 이미지에서 이미지 스트리밍을 사용함을 나타냅니다.
  참고: 동일한 노드에서 같은 이미지를 사용하는 워크로드를 실행하면 GKE는 이미지 스트리밍 대신 이미지 로컬 캐시를 사용합니다. 포드 Pulled 이벤트의 Message 필드에 Container image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" already present on machine이 표시됩니다. 이미지 스트리밍 성능을 다시 테스트하려면 노드를 삭제하고 새 노드를 만드세요.

표준 이미지 가져오기와 성능 비교

이 선택적 예시에서는 이미지 스트리밍이 중지된 새 클러스터를 만들고 frontend 배포를 배포하여 성능을 이미지 스트리밍과 비교합니다.

이미지 스트리밍이 중지된 새 클러스터를 만듭니다.
```
gcloud container clusters create CLUSTER2_NAME\
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD"
```
참고: 기본적으로 GKE는 이미지 스트리밍이 중지된 클러스터를 만듭니다.

클러스터의 사용자 인증 정보를 가져옵니다.

gcloud container clusters get-credentials CLUSTER2_NAME \
    --zone=COMPUTE_ZONE

이전 예시의 frontend 배포를 배포합니다.
```
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가 전체 이미지를 가져오는 데 걸린 시간을 확인합니다. 이 예시 출력에서는 GKE에 거의 24초가 사용되었습니다. 이미지 스트리밍이 사용 설정된 상태에서 GKE에서 워크로드가 시작하는 데 필요한 이미지 데이터를 가져오는 데 1.5초밖에 걸리지 않았습니다.

삭제

요금이 청구되지 않도록 이전 예시에서 만든 클러스터를 삭제합니다.

gcloud container clusters delete CLUSTER_NAME CLUSTER2_NAME

이미지 스트리밍 중지

GKE Autopilot을 사용하는 경우 개별 클러스터에서 이미지 스트리밍을 중지할 수 없습니다. 컨테이너 파일 시스템 API를 사용 중지하여 전체 프로젝트에 대해 이미지 스트리밍을 사용 중지할 수 있습니다.

GKE Standard 클러스터를 사용하는 경우 다음 섹션의 설명대로 개별 클러스터 또는 특정 노드 풀에서 이미지 스트리밍을 중지할 수 있습니다.

GKE Standard 클러스터에서 이미지 스트리밍 중지

gcloud CLI 또는 Google Cloud 콘솔을 사용하여 기존 GKE Standard 클러스터에서 이미지 스트리밍을 중지할 수 있습니다.

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 \
    --zone=COMPUTE_ZONE \
    --no-enable-image-streaming

기존 노드 풀에서

기존 노드 풀에서 이미지 스트리밍을 중지하려면 다음 명령어를 실행합니다.

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

이미지 스트리밍을 위한 메모리 예약

GKE는 노드 시스템 구성요소의 실행을 위해 예약된 메모리 외에도 이미지 스트리밍을 위한 메모리 리소스를 예약합니다. GKE는 이미지 스트리밍을 위한 추가 CPU 리소스를 예약하지 않습니다. GKE Standard 클러스터에서 이 예약은 포드에서 요청할 수 있는 메모리 리소스를 변경합니다. GKE Autopilot에서 GKE는 시스템 할당을 관리하므로 워크로드 예약에는 영향을 주지 않습니다.

노드 구성요소를 위한 GKE의 메모리 예약에 대한 자세한 내용은 표준 클러스터 아키텍처를 참조하세요.

이미지 스트리밍을 사용하는 노드에서 GKE는 새 예약에 다음과 같은 추가 메모리 예약을 수행합니다.

메모리가 1GiB 미만인 머신의 경우 추가 메모리 없음
처음 4GiB 메모리 중 1%
다음 4GiB 메모리 중 0.8%(최대 8GiB)
다음 8GiB 메모리 중 0.4%(최대 16GiB)
다음 112GiB 메모리 중 0.24%(최대 128GiB)
128GiB 이상의 메모리 중 0.08%

문제 해결

GKE는 이미지 스트리밍 파일 시스템을 사용하지 않음

GKE 이벤트 로그에 이미지 스트리밍 이벤트가 표시되지 않는 경우 원격 파일 시스템에서 이미지를 지원하지 않습니다. 전에 GKE가 노드에서 이미지를 가져온 경우 GKE에서 이미지 스트리밍을 사용하는 대신 이미지의 로컬 캐시를 후속 가져오기에 사용하므로 이는 예상 동작입니다. 포드 Pulled 이벤트의 Message 필드에서 Container image IMAGE_NAME already present on machine을 찾으면 이를 확인할 수 있습니다.

노드에서 이미지를 처음 가져올 때 이미지 스트리밍 이벤트가 표시되지 않으면 이미지 스트리밍 요구사항을 충족하는지 확인합니다. 요구사항을 충족하는 경우 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에서 이미지 스트리밍을 사용하지 않고 워크로드의 컨테이너 이미지를 가져옵니다.

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 \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming \
    --scope="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

이 오류는 프로젝트에 원격 컨테이너 파일 시스템 서비스에서 파일을 읽는 데 필요한 할당량이 초과되었음을 나타냅니다. 이 문제를 해결하려면 다음 할당량을 늘립니다.

리전 및 프로젝트별 분당 콘텐츠 요청
리전 및 프로젝트별 콘텐츠 요청

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 시스템 호출로 이어지는 코드를 대체해 볼 수 있습니다. 코드를 수정할 수 없는 경우에는 노드 풀에서 이미지 스트리밍을 중지하여 문제를 완화해야 합니다.

이미지 스트리밍을 사용하여 컨테이너 이미지 가져오기

개요

요구사항

제한사항

시작하기 전에

클러스터에 이미지 스트리밍 사용 설정

새 클러스터

gcloud

콘솔

기존 클러스터에서

gcloud

콘솔

클러스터에 이미지 스트리밍이 사용 설정되었는지 확인

gcloud

콘솔

노드 풀에 이미지 스트리밍 사용 설정

새 노드 풀에서

기존 노드 풀에서

노드 풀에 이미지 스트리밍이 사용 설정되어 있는지 확인

이미지 스트리밍을 사용한 워크로드 예약

표준 이미지 가져오기와 성능 비교

삭제

이미지 스트리밍 중지

GKE Standard 클러스터에서 이미지 스트리밍 중지

gcloud

콘솔

새 노드 풀에서

기존 노드 풀에서

이미지 스트리밍을 위한 메모리 예약

문제 해결

GKE는 이미지 스트리밍 파일 시스템을 사용하지 않음

PermissionDenied

FailedPrecondition

InvalidArgument

backend.FileContent failed

GKE는 데이터 스트리밍 없이 이미지를 다운로드함

빈 레이어 또는 중복 레이어 확인

심볼릭 링크 파일에서 mv 명령어 및 renameat2 시스템 호출이 실패함

`backend.FileContent failed`

심볼릭 링크 파일에서 `mv` 명령어 및 `renameat2` 시스템 호출이 실패함