이 페이지의 일부 또는 모든 정보는 S3NS의 Cloud de Confiance에 적용되지 않을 수 있습니다. 자세한 내용은 Google Cloud와의 차이점을 참조하세요.

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

Fleet 패키지 배포

이 페이지에서는 구성 동기화 Fleet 패키지를 사용하여 Fleet에 등록된 클러스터에 Kubernetes 리소스를 배포하는 방법을 설명합니다. Fleet 패키지를 만들고 배포한 후 Fleet에 새 클러스터를 추가하면 Fleet 패키지가 Git 저장소의 Kubernetes 구성 파일을 새 클러스터에 자동으로 배포합니다.

FleetPackage는 Kubernetes 원시 매니페스트를 클러스터 Fleet에 배포하는 선언적 API입니다. Fleet 패키지로 배포하려는 Kubernetes 리소스는 이미 하이드레이션 (WET)되어 있어야 합니다.

시작하기 전에

Fleet에 배포하려는 Kubernetes 리소스가 포함된 Git 저장소를 만들거나 액세스 권한이 있는지 확인합니다.
gcloud 및 nomos 명령어를 제공하는 Google Cloud CLI를 설치하고 초기화합니다. Cloud Shell을 사용하는 경우 Google Cloud CLI가 사전 설치됩니다. 이전에 Google Cloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.

참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.

구성 동기화 (anthosconfigmanagement) API와 ConfigDelivery API를 사용 설정합니다.

gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

기본 위치를 설정합니다.
```
gcloud config set config_delivery/location us-central1
```
참고: ConfigDelivery API에 사용할 수 있는 유일한 위치는 us-central1입니다.
기본 프로젝트를 설정합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID를 Fleet 호스트 프로젝트의 프로젝트 ID로 바꿉니다.
클러스터가 Fleet에 등록되어 있는지 확인합니다.
Cloud Build 저장소를 사용하여 GitHub 또는 GitLab과 같은 지원되는 제공업체에 연결합니다. Fleet 패키지를 사용하는 경우 동기화하려는 저장소당 한 번만 Cloud Build를 설정하면 됩니다.

중요: Git 연결과 FleetPackage이 동일한 리전에 있어야 하므로 Cloud Build 연결은 us-central1에 있어야 합니다. ConfigDelivery API는 us-central1에서만 사용할 수 있습니다.

클러스터 요구사항 검토

클러스터에 구성 동기화를 설치하기 전에 클러스터 구성 권장사항 및 요구사항을 검토하세요.

개발 환경 준비

구성 동기화 Fleet 패키지용 환경을 준비하려면 클러스터를 등록하는 사용자에게 필요한 IAM 역할을 부여하세요.

구성 동기화 설치

Cloud de Confiance 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치할 수 있습니다.

콘솔

구성 동기화를 설치하려면 모든 클러스터를 Fleet에 등록해야 합니다. Cloud de Confiance 콘솔에서 구성 동기화를 설치할 때 개별 클러스터를 선택하면 해당 클러스터가 Fleet에 자동으로 등록됩니다.

Cloud de Confiance 콘솔에서 기능 섹션 아래의 구성 페이지로 이동합니다.

구성으로 이동

구성 동기화 설치를 클릭합니다.
설치 옵션에서 전체 Fleet에 구성 동기화 설치(권장)를 선택합니다.
구성 동기화 설치를 클릭합니다. 몇 분 후 설정 탭에서 Fleet에 있는 클러스터의 상태 열에 사용 설정됨이 표시됩니다.

gcloud

ConfigManagement Fleet 기능을 사용 설정합니다.

gcloud beta container fleet config-management enable

