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

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

개요

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

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

제한사항

  • API 전용: 사전 준비는 Artifact Registry REST API를 통해서만 사용할 수 있습니다. gcloud CLI 또는 Google Cloud 콘솔을 사용하여 사전 준비를 사용할 수 없습니다.
  • GKE 전용: 사전 준비는 이미지 스트리밍 이 사용 설정된 GKE 클러스터에만 적용됩니다. 이미지 스트리밍에는 클라이언트 노드에서 실행되는 특정 소프트웨어가 필요합니다.
  • 단일 아티팩트: API 요청당 하나의 아티팩트 (버전 또는 태그)만 사전 준비할 수 있습니다.
  • 멀티 아키텍처 이미지: 지원되지 않음 아키텍처 이미지에 특정 버전을 사용합니다.

시작하기 전에

  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"

다음 단계