이 페이지는 Cloud Translation API를 통해 번역되었습니다.

GKE 노드에서 containerd 구성 맞춤설정

Autopilot Standard

이 페이지에서는 Google Kubernetes Engine(GKE) 노드에서 containerd 컨테이너 런타임 구성을 맞춤설정하는 방법을 보여줍니다. 이 문서를 읽기 전에 컨테이너 런타임의 정의와 맞춤설정해야 하는 이유를 숙지해야 합니다.

GKE의 containerd 구성 정보

Container-Optimized OS와 같은 운영체제를 실행하는 GKE 노드의 containerd 런타임에서 옵션 집합을 수동으로 구성할 수 있습니다. 런타임을 맞춤설정하면 비공개 이미지 레지스트리에 액세스와 같은 특별한 요구사항을 구성할 수 있습니다. 이러한 옵션을 설정하려면 런타임 구성 파일이라는 YAML 파일을 만들고 클러스터를 만들거나 업데이트할 때 이 파일을 GKE에 전달합니다.

이러한 containerd 맞춤설정 방법을 사용하면 보안 위험인 권한이 있는 DaemonSet 배포를 방지할 수 있습니다. GKE에 런타임 구성 파일을 제공하면 GKE에서 노드를 다시 만들고 구성을 사용하여 모든 노드에서 containerd config.toml 파일을 업데이트합니다. 구성은 노드 종료, 업그레이드, 재생성 동안 유지됩니다.

런타임 구성 파일을 사용하면 containerd의 옵션만 구성할 수 있습니다. 또한 GKE에서 노드 시스템 구성 파일이라는 별도의 파일을 사용하여 특정 kubelet 옵션과 하위 수준 Linux 커널 옵션을 구성할 수 있습니다. 자세한 내용은 노드 시스템 구성 맞춤설정을 참조하세요.

제한사항

런타임 구성 파일을 사용하여 Windows 노드 이미지의 containerd 설정을 변경할 수 없습니다.

사용 가능한 containerd 구성 옵션

다음 섹션에서는 런타임 구성 파일을 사용하여 구성할 수 있는 옵션을 설명합니다.

참고: containerd 레지스트리를 설정할 때는 privateRegistryAccessConfig 대신 더 많은 레지스트리 필드를 포함하는 registryHosts 구성을 사용하는 것이 좋습니다. registryHosts은 privateRegistryAccessConfig의 일치하는 FQDN을 재정의합니다.

`privateRegistryAccessConfig`

Secret Manager에 저장하는 비공개 사용자 인증 정보를 사용하여 비공개 이미지 레지스트리에 액세스합니다.

이 옵션은 Container-Optimized OS 노드 이미지의 경우 GKE 버전 1.27.3-gke.1700 이상, Ubuntu 노드 이미지의 경우 1.33 이상에서 사용할 수 있습니다.

자세한 내용은 비공개 CA 인증서로 비공개 레지스트리에 액세스를 참고하세요.

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

이 구성에는 다음 필드가 포함됩니다.

enabled: 비공개 레지스트리 구성을 사용 설정하는 불리언입니다. enabled: false를 설정한 경우 privateRegistryAccessConfig 항목의 다른 필드를 삭제합니다.
certificateAuthorityDomainConfig: 인증서 최대 5개와 FQDN 정의를 포함합니다.
gcpSecretManagerCertificateConfig: Secret Manager에 저장된 인증서와 FQDN 배열을 포함합니다.
secretURI: Secret Manager에서의 인증서 위치입니다. privateRegistryAccessConfig은 secretURI에서만 전역 비밀번호를 지원합니다.
fqdns: 비공개 레지스트리의 정규화된 도메인 이름 목록입니다. IPv4 주소도 사용할 수 있지만 FQDN을 사용하는 것이 좋습니다.

`registryHosts`

기능, 맞춤 헤더, 인증서와 같은 containerd 레지스트리의 고급 설정을 구성합니다. 이는 containerd의 hosts.toml에 해당합니다.

이 옵션은 GKE 버전 1.34.1-gke.2980000 이상에서 사용할 수 있습니다.

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

이 구성에는 다음 필드가 포함됩니다.

