이 페이지에서는 Google Distributed Cloud connected 버전 1.12.0 환경에서 구성 동기화 Fleet 패키지를 사용하는 방법을 설명합니다. Fleet 패키지는 Git 저장소를 클러스터 구성의 단일 정보 소스로 사용하는 도구입니다.
Distributed Cloud Connected의 Fleet 패키지는 표준 Google Kubernetes Engine 클러스터와 동일한 기본 기술과 명령어를 사용합니다. GKE 문서의 Fleet 패키지 배포 페이지에서는 Fleet 패키지를 만들고 관리하는 방법을 설명합니다. 이 페이지에서는 Distributed Cloud 연결 환경에 맞게 가이드를 조정하는 방법을 설명합니다.
다음 섹션에서는 Distributed Cloud Connected에서 다르게 해야 하는 작업과 GKE 문서에서 변경 없이 따를 수 있는 단계를 설명합니다.
요구사항
Distributed Cloud Connected에서 구성 동기화 Fleet 패키지를 사용하려면 다음 요구사항을 충족해야 합니다.
- 롤아웃 컨트롤러는 클라우드에 있으므로 공개 인터넷을 통해 Git 저장소에 연결할 수 있어야 합니다. 공개적으로 노출되지 않는 내부 또는 온프레미스 Git 서버는 지원되지 않습니다.
- Distributed Cloud Connected는 Google Cloud 서비스로 인증하기 위해 Fleet 워크로드 아이덴티티 제휴를 사용하는 것만 지원합니다. SSH 키나 쿠키와 같은 다른 구성 동기화 인증 방법은 클러스터와 버전이 지정된 번들 저장소 간의 연결에 지원되지 않습니다. 자세한 내용은 워크로드 아이덴티티 클러스터 인증을 참고하세요.
- Fleet의 모든 클러스터는 동일한 프로젝트에 있어야 합니다. Distributed Cloud Connected는 Fleet 관리를 위해 여러 프로젝트의 클러스터를 단일 중앙 프로젝트에 등록하는 것을 지원하지 않습니다.
- Kubernetes 매니페스트는 Distributed Cloud 연결 워크로드 제한사항을 준수해야 합니다. 이러한 제한사항을 위반하는 매니페스트는 클러스터 승인 컨트롤러에 의해 차단됩니다.
- Fleet 패키지에는 구성 동기화 버전 1.16.0 이상이 필요합니다.
시스템 동작
Distributed Cloud(연결형)의 Fleet 패키지에는 다음과 같은 동작이 있습니다.
- Fleet 패키지는 Kubernetes 매니페스트를 버전이 지정된 OCI 이미지로 변환합니다. 이러한 이미지는 프로젝트에 자동으로 생성되는 관리형 Artifact Registry 저장소인
fleet-packages에 저장됩니다. 클러스터는 일관되고 안정적인 전송을 위해 저장소에서 이러한 이미지를 직접 가져옵니다. - Fleet 패키지는 구성 동기화의 드리프트 수정 동작을 상속합니다. 클러스터의 리소스에 적용된 수동 변경사항은 버전이 지정된 OCI 번들과 일치하도록 자동으로 덮어쓰여집니다.
- Distributed Cloud 연결 클러스터가 생존 모드로 전환되면 구성 동기화 에이전트가 마지막으로 동기화된 구성을 로컬로 계속 적용합니다. 하지만 클라우드 연결이 복원될 때까지 새 출시 또는 플릿 패키지 업데이트는 일시중지됩니다.
- Fleet 패키지는 구성 동기화의 자동 리소스 가지치기 동작을 상속합니다. Git 저장소에서 새 태그를 만들고 새 태그로 Fleet 패키지 구성을 업데이트하여 동기화를 시작하면 Git 저장소에서 매니페스트를 삭제하는 경우 구성 동기화 에이전트가 클러스터에서 해당 리소스를 삭제합니다.
- 여러 Fleet 패키지가 동일한 리소스를 관리하는 경우 소유권 충돌이 발생합니다. 소유권 충돌이 있는 동안 Fleet 패키지를 삭제하려고 하면 삭제가 중단될 수 있습니다. 이 문제를 해결하려면 패키지를 삭제하기 전에 충돌하는 리소스를 삭제하도록 경쟁하는 Fleet 패키지 중 하나를 수정하세요.
Distributed Cloud Connected 기본 요건
Fleet 패키지 배포의 단계를 따르기 전에 Distributed Cloud 연결 환경과 사용자 권한이 올바르게 구성되어 있는지 확인하세요.
네트워킹 및 보안
네트워킹 환경은 다음 요구사항을 충족해야 합니다.
- VPC 서비스 제어. 프로젝트가 VPC 서비스 경계로 보호되는 경우 Cloud Build 및 Config Delivery 서비스 에이전트(예:
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 역할이 있어야 합니다.
- Config Delivery 관리자 (
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: 클러스터 전체에 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 Connected 조정 |
|---|---|
| Fleet에 클러스터 등록 | 이 단계 건너뛰기 Distributed Cloud 연결된 클러스터는 생성 시 프로젝트의 Fleet에 자동으로 등록됩니다. |
| 구성 동기화 설치 | 표준 단계를 따르되 전체 Fleet에 설치 (Fleet 기본값) 방법을 사용하는 것이 좋습니다. Google Cloud 콘솔의 허브 또는 Fleet 설정에서 이 메서드를 구성합니다.
이 구현을 통해 영역에 있는 기존 또는 향후 Distributed Cloud 연결 노드가 구성 동기화 에이전트를 자동으로 수신합니다. 인증 구성원 유형으로 워크로드 아이덴티티를 선택해야 합니다. 워크로드 아이덴티티에 사용하는 서비스 계정에는 구성 동기화 에이전트가 관리형 fleet-packages 저장소에서 매니페스트 번들을 가져올 수 있도록 프로젝트에 대한 roles/artifactregistry.reader 역할이 있어야 합니다. |
| 서비스 계정 만들기 | 안내에 따라 Cloud Build의 서비스 계정을 만들고 필요한 권한을 부여합니다. 서비스 계정은 Fleet 패키지와 동일한 프로젝트에 있어야 합니다. 다음 명령어를 사용하는 것이 좋습니다.
|
| 멤버십 이름 확인 | 명령어에서 MEMBERSHIP_NAME를 요청하는 경우 Distributed Cloud 연결 클러스터의 이름을 사용합니다. gcloud container fleet memberships list 명령어를 실행하여 클러스터 이름을 찾을 수 있습니다. |
| 클러스터 식별 | Fleet 패키지로 클러스터를 타겟팅하기 전에 워크로드에 HugePages 또는 SR-IOV와 같은 호스트 수준 네트워킹 구성이 필요한 경우 클러스터의 모든 노드에 NodeSystemConfigUpdate 리소스를 적용하고 확인합니다.
|
| Git 태그 식별 | 롤아웃 컨트롤러에는 Git 태그가 전체 시맨틱 버전 형식 (major.minor.patch)이어야 합니다. 예를 들어 v1.0.0은 유효하지만 v1은 유효하지 않습니다. |
| 특정 클러스터 타겟팅하기 | 클러스터는 자동 등록되지만 라벨 선택기를 사용하여 클러스터의 하위 집합을 타겟팅하려면 클러스터 멤버십에 라벨을 수동으로 추가해야 합니다. |
| 배포 전략 | 라벨과 변형을 사용하여 특정 클러스터를 타겟팅합니다. Distributed Cloud connected의 경우 변형 템플릿에 사용되는 프로젝트 및 위치와 같은 멤버십 메타데이터 변수는 Distributed Cloud connected 클러스터와 연결된 클라우드 측 리소스를 참조합니다. 다음 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 패키지의 이름입니다.
빌드가 실패하거나 멈추면 gcloud container fleet packages list 명령어의 출력에서 Cloud Build 작업의 스트리밍 로그 링크를 확인할 수 있습니다. 출시가 PENDING 또는 STALLED 상태로 유지되면 Distributed Cloud connected 문제 해결에 설명된 대로 Distributed Cloud connected 하드웨어 연결을 확인하세요.
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 객체 모니터링을 참고하세요.
출력에서 특정 오류 코드를 디코딩하는 데 도움이 필요하면 구성 동기화 오류 참조를 참고하세요.