구성 동기화를 사용 설정하려면 다음 콘텐츠로 apply-spec.yaml이라는 파일을 만듭니다.
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
apply-spec.yaml 파일을 적용합니다.
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml
```
MEMBERSHIP_NAME을 클러스터를 등록할 때 선택한 Fleet 멤버십 이름으로 바꿉니다. 멤버십 이름을 찾으려면 gcloud container fleet memberships list 명령어를 실행합니다.

Cloud Build의 서비스 계정 만들기

Fleet 패키지는 Cloud Build를 사용하여 Git 저장소에서 Kubernetes 리소스를 가져와 클러스터에 배포합니다. Cloud Build에는 이 작업을 실행할 권한이 있는 서비스 계정이 필요합니다. 서비스 계정을 만들고 필요한 권한을 부여하려면 다음 단계를 완료합니다.

서비스 계정을 만듭니다.
```
gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
```
SERVICE_ACCOUNT_NAME을 서비스 계정 이름으로 바꿉니다. 이름은 6~30자(영문 기준) 사이의 영숫자 ID여야 합니다(예: my-service-account). 서비스 계정을 만든 후에는 이름을 변경할 수 없습니다.

리소스 번들 게시자 역할에 대한 IAM 정책 바인딩을 추가합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/configdelivery.resourceBundlePublisher'

메시지가 표시되면 정책 조건으로 None을 선택합니다.

로그 작성자 역할에 대한 IAM 정책 바인딩을 추가합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/logging.logWriter'

메시지가 표시되면 정책 조건으로 None을 선택합니다.

ArtifactRegistry Writer 역할의 IAM 정책 바인딩을 추가합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/artifactregistry.writer'

메시지가 표시되면 정책 조건으로 None을 선택합니다.

Fleet 패키지 만들기

Fleet 패키지를 만들려면 Cloud Build에 연결된 Kubernetes 리소스가 있는 저장소를 가리키는 FleetPackage 사양을 정의합니다. 그런 다음 Git에서 리소스를 가져와 Fleet 전체에 배포하는 FleetPackage를 적용합니다.

다음 콘텐츠로 fleetpackage-spec.yaml이라는 파일을 만듭니다.
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED
```
다음을 바꿉니다.
- CONNECTION_NAME: Git 호스트를 Cloud Build에 연결할 때 선택한 이름입니다. gcloud builds connections list를 실행하거나 Cloud de Confiance 콘솔에서 저장소 페이지를 열어 프로젝트의 모든 Cloud Build 연결을 볼 수 있습니다.
  
  저장소 페이지 열기
- REPOSITORY_NAME: 저장소 이름. Cloud Build 연결을 설정할 때 입력한 값과 동일해야 합니다.
- TAG: 저장소의 Git 태그입니다. 형식은 주요 버전, 부 버전, 패치 번호가 포함된 전체 시맨틱 버전이어야 합니다. 예를 들어 v1.0.0은 유효한 태그이지만 v1 또는 v1.0은 잘못된 태그입니다.
- CONFIG_FILE_PATH: 저장소에 있는 Kubernetes 리소스의 경로입니다. 파일이 저장소의 루트에 있는 경우 이 필드를 생략할 수 있습니다.
- MAX_CLUSTERS: 한 번에 Kubernetes 리소스를 배포할 최대 클러스터 수입니다. 예를 들어 이를 1으로 설정하면 리소스 번들이 한 번에 하나의 클러스터에 배포됩니다.
  
  구성할 수 있는 모든 필드의 전체 목록은 FleetPackage 참조 문서를 참고하세요.

Fleet 패키지를 만듭니다.

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

FLEET_PACKAGE_NAME을 플릿 패키지 출시의 이름으로 바꿉니다.

Fleet 패키지가 생성되었는지 확인합니다.
```
gcloud container fleet packages list
```
출력에 빌드 트리거 상태가 나열됩니다. 몇 초 후 MESSAGE 필드가 다음과 유사한 출력으로 업데이트됩니다.
```
MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
```
제공된 링크를 클릭하면 Cloud Build 작업의 스트리밍 로그를 볼 수 있습니다. Cloud Build에서 빌드 트리거를 처리하는 데 몇 분 정도 걸릴 수 있습니다.