server: 레지스트리 서버의 호스트 이름입니다 (예: example.com). 이는 노드에서 구성 파일의 이름을 지정하는 데 사용됩니다. 정규화된 도메인 이름 또는 IPv4 주소여야 합니다.
hosts: server의 호스트별 구성 목록입니다.
host: 레지스트리 미러의 호스트 이름 (예: mirror.example.com). 정규화된 도메인 이름 또는 IPv4 주소여야 합니다.
capabilities: 호스트가 실행할 수 있는 작업을 지정하는 기능 목록입니다. 지원되는 값은 다음 중 하나입니다.
- HOST_CAPABILITY_PULL: 다이제스트로 매니페스트와 blob을 가져오는 기능을 나타냅니다.
- HOST_CAPABILITY_RESOLVE: 이름으로 매니페스트를 가져오는 기능을 나타냅니다.
- HOST_CAPABILITY_PUSH: blob 및 매니페스트를 푸시하는 기능을 나타냅니다.
지정하지 않으면 모든 기능이 사용 설정됩니다.
overridePath: 불리언. true인 경우 호스트의 API 루트 엔드포인트가 API 사양이 아닌 URL 경로에 정의되어 있음을 나타냅니다. /v2 접두어가 누락된 비규격 OCI 레지스트리와 함께 사용할 수 있습니다. 기본값은 false입니다.
dialTimeout: 연결 시도가 완료되는 데 허용되는 최대 시간을 지정하는 기간 문자열입니다 (예: "30s"). 허용되는 최댓값은 "180s"입니다. 설정하지 않으면 containerd에서 기본값 "30s"을 설정합니다. 값은 s 접미사가 있는 초 단위의 십진수여야 합니다.
header: 레지스트리 호스트로 전송할 맞춤 HTTP 헤더 목록입니다.
- key: 헤더 키입니다.
- value: 헤더 값 목록입니다.
ca: 레지스트리 호스트의 인증 기관 (CA)에 대한 인증서 구성 목록입니다. 인증서의 보안 비밀을 만들고 필수 권한을 구성하려면 Secret Manager에 CA 공개 키 저장의 안내를 참고하세요.
- gcpSecretManagerSecretUri: CA 인증서를 포함하는 Secret Manager의 보안 비밀 URI입니다. 전역 보안 비밀과 리전 보안 비밀을 모두 지원합니다. 형식은 각각의 비밀 유형에 따라 다음과 같습니다.
  - 전역 보안 비밀 형식: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION
  - 리전 보안 비밀 형식: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION
client: 레지스트리 호스트에 인증하기 위한 클라이언트 인증서 및 키 쌍 목록입니다. 인증서의 보안 비밀을 만들고 필수 권한을 구성하려면 Secret Manager에 CA 공개 키 저장의 안내를 참고하세요.
- cert: 클라이언트 인증서 구성입니다.
- key: 클라이언트 비공개 키 구성입니다.

`writableCgroups`

워크로드가 하위 프로세스의 리소스를 관리할 수 있도록 /sys/fs/cgroup 파일 시스템을 읽기-쓰기 모드로 마운트합니다.

이 옵션은 GKE 버전 1.34.1-gke.2541000 이상에서 사용할 수 있습니다.

자세한 내용은 컨테이너의 쓰기 가능한 cgroup 구성을 참고하세요.

writableCgroups:
  enabled: true

새 클러스터에 containerd 구성 적용

이 섹션에서는 새 GKE 클러스터를 만들 때 containerd 구성 파일을 적용하는 방법을 보여줍니다.

다음 명령어를 실행하여 Autopilot 클러스터를 만듭니다.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

다음을 바꿉니다.

CLUSTER_NAME: 새 클러스터의 이름
LOCATION: 새 클러스터의 Compute Engine 위치
PATH_TO_CONFIG_FILE: 생성된 구성 파일의 경로(예: ~/containerd-configuration.yaml)

같은 옵션으로 gcloud container clusters create 명령어를 실행하여 새 표준 클러스터에서 containerd 구성을 사용 설정할 수 있습니다.

새 노드 풀에 containerd 구성 적용

