Google Kubernetes Engine에 배포

이 가이드에서는 Artifact Registry에서 이미지를 가져와 Google Kubernetes Engine에 배포하는 방법을 설명합니다. 자체 호스팅 또는 서드 파티 Kubernetes 서비스에 배포하려면 Artifact Registry에서 이미지를 가져오기 전에 Google Cloud에 대한 인증을 구성해야 합니다. Google Cloud 외부의 Kubernetes 워크로드에서 Google Cloud에 인증하려면 Kubernetes로 워크로드 아이덴티티 제휴 구성하기를 참조하세요.

Google Kubernetes Engine은 Docker 저장소에서 직접 이미지를 가져올 수 있습니다. 일부 버전에는 Artifact Registry Docker 저장소에서 이미지를 가져오기 위한 사전 구성된 지원이 포함됩니다.

요구사항

이 섹션에서는 GKE와 통합하기 위한 요구사항에 대해 설명합니다.

권한

GKE는 노드 풀 또는 클러스터를 만들 때 다음 기본값을 사용합니다.

Compute Engine 기본 서비스 계정은 노드의 ID입니다. 기본 편집자 역할 부여를 사용 중지한 경우 이 기본 서비스 계정에 Artifact Registry 리더 역할(roles/artifactregistry.reader)이 포함됩니다.
기본 서비스 계정으로 만드는 노드에는 스토리지에 대한 읽기 전용 액세스를 포함하여 Compute Engine 기본 액세스 범위가 포함됩니다. 기존 노드에서는 액세스 범위를 변경할 수 없습니다.

이러한 기본값을 사용할 경우 GKE는 동일한 Google Cloud 프로젝트에 있는 Artifact Registry 저장소에서 이미지를 가져올 수 있습니다. 노드에서 이미지를 내보내거나, 프로젝트 간에 이미지를 가져오거나 내보내야 하는 경우, 사용자 제공 서비스 계정을 사용해야 하는 경우 또는 기본 설정으로 지원되지 않는 다른 요구 사항이 있는 경우에는 액세스 제어 문서에서 액세스 구성 정보를 참조하세요.

'권한 거부됨' 오류가 발생하면 권한 거부됨 오류를 참조하세요.

GKE 버전

다음 표에서는 동일한 프로젝트에 있는 Docker 저장소에서 컨테이너를 가져오기 위해 기본 권한이 있는 클러스터를 만들기 위해 필요한 최소한의 GKE 버전을 보여줍니다.

버전	최소 필수 패치
1.14	1.14.10-gke.22
1.15	1.15.9-gke.8

GKE 버전이 최소 버전보다 이전이면 GKE가 이미지를 가져오도록 Kubernetes imagePullSecrets를 구성해야 합니다.

GKE가 Artifact Registry와 다른 프로젝트에 있으면 GKE 노드에 사용되는 서비스 계정에 Artifact Registry 권한을 부여합니다. 기본적으로 노드는 Compute Engine 기본 서비스 계정을 사용합니다.

이미지 실행

다음 명령어를 사용하면 Google Kubernetes Engine 클러스터에서 Artifact Registry 이미지를 실행할 수 있습니다.

kubectl run [NAME] --image=LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

각 항목의 의미는 다음과 같습니다.

LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
PROJECT는 Google Cloud 콘솔 프로젝트 ID입니다. 프로젝트 ID에 콜론(:)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
REPOSITORY는 이미지가 저장된 저장소의 이름입니다.
IMAGE는 저장소의 이미지 이름입니다.
TAG는 가져올 이미지 버전의 태그입니다.

Kubernetes 명령어에 대한 자세한 내용은 kubectl 개요를 참조하세요.

containerd 노드 이미지 문제 해결

GKE 노드 버전 1.19부터는 Linux 노드의 기본 노드 이미지가 Docker(cos) 변형을 포함한 Container-Optimized OS 대신 containerd(cos_containerd) 변형을 포함한 Container-Optimized OS입니다.