빌드 트리거가 성공하면 Fleet 패키지가 Fleet 전체에서 Kubernetes 리소스를 출시하기 시작합니다.

빌드 트리거가 성공적으로 완료되면 gcloud container fleet packages list 출력은 다음과 비슷합니다.

NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621

Fleet 패키지가 Fleet 전체에서 Kubernetes 리소스를 출시하기 시작합니다.

이제 Fleet 패키지를 배포했으므로 Fleet에 새 클러스터를 추가하면 Fleet 패키지에 정의된 Kubernetes 리소스가 새 클러스터에 자동으로 배포됩니다.

Fleet 패키지 업데이트

다음 예와 같이 설정 변경 또는 함대 패키지에서 배포하는 리소스 변경을 위해 함대 패키지를 업데이트할 수 있습니다.

maxConcurrent 필드의 값을 변경하여 출시 전략을 변경합니다.
state: SUSPENDED를 설정하여 차량 패키지를 일시적으로 중지합니다. 함대 패키지가 정지되면 진행 중인 출시는 계속됩니다. 상태를 다시 ACTIVE로 변경할 때까지는 새로운 출시가 생성되거나 예약되지 않습니다.
tag 필드를 업데이트하여 다른 Git 태그에서 가져오도록 함으로써 Fleet 패키지에서 배포하는 Kubernetes 리소스를 업데이트합니다.

Fleet 패키지를 업데이트하려면 다음 단계를 완료하세요.

