이 페이지에서는 Google Distributed Cloud(연결형) 환경에서 구성 동기화 Fleet 패키지를 사용하는 방법을 설명합니다. Fleet 패키지는 Git 저장소를 클러스터 구성의 단일 정보 소스로 사용하는 도구입니다.
Distributed Cloud(연결형)의 Fleet 패키지는 표준 Google Kubernetes Engine 클러스터와 동일한 기본 기술 및 명령어를 사용합니다. GKE 문서의 Fleet 패키지 배포 페이지에서는 Fleet 패키지를 만들고 관리하는 방법을 설명합니다. 이 페이지에서는 Distributed Cloud(연결형) 환경에 맞게 가이드를 조정하는 방법을 설명합니다.
다음 섹션에서는 Distributed Cloud(연결형)에서 다르게 해야 하는 작업과 변경 없이 따를 수 있는 GKE 문서의 단계를 설명합니다.
요구사항
Distributed Cloud(연결형)에서 구성 동기화 Fleet 패키지를 사용하려면 다음과 같은 요구사항이 있습니다.
- 출시 컨트롤러가 클라우드에 있으므로 공개 인터넷을 통해 Git 저장소에 연결할 수 있어야 합니다. 공개적으로 노출되지 않는 내부 또는 온프레미스 Git 서버는 지원되지 않습니다.
- Distributed Cloud(연결형)는 Fleet 워크로드 아이덴티티 제휴를 사용하여 서비스로 인증하는 것만 지원합니다. Google Cloud SSH 키 또는 쿠키와 같은 다른 구성 동기화 인증 방법은 클러스터와 버전 관리 번들 저장소 간의 연결에 지원되지 않습니다. 자세한 내용은 워크로드 아이덴티티 클러스터 인증을 참조하세요.
- Fleet의 모든 클러스터는 동일한 프로젝트에 있어야 합니다. Distributed Cloud(연결형)는 Fleet 관리를 위해 여러 프로젝트의 클러스터를 단일 중앙 프로젝트에 등록하는 것을 지원하지 않습니다.
- Kubernetes 매니페스트는 Distributed Cloud(연결형) 워크로드 제한사항을 준수해야 합니다. 이러한 제한사항을 위반하는 매니페스트는 클러스터 승인 컨트롤러에 의해 차단됩니다.
- Fleet 패키지에는 구성 동기화 버전 1.16.0 이상이 필요합니다.
시스템 동작
Distributed Cloud(연결형)의 Fleet 패키지에는 다음과 같은 동작이 있습니다.
- Fleet 패키지는 Kubernetes 매니페스트를 버전 관리 OCI 이미지로 변환합니다. 이러한 이미지는 프로젝트에서 자동으로 생성되는
fleet-packages라는 관리형 Artifact Registry 저장소에 저장됩니다. 클러스터는 일관되고 안정적인 전달을 보장하기 위해 저장소에서 이러한 이미지를 직접 가져옵니다. - Fleet 패키지는 구성 동기화의 드리프트 수정 동작을 상속합니다. 클러스터의 리소스에 수동으로 변경한 내용은 버전 관리 OCI 번들과 일치하도록 자동으로 덮어쓰입니다.
- Distributed Cloud(연결형) 클러스터가 생존 가능성 모드로 전환되면 구성 동기화 에이전트는 마지막으로 성공적으로 동기화된 구성을 로컬에서 계속 적용합니다. 하지만 클라우드 연결이 복원될 때까지 Fleet 패키지의 새로운 출시 또는 업데이트는 일시중지됩니다.
- Fleet 패키지는 구성 동기화의 자동 리소스 프루닝 동작을 상속합니다. Git 저장소에서 새 태그를 만들고 새 태그로 Fleet 패키지 구성을 업데이트하여 동기화를 시작하면 Git 저장소에서 매니페스트를 삭제할 때 구성 동기화 에이전트가 클러스터에서 해당 리소스를 삭제합니다.
- 여러 Fleet 패키지가 동일한 리소스를 관리하는 경우 소유권 충돌이 발생합니다. 소유권 충돌이 있는 동안 Fleet 패키지를 삭제하려고 하면 삭제가 중단될 수 있습니다. 이 문제를 해결하려면 패키지를 삭제하기 전에 충돌하는 Fleet 패키지 중 하나를 수정하여 충돌하는 리소스를 삭제하세요.
Distributed Cloud(연결형) 기본 요건
Fleet 패키지 배포의 단계를 따르기 전에 Distributed Cloud(연결형) 환경 및 사용자 권한이 올바르게 구성되어 있는지 확인하세요.
네트워킹 및 보안
네트워킹 환경은 다음 요구사항을 충족해야 합니다.
- VPC 서비스 제어. 프로젝트가 VPC 서비스 경계로 보호되는 경우 Cloud Build 및 구성 전달 서비스 에이전트(예:
service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com)가 경계를 넘어 Artifact Registry에서 이미지를 가져올 수 있도록 승인되었는지 확인합니다. 자세한 내용은 VPC 서비스 제어 통합 구성을 참조하세요. - 이그레스 액세스. Distributed Cloud(연결형) 클러스터는
us-central1-docker.pkg.dev에 대한 이그레스 액세스 권한이 있어야 합니다. Fleet 패키지는 매니페스트 번들을 Artifact Registry에 OCI 이미지로 저장합니다. 클러스터는 Artifact Registry에서 이러한 이미지를 직접 가져올 수 있어야 합니다.
저장소 설정
매니페스트 번들이 포함된 Artifact Registry 저장소는 Fleet 패키지와 동일한 프로젝트에 있어야 하며 us-central1에 있어야 합니다.
필수 권한
Distributed Cloud(연결형) 환경에서 단계를 완료하려면 프로젝트에 다음 IAM 역할이 있어야 합니다.
- 구성 전달 관리자 (
roles/configdelivery.admin): Fleet 패키지 및 출시를 만들고 관리하는 데 필요합니다. - Developer Connect 관리자 (
roles/developerconnect.admin): 저장소 연결을 만들고 관리하는 데 필요합니다. - 프로젝트 IAM 관리자 (
roles/resourcemanager.projectIamAdmin): 서비스 계정에 필요한 역할을 부여하는 데 필요합니다.
역할 부여에 대한 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참조하세요.
필수 API
저장소 연결 및 Distributed Cloud(연결형) 클러스터와의 보안 통신을 위해 API를 사용 설정해야 합니다. 필요한 API를 사용 설정하려면 다음
gcloud services enable
명령어를 실행하세요.
gcloud services enable anthosconfigmanagement.googleapis.com \
configdelivery.googleapis.com \
cloudbuild.googleapis.com \
connectgateway.googleapis.com \
developerconnect.googleapis.com \
artifactregistry.googleapis.com
이러한 API는 다음 구성요소에 필요합니다.
anthosconfigmanagement.googleapis.com: 클러스터에서 구성 동기화 에이전트를 관리합니다.configdelivery.googleapis.com: 클러스터 Fleet 전체에서 Kubernetes 리소스 출시를 조정합니다.cloudbuild.googleapis.com: Git에서 Kubernetes 매니페스트를 가져와 버전 관리 번들로 패키징합니다.connectgateway.googleapis.com: 구성 전달 서비스와 Distributed Cloud(연결형) 클러스터 간에 보안 연결을 제공합니다.developerconnect.googleapis.com: 외부 Git 저장소 호스트에 대한 보안 연결을 사용 설정합니다.artifactregistry.googleapis.com: 버전 관리 패키지 번들을 프로젝트에 OCI 이미지로 저장합니다.
기본 환경 설정
Fleet 패키지의 구성 전달 API는 us-central1에서만 지원됩니다. 명령어가 올바르게 라우팅되도록 하려면
gcloud config set 명령어를 사용하여 기본 프로젝트 및 위치를 설정하세요.
기본 프로젝트를 설정합니다.
gcloud config set project PROJECT_ID
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.Fleet 패키지의 기본 위치를 설정합니다. Fleet 패키지와 함께 사용되는 모든 Cloud Build 저장소 연결은
us-central1리전에 있어야 합니다.gcloud config set config_delivery/location us-central1
절차상의 차이점
다음 표를 사용하여 Fleet 패키지 배포 의 단계를 Distributed Cloud(연결형) 환경에 적용하는 방법을 알아보세요.
| 표준 단계 | Distributed Cloud(연결형) 조정 |
|---|---|
| Fleet에 클러스터 등록 | 이 단계는 건너뜁니다. Distributed Cloud(연결형) 클러스터는 생성 시 프로젝트의 Fleet에 자동으로 등록됩니다. |
| 구성 동기화 설치 | 표준 단계를 따르되
전체 Fleet에 설치 (Fleet 기본값) 방법을 사용하는 것이 좋습니다. 콘솔의 허브 또는 Fleet 설정에서 이
메서드를 구성합니다. Google Cloud
이 구현을 통해 영역의 기존 또는 향후
Distributed Cloud(연결형) 노드가 구성 동기화 에이전트를 자동으로
수신합니다. 인증 구성원 유형의 경우 워크로드 아이덴티티를 선택해야 합니다. 워크로드 아이덴티티에 사용하는 서비스 계정에는 구성 동기화 에이전트가 관리형 fleet-packages 저장소에서 매니페스트 번들을 가져올 수 있도록 프로젝트에 roles/artifactregistry.reader 역할이 있어야 합니다. |
| 서비스 계정 만들기 | 안내에 따라 Cloud Build의 서비스 계정을 만들고 필요한 권한을 부여합니다. 서비스 계정은 Fleet 패키지와 동일한 프로젝트에 있어야 합니다. 다음 명령어를 사용하는 것이 좋습니다.
|
| 멤버십 이름 식별 | 명령어에서 MEMBERSHIP_NAME을 요청하면 Distributed Cloud(연결형) 클러스터의 이름을 사용합니다. 명령어를 실행하여 클러스터 이름을 찾을 수 있습니다.gcloud container fleet memberships list |
| 클러스터 식별 | 워크로드에 HugePages 또는 SR-IOV와 같은 호스트 수준 네트워킹 구성이 필요한 경우 Fleet 패키지로 클러스터를 타겟팅하기 전에 클러스터의 모든 노드에 NodeSystemConfigUpdate 리소스를 적용하고 확인합니다.
|
| Git 태그 식별 | 출시 컨트롤러에는 Git 태그가 전체 시맨틱
버전 형식 (major.minor.patch)이어야 합니다. 예를 들어
v1.0.0은 유효하지만 v1은 유효하지 않습니다. |
| 특정 클러스터 타겟팅 | 클러스터는 자동으로 등록되지만 라벨 선택기를 사용하여 클러스터 하위 집합을 타겟팅하려면 클러스터 멤버십에 라벨을 수동으로 추가해야 합니다. |
| 배포 전략 | 라벨 및 변형을 사용하여 특정 클러스터를 타겟팅합니다. Distributed Cloud(연결형)의 경우 변형 템플릿에 사용되는 프로젝트 및 위치와 같은 멤버십 메타데이터 변수는 Distributed Cloud(연결형) 클러스터와 연결된 클라우드 측 리소스를 참조합니다. 다음 Distributed Cloud 관련 멤버십 메타데이터는 변형 템플릿에서 사용할 수 있습니다.
|
공유 절차
다음 운영 태스크의 경우 명령어 구문과 서비스 동작은 Distributed Cloud(연결형)와 표준 GKE에서 동일합니다. 이 안내를 따를 때는 이 문서의 절차상의 차이점 섹션에 있는 표에 정의된 설정과 값을 사용하세요.
- Fleet 패키지 만들기:
FleetPackage리소스를 정의하여 구성을 가져오고 배포합니다. - Fleet 패키지 업데이트: 패키지를 수정하여 변경사항을 출시하거나 설정을 업데이트합니다.
- Fleet 패키지 출시 관리: 활성 출시를 일시중지, 재개 또는 중단합니다.
- 리소스 번들 및 출시 검사:
변형 생성 및 버전 관리를 디버그합니다. 리소스 번들은 구성의 컨테이너이고 출시는 이러한 번들의 버전 관리 인스턴스입니다. Distributed Cloud(연결형) 하드웨어에 대한 전달이 성공했는지 확인하려면
gcloud container fleet memberships get-credentials명령어를 사용하여 클러스터에 대한 액세스 권한을 얻은 다음,kubectl을(를) 사용하여 클러스터의RootSync상태를 검사합니다. - Fleet 패키지 삭제:
Fleet 패키지 및 관리형 리소스를 삭제합니다. 완전히 삭제하려면 Fleet 패키지와 연결된 관리형
RootSync객체가 클러스터에서 삭제되었는지 확인합니다.
모니터링 및 문제 해결
배포를 더 효과적으로 모니터링하려면 출시 중에 자세한 상태 메시지를 가져오기 위해 gcloud 명령어와 함께 --format 플래그를 사용하세요.
예를 들어 다음
gcloud container fleet packages rollouts describe
명령어를 실행하여 Fleet의 모든 클러스터에 대한 자세한 상태 메시지를 확인합니다.
gcloud container fleet packages rollouts describe ROLLOUT_NAME \
--fleet-package=FLEET_PACKAGE_NAME \
--format=json
다음 값을 바꿉니다.
ROLLOUT_NAME: 출시 이름입니다.FLEET_PACKAGE_NAME: Fleet 패키지의 이름입니다.
빌드가 실패하거나 중단되면 Cloud Build 작업의 스트리밍 로그
링크를
gcloud container fleet packages list
명령어의 출력에서 찾을 수 있습니다. 출시가 PENDING 또는 STALLED 상태로 유지되면
Distributed Cloud(연결형) 문제 해결에 설명된 대로
Distributed Cloud(연결형) 하드웨어 연결을 확인합니다.
Cloud Build와 관련된 오류 진단에 대한 자세한 내용은 빌드 오류 문제 해결을 참조하세요.
클러스터 내 동기화 상태 확인
클러스터가 Fleet 패키지와 성공적으로 동기화되고 있는지 확인하려면 클러스터의 RootSync 리소스를 검사합니다. 클러스터의 RootSync 객체 이름은 패키지에 선택한 FLEET_PACKAGE_NAME과 동일합니다.
상태를 확인하려면 다음 명령어를 실행하세요.
kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system
동기화가 성공하면 SYNCED 상태가 표시됩니다. Error 상태가 표시되면 자세한 내용을 보려면 다음 명령어를 실행하세요.
kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system
자세한 내용은 GKE 문서의 RootSync 및 RepoSync 객체 모니터링 을 참조하세요.
출력에서 특정 오류 코드를 디코딩하는 데 도움이 필요하면 구성 동기화 오류 참조를 확인하세요.