현재 containerd를 런타임으로 사용하는 Linux 노드에서 Docker 바이너리를 사용할 수는 있기는 하지만 이 바이너리를 사용하지 않는 것이 좋습니다. Docker는 Kubernetes가 containerd 노드에서 실행하는 컨테이너를 관리하지 않으므로 Docker 명령어 또는 Docker API를 사용하여 실행중인 Kubernetes 컨테이너를 확인하거나 상호작용하는 데는 사용할 수 없습니다.

Linux 노드에서 디버깅 또는 문제 해결을 위해 개발자는 Kubernetes 컨테이너 런타임용으로 빌드된 간이 명령줄 도구인 crictl을 사용하여 containerd와 상호작용할 수 있습니다. crictl은 컨테이너 및 이미지 보기, 로그 읽기, 컨테이너에서 명령어 실행을 수행하는 일반 기능을 지원합니다.

자세한 내용은 crictl 사용자 가이드와 containerd에 대한 GKE 문서를 참조하세요.

Windows Server 노드의 경우 containerd 데몬이 containerd라는 이름의 Windows 서비스로 실행됩니다. 로그는 C:\etc\kubernetes\logs\containerd.log 로그 디렉터리에서 제공되며 로그 탐색기에서 LOG NAME: "container-runtime"에 표시됩니다.

공개 Artifact Registry 저장소에서 가져오기

containerd 노드로 GKE 클러스터에 이미지를 배포한 후 SSH를 사용하여 VM 인스턴스에 연결하고 문제 해결을 위해 crictl 명령어를 실행할 수 있습니다.

공개 Artifact Registry 저장소는 인증이 필요하지 않습니다. crictl을 사용하여 비공개 Artifact Registry 저장소에서 이미지를 가져올 수 있습니다.

콘솔

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.

VM 인스턴스로 이동
가상 머신 인스턴스 목록에서 연결하려는 인스턴스 행에서 SSH 옆에 있는 화살표를 클릭합니다.

참고: Google Cloud 콘솔을 사용하여 VM에 연결할 때 Compute Engine은 일시적인 SSH 키를 자동으로 만듭니다. SSH 키에 대한 자세한 내용은 Linux VM에 대한 SSH 연결을 참조하세요.
'브라우저 창에서 열기'를 선택하거나 드롭다운 옵션에서 원하는 연결 방법을 선택합니다.
Google Cloud 콘솔에 새 터미널 창이 열립니다. crictl을 사용하여 Artifact Registry에서 이미지를 가져옵니다.
```
crictl pull IMAGE_LOCATION:TAG
```
출력은 다음과 같이 표시됩니다.
```
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
```
Artifact Registry 비공개 저장소에서 이미지를 가져올 때 저장소에 인증을 수행해야 합니다. 액세스 토큰을 사용하여 사용자 인증 정보를 제공할 수 있습니다.

gcloud

최신 버전의 Google Cloud CLI가 있어야 합니다.
```
gcloud components update
```
VM에 연결합니다.
```
gcloud compute ssh --project=PROJECT_ID \
 --zone=ZONE \
 VM_NAME
```
다음을 바꿉니다.
- PROJECT_ID: VM이 포함된 프로젝트의 ID
- ZONE: VM이 있는 영역의 이름
- VM_NAME: VM의 이름
Google Cloud CLI에 기본 속성을 설정한 경우 이 명령어에서 --project 플래그와 --zone 플래그를 생략할 수 있습니다. 예를 들면 다음과 같습니다.
```
gcloud compute ssh VM_NAME
```
아직 SSH 키를 만들지 않았으면 SSH keygen으로 키가 생성됩니다. 메시지가 표시되면 암호를 입력하거나 비워 둡니다.
crictl을 사용하여 Artifact Registry에서 이미지를 가져옵니다.
```
crictl pull IMAGE_LOCATION:TAG
```
출력은 다음과 같이 표시됩니다.
```
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
```
Artifact Registry 비공개 저장소에서 이미지를 가져올 때 저장소에 인증을 수행해야 합니다. 액세스 토큰을 사용하여 사용자 인증 정보를 제공할 수 있습니다.