변경사항으로 FleetPackage 사양을 업데이트합니다.
Fleet 패키지를 업데이트합니다.
```
gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
변경사항이 적용되어 클러스터로 출시되기까지 몇 분 정도 걸릴 수 있습니다.

Fleet 패키지 출시 관리

Fleet 패키지 배포 진행 상황을 모니터링하고 활성 출시를 관리할 수 있습니다. 함대 패키지가 변경되면 새 출시가 자동으로 생성됩니다. 다음 명령어를 사용하면 출시에 관한 자세한 정보를 확인할 수 있습니다. 예를 들어 배포 문제를 디버그해야 하는 경우 출시 세부정보를 검토하고 필요한 경우 출시를 일시중지하거나 취소할 수 있습니다.

출시를 나열하면 출시가 실패할 수 있는 오류를 비롯하여 패키지에 연결된 모든 출시의 상태를 확인할 수 있습니다. 출시를 나열하고 상태를 보려면 다음 명령어를 실행합니다.

gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME

다음과 유사한 결과가 출력됩니다.

ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED

출시를 설명하면 타겟팅된 각 클러스터의 상태와 클러스터별 오류를 비롯한 특정 출시에 관한 세부정보를 확인할 수 있습니다. 출시를 설명하려면 다음 명령어를 실행합니다.

gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

ROLLOUT_NAME을 출시 이름으로 바꿉니다. 이전 단계의 list 명령어에서 전체 출시 이름을 가져올 수 있습니다.

다음과 유사한 결과가 출력됩니다.

CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists

다음 명령어를 실행하여 활성 출시를 관리할 수 있습니다.
- 롤아웃을 일시중지하면 진행 중인 롤아웃이 SUSPENDED 상태가 됩니다. 진행 중인 패키지 업데이트는 계속되고 추가 패키지 업데이트는 예약되지 않습니다. 출시를 일시중지하려면 다음 명령어를 실행합니다.
```
gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- 출시를 재개하면 SUSPENDED 출시가 IN_PROGRESS 상태로 다시 변경됩니다. 패키지 업데이트가 계획대로 타겟 클러스터에 배포됩니다. 출시를 재개하려면 다음 명령어를 실행합니다.
```
gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- 진행 중인 출시를 취소하면 출시가 즉시 종료되어 ABORTED 상태가 됩니다. 출시의 일부로 계획된 대기 중인 패키지 업데이트가 모두 취소됩니다. 출시를 취소하려면 다음 명령어를 실행합니다.
```
gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```

라벨을 사용하여 여러 클러스터에 배포

라벨은 객체에 연결하는 키-값 쌍입니다. Fleet 패키지는 Fleet 멤버십 라벨만 지원합니다. GKE 클러스터 라벨은 지원되지 않습니다.

라벨을 사용하여 Fleet 패키지를 Fleet의 클러스터 하위 집합에 배포할 수 있습니다.

멤버십 라벨 추가

멤버십 라벨을 추가하려면 다음 단계를 완료하세요.

Fleet의 멤버십 목록을 가져옵니다.

gcloud container fleet memberships list

멤버십에 라벨을 추가합니다.
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
다음을 바꿉니다.
- MEMBERSHIP_NAME: Fleet에 등록된 클러스터의 이름입니다.
- KEY 및 VALUE: 멤버십에 추가할 라벨입니다. 라벨이 있으면 해당 값이 수정됩니다. 그렇지 않으면 새 라벨이 생성됩니다. 키는 소문자로 시작해야 하고 하이픈 (-), 밑줄 (_), 소문자, 숫자만 포함할 수 있습니다. 값은 하이픈 (-), 밑줄 (_), 소문자, 숫자만 포함해야 합니다.
라벨을 추가하려는 각 멤버십에 대해 이 명령어를 반복합니다.

클러스터 하위 집합에 배포

키-값 쌍과 함께 target.fleet.selector.matchLabels 필드를 지정하여 클러스터의 하위 집합에 배포할 수 있습니다. 예를 들어 matchLabels을 country: "us"로 설정하면 Fleet 패키지 서비스는 "us"과 일치하는 country 라벨이 있는 클러스터에만 리소스를 배포합니다.

일부 클러스터에 Fleet 패키지를 배포하려면 다음 단계를 완료하세요.

라벨 선택기를 사용하여 FleetPackage 사양을 만들거나 업데이트합니다.

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

Fleet 패키지를 만들거나 업데이트합니다.

Fleet 패키지 만들기

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Fleet 패키지 업데이트

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

클러스터에 변이 리소스 배포

변형은 리소스의 다양한 버전입니다. 이러한 리소스는 클러스터의 위치, 프로젝트 또는 이름에 따라 값이 다를 수 있습니다. variantsPattern 및 variantNameTemplate 필드를 지정하여 변이 리소스를 다른 클러스터에 배포할 수 있습니다.

회원십 라벨 또는 위치, 프로젝트, 이름과 같은 기타 회원십 메타데이터를 사용하여 변형을 일치시킬 수 있습니다.

변형이 있는 Fleet 패키지를 배포하려면 다음 단계를 완료하세요.

옵션 세부정보를 사용하여 FleetPackage 사양을 만들거나 업데이트합니다.

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE

다음을 바꿉니다.

VARIANT_PATTERN: 변형의 패턴입니다(예: "variants/*.yaml" 또는 "us-*").
VARIANT_NAME_TEMPLATE : 위치, 프로젝트, 이름, 라벨 등 클러스터 멤버십 메타데이터를 포함하는 변수를 참조하여 대상 클러스터의 변형 이름을 결정하는 템플릿 문자열입니다. 자세한 예는 FleetPackage 참조 문서를 참고하세요.

Fleet 패키지를 만들거나 업데이트합니다.

Fleet 패키지 만들기

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Fleet 패키지 업데이트

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Fleet 패키지 삭제

Fleet 패키지를 삭제하면 다음 리소스도 삭제됩니다.

클러스터에 배포된 Kubernetes 리소스
Fleet 패키지 출시 내역

Fleet 패키지를 삭제하려면 다음 명령어를 실행합니다.

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

문제 해결

Cloud Build와 관련된 오류를 진단하고 해결하는 방법을 알아보려면 빌드 오류 문제 해결을 참고하세요.

다음 단계

FleetPackage 필드 참조 페이지를 참고하세요.