이미지 사전 로딩으로 지연 시간 줄이기

이미지를 미리 워밍하면 런타임 클라이언트가 컨테이너 이미지를 요청하기 전에 이미지 스트리밍 캐시로 컨테이너 이미지 다운로드를 명시적으로 트리거할 수 있습니다. 이렇게 하면 이미지 스트리밍을 사용하는 워크로드의 새 이미지 버전을 처음 가져올 때 발생하는 "콜드 스타트" 지연 시간이 효과적으로 제거됩니다.

개요

Artifact Registry에 이미지를 푸시하면 기본 스토리지 시스템에 저장됩니다. 지연 시간이 짧은 액세스를 위해 Artifact Registry는 이미지 스트리밍 캐시도 사용합니다. 이 캐시는 일반적으로 이미지 스트리밍이 사용 설정된 클라이언트에서 처음 가져올 때 채워집니다. Google Kubernetes Engine 클러스터 확장과 같이 지연 시간에 민감한 워크로드의 경우 이 캐시가 워밍될 때까지 기다리면 지연이 발생할 수 있습니다. 미리 워밍하면 이미지를 이미지 스트리밍 캐시에 미리 가져올 수 있습니다.

아티팩트 미리 워밍 API를 사용하면 특정 이미지 버전 또는 태그가 미리 캐시되도록 수동으로 요청할 수 있습니다. 또한 이미지의 캐시 보관 기간을 지정하여 이미지가 지정된 기간 동안 캐시에 유지되도록 할 수 있습니다.

제한사항

  • API 전용: 미리 워밍은 Artifact Registry REST API를 통해서만 사용할 수 있습니다. 콘솔을 Google Cloud 사용하여 미리 워밍할 수는 없습니다.
  • GKE 전용: 미리 워밍은 이미지 스트리밍 이 사용 설정된 GKE 클러스터에만 적용됩니다. 이미지 스트리밍에는 클라이언트 노드에서 실행되는 특정 소프트웨어가 필요합니다.
  • 단일 아티팩트: API 요청당 하나의 아티팩트 (버전 또는 태그)만 미리 워밍할 수 있습니다.
  • 다중 아키텍처 이미지: 지원되지 않음 아키텍처 이미지의 특정 버전을 사용하세요.
  • 프로젝트 한도: 미리 워밍된 이미지의 소비자 프로젝트당 전체 한도는 100GB입니다. 한도에 도달하면 새 이미지를 위한 공간을 확보하기 위해 이전 이미지가 삭제됩니다.

시작하기 전에

  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인 경우 시스템에서 이전 아티팩트를 삭제하여 이 아티팩트를 위한 공간을 확보할 수 있습니다.
stream_location 선택사항. 이미지가 미리 워밍될 특정 리전입니다. 기본적으로 이는 이미지 위치와 일치합니다. 멀티 리전 구성은 지원되지 않습니다. 광범위한 리전이 지정된 경우 기본값은 us-central1 (미국), europe-north1 (EU), asia-east1 (아시아)입니다.

예: 특정 버전 미리 워밍

다음 예에서는 'us-east1' 리전의 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,
    "stream_location": "us-east1",
  }' \
  "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 메서드를 사용합니다. 다음 예에서는 us-east1의 my-repo 아래에 있는 미리 워밍된 모든 이미지를 나열합니다. stream_location 필터가 필요합니다.

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?filter=stream_location=us-east1"/

캐시에서 삭제

미리 워밍 캐시에서 아티팩트를 명시적으로 삭제하려면 :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"

다음 단계