비공개 Artifact Registry 저장소에서 가져오기

콘솔

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.

VM 인스턴스로 이동
가상 머신 인스턴스 목록에서 연결하려는 인스턴스 행에서 SSH 옆에 있는 화살표를 클릭합니다.

참고: Google Cloud 콘솔을 사용하여 VM에 연결할 때 Compute Engine은 일시적인 SSH 키를 자동으로 만듭니다. SSH 키에 대한 자세한 내용은 Linux VM에 대한 SSH 연결을 참조하세요.
드롭다운 옵션에서 '브라우저 창에서 열기'를 선택합니다.

Google Cloud 콘솔에 새 터미널 창이 열립니다. curl을 사용하여 Compute Engine 서비스 계정 액세스 토큰을 생성합니다.

curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

출력은 다음 예시와 같이 표시됩니다.

"access_token":"ya29.c.KpkBCQgdwv6LrZ2tjrCpG6snWwPMX29LzMeUmAV_Hq_XaxUurfXcCfGZfASGh_KbdmUYTvkuV3sh-WaSBplEskdP6Tc
HDsTv4B9hMyvoL4M9HrzKHuKTa1ZGj_3iQ1lwq_dAMxAPGjxEVKexatwN2KP0EAWyb6R55Cuu8ItgLf9f4pm9lC5zH4Qo0fkxPUsnCGRBe4AYxEpN6T
sh","expires_in":3526,"token_type":"Bearer"}

따옴표 없이 반환된 출력에서 access_token 값을 복사합니다.

이전 단계에서 복사한 crictl pull --creds 및 access_token 값을 사용하여 이미지를 가져옵니다.

crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" IMAGE_LOCATION:TAG

출력은 다음과 같이 표시됩니다.

Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

gcloud

최신 버전의 Google Cloud CLI가 있어야 합니다.
```
gcloud components update
```
VM에 연결합니다.
```
gcloud compute ssh --project=PROJECT_ID \
 --zone=ZONE \
 VM_NAME
```
다음 변수를 바꿉니다.
- PROJECT_ID: VM이 포함된 프로젝트의 ID
- ZONE: VM이 있는 영역의 이름
- VM_NAME: VM의 이름
Google Cloud CLI에 기본 속성을 설정한 경우 이 명령어에서 --project 플래그와 --zone 플래그를 생략할 수 있습니다. 예를 들면 다음과 같습니다.
```
gcloud compute ssh VM_NAME
```
아직 SSH 키를 만들지 않았으면 SSH keygen으로 키가 생성됩니다. 메시지가 표시되면 암호를 입력하거나 비워 둡니다.

curl을 사용하여 Compute Engine 서비스 계정 액세스 토큰을 생성합니다.

curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

출력은 다음과 같이 표시됩니다.

"access_token":"ya29.c.KpkBCQgdwv6LrZ2tjrCpG6snWwPMX29LzMeUmAV_Hq_XaxUurfXcCfGZfASGh_KbdmUYTvkuV3sh-WaSBplEskdP6Tc
HDsTv4B9hMyvoL4M9HrzKHuKTa1ZGj_3iQ1lwq_dAMxAPGjxEVKexatwN2KP0EAWyb6R55Cuu8ItgLf9f4pm9lC5zH4Qo0fkxPUsnCGRBe4AYxEpN6T
sh","expires_in":3526,"token_type":"Bearer"}

따옴표 없이 반환된 출력에서 access_token 값을 복사합니다.

이전 단계에서 복사한 crictl pull --creds 및 access_token 값을 사용하여 이미지를 가져옵니다.

crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" IMAGE_LOCATION:TAG

출력은 다음과 같이 표시됩니다.

Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

crictl을 사용하면 개발자가 Kubernetes 구성요소를 설정할 필요 없이 런타임을 디버깅할 수 있습니다. 전체 명령어 목록은 crictl 문서 및 Kubernetes 디버깅 문서를 참조하세요.