다음 명령어를 사용하여 containerd 구성을 새 GKE 노드 풀에 적용할 수 있습니다.

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

다음을 바꿉니다.

NODE_POOL_NAME: 새 노드 풀의 이름입니다.
CLUSTER_NAME: 기존 클러스터의 이름입니다.
LOCATION: 새 노드 풀의 Compute Engine 위치
PATH_TO_CONFIG_FILE: 생성된 구성 파일의 경로(예: ~/containerd-configuration.yaml)

기존 클러스터에 containerd 구성 적용

이 섹션에서는 기존 클러스터와 노드에 containerd 구성을 적용하는 방법을 보여줍니다.

액세스 범위 확인

이 기능을 사용하려면 기존 클러스터에 cloud-platform 액세스 범위가 있어야 합니다. 이 섹션에서는 액세스 범위를 확인하고 새롭거나 수정된 비공개 레지스트리 구성 파일로 기존 클러스터를 업데이트하는 방법을 보여줍니다.

새 클러스터의 기본 액세스 범위에 대한 자세한 내용은 GKE의 액세스 범위를 참조하세요.

Autopilot 액세스 범위 확인

다음 명령어를 실행합니다.

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

클러스터에 https://www.googleapis.com/auth/cloud-platform 액세스 범위가 없으면 이 액세스 범위로 새 클러스터를 만듭니다.

표준 액세스 범위 확인

표준 클러스터 액세스 범위를 확인하려면 노드 풀을 확인합니다.

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --format='value[delimiter="\\n"](config.oauthScopes)'

NODE_POOL_NAME을 노드 풀의 이름으로 바꿉니다.

클러스터에 https://www.googleapis.com/auth/cloud-platform 액세스 범위가 없으면 cloud-platform 액세스 범위로 새 노드 풀을 만들고 기존 노드 풀을 삭제합니다.

구성 파일을 사용하도록 클러스터 업데이트

다음 명령어를 실행합니다.

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

표준 클러스터에서 노드 다시 만들기

표준 클러스터에서 자동 업그레이드를 사용하지 않는 경우에 노드 풀을 수동으로 다시 만들어 새 구성을 적용해야 합니다. 수동으로 노드 다시 만들기를 트리거하려면 클러스터를 이미 사용 중인 같은 GKE 버전으로 업그레이드합니다.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

VERSION을 클러스터에서 이미 사용 중인 같은 GKE 패치 버전으로 바꿉니다.

containerd 구성 옵션 중지

`privateRegistryAccessConfig` 사용 중지

다음 예시와 같이 구성 파일을 업데이트하여 privateRegistryAccessConfig에서 enabled: false를 지정하고 항목의 다른 모든 필드를 삭제합니다.
```
privateRegistryAccessConfig:
  enabled: false
```
업데이트된 구성 파일을 클러스터에 적용합니다. 자세한 내용은 기존 클러스터에 containerd 구성 적용을 참조하세요.

`registryHosts` 사용 중지

다음 예시와 같이 구성 파일을 업데이트하여 registryHosts 항목에 빈 배열을 지정합니다.
```
registryHosts: []
```
업데이트된 구성 파일을 클러스터에 적용합니다. 자세한 내용은 기존 클러스터에 containerd 구성 적용을 참조하세요.

GKE 노드에서 containerd 구성 맞춤설정 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

GKE의 containerd 구성 정보

제한사항

사용 가능한 containerd 구성 옵션

privateRegistryAccessConfig

registryHosts

writableCgroups

새 클러스터에 containerd 구성 적용

새 노드 풀에 containerd 구성 적용

기존 클러스터에 containerd 구성 적용

액세스 범위 확인

Autopilot 액세스 범위 확인

표준 액세스 범위 확인

구성 파일을 사용하도록 클러스터 업데이트

표준 클러스터에서 노드 다시 만들기

containerd 구성 옵션 중지

privateRegistryAccessConfig 사용 중지

registryHosts 사용 중지

GKE 노드에서 containerd 구성 맞춤설정

`privateRegistryAccessConfig`

`registryHosts`

`writableCgroups`

`privateRegistryAccessConfig` 사용 중지

`registryHosts` 사용 중지