Fleet 패키지 정보

이 페이지에서는 Fleet 패키지, FleetPackage API, 구성 동기화와의 관계를 설명합니다.

FleetPackage는 Fleet 전반에서 패키지를 관리할 수 있는 선언적 API입니다. Fleet 패키지는 클러스터 구성을 정의하는 Kubernetes YAML 매니페스트 집합입니다. Fleet 패키지를 사용하면 한 번에 또는 점진적 출시를 통해 Fleet에 등록된 클러스터에 패키지를 배포할 수 있습니다.

각 FleetPackage 객체를 한 번 정의한 후 새 버전으로 패키지를 업데이트할 수 있습니다. 새 버전을 적용하면 Fleet 패키지 서비스가 이러한 변경사항을 선택하여 클러스터에 배포합니다.

이점

Fleet 패키지를 사용하여 Fleet에 등록된 클러스터에 Kubernetes 리소스를 배포합니다. Fleet 패키지를 만들고 적용하면 Fleet 패키지가 Git 저장소의 Kubernetes 구성 파일을 새 클러스터에 자동으로 배포합니다. Fleet 패키지는 자동 드리프트 수정과 같은 구성 동기화의 이점을 기반으로 하며 다음과 같은 고유한 이점을 제공합니다.

  • 리소스 출시 자동화: Fleet 패키지를 설정하면 Fleet 패키지 서비스가 가리키는 Kubernetes 리소스가 모든 클러스터에 자동으로 배포됩니다.

  • 새 클러스터 자동 구성: Fleet 패키지를 구성한 후 나중에 Fleet에 새 클러스터를 추가하면 Fleet 패키지로 정의된 리소스가 새 클러스터에 자동으로 배포됩니다.

  • 대규모 Kubernetes 구성 관리: 클러스터를 하나씩 관리하는 대신 Fleet 패키지를 사용하여 전체 클러스터 Fleet에 리소스를 배포합니다.

  • 잘못된 변경사항의 영향 최소화: 한 번에 리소스를 배포할 최대 클러스터 수를 선택합니다. 각 클러스터의 변경사항을 면밀히 모니터링하여 잘못된 변경사항이 전체 차량에 영향을 미치지 않도록 할 수 있습니다.

  • 구성 동기화 구성 간소화: Fleet 패키지는 Cloud Build를 사용하여 Git에 인증하므로 RootSync 또는 RepoSync 객체당 한 번이 아닌 프로젝트당 한 번 인증합니다.

다음 시나리오 중 하나 이상에 해당하는 경우 Fleet 패키지 대신 RootSync 또는 RepoSync 객체와 함께 구성 동기화를 사용하는 것이 좋습니다.

  • 소수의 클러스터를 관리합니다.

  • 라벨 및 변형을 사용하여 Fleet 패키지 API에서 제공하는 것 이상으로 리소스가 클러스터에 배포되는 방식을 더 세밀하게 제어해야 합니다.

요구사항 및 제한사항

  • 함대 패키지를 구성할 때는 Git 저장소만 정보 소스로 지원됩니다.

  • Git에 저장된 Kubernetes 리소스는 리소스의 최종 상태를 나타내야 합니다. Git에 저장된 리소스를 변환하는 추가 오버레이는 지원되지 않습니다. 이러한 리소스의 차이점에 대한 자세한 내용은 권장사항: WET 저장소 만들기를 참고하세요.

  • FleetPackage API는 us-central1 리전에서만 사용할 수 있습니다. 서로 다른 리전의 클러스터에 배포할 수는 있지만 us-central1에서 Cloud Build를 설정하고 gcloud CLI를 구성해야 합니다.

  • 프로젝트당 리전별 최대 Fleet 패키지 수는 300개입니다.

아키텍처

FleetPackage API를 사용하여 클러스터 Fleet에 Kubernetes 매니페스트를 배포할 수 있습니다. FleetPackage API는 Cloud Build를 사용하여 Git 저장소에서 Kubernetes 리소스를 동기화하고 가져옵니다. 그러면 Fleet 패키지 서비스가 이러한 리소스를 클러스터에 배포합니다.

Git에서 클러스터 Fleet으로 동기화되는 Kubernetes 리소스의 흐름을 보여주는 다이어그램

변형 생성 방식

Fleet 패키지는 변형 시스템을 사용하여 동일한 Git 저장소에서 Fleet 내의 여러 클러스터 또는 클러스터 그룹에 다양한 Kubernetes 리소스 구성을 배포합니다.

FleetPackage 사양에는 변수의 동작을 제어하는 두 가지 필드가 있습니다.

  1. resourceBundleSelector.cloudBuildRepository.variantsPattern: Git 저장소에서 파일과 디렉터리를 찾는 데 사용되는 glob 패턴입니다 (지정된 path 또는 path가 생략된 경우 저장소 루트 아래). 이 패턴은 어떤 파일이나 디렉터리가 변형이 되고 어떤 콘텐츠가 포함되는지 결정합니다.
  2. variantSelector.variantNameTemplate: Fleet의 각 클러스터를 variantsPattern에서 생성된 변형 이름 중 하나에 매핑하는 표현식입니다. 이 선택은 클러스터의 Fleet 멤버십 메타데이터를 기반으로 합니다.

variantsPattern 일치

variantsPattern 필드는 저장소에 저장된 구성에서 변형을 생성하는 방법을 지정하는 데 필요합니다. 매칭은 다음 논리를 사용합니다.

  • 파일 일치: 패턴이 YAML 파일과 일치하면 변형이 생성됩니다.

    • 변형 이름: 확장자가 없는 파일 이름입니다 (예: prod-config.yaml는 변형 prod-config이 됨).
    • 대안 콘텐츠: 이 단일 파일의 콘텐츠입니다.

  • 디렉터리 일치: 패턴이 디렉터리와 일치하면 변형이 생성됩니다.

    • 변형 이름: 디렉터리 이름입니다 (예: 디렉터리 dev는 변형 dev가 됨).
    • 변형 콘텐츠: 이 디렉터리와 모든 하위 디렉터리 내에서 재귀적으로 발견된 모든 YAML 파일의 조합입니다.

파일 일치 패턴에는 다음과 같은 제한사항이 있습니다.

  • 재귀 (이중) 와일드 카드는 사용할 수 없습니다. ** 패턴은 지원되지 않습니다.
  • 패턴에 점 (.) 문자가 포함된 경우 영숫자 문자가 뒤따라야 합니다.
  • 패턴에는 작은따옴표 (')를 포함할 수 없습니다.
  • 변형 이름은 고유해야 합니다. 패턴이 이름이 같은 여러 파일 (예: app1/deploy.yaml 및 app2/deploy.yaml)과 일치하는 경우 두 파일 모두 deploy라는 변형을 만들려고 시도하여 이름 충돌이 발생합니다.

예를 들어 다음과 같은 구조의 저장소를 생각해 보겠습니다.

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

예를 들어 Fleet 패키지 사양에 정의된 파일 또는 디렉터리 일치 유형에 따라 다른 파일을 일치시켜 클러스터에 동기화할 수 있습니다.

  • variantsPattern: "*": common-ingress.yaml, us-central1-a, us-central1-b와 일치합니다. 변형을 생성합니다.

    • common-ingress (파일에서)
    • us-central1-a (해당 폴더 내의 모든 YAML 파일 결합)
    • us-central1-b (해당 폴더 내의 모든 YAML 결합)

  • variantsPattern: "*.yaml": common-ingress.yaml와 일치합니다. 변형을 생성합니다.

    • common-ingress

  • variantsPattern: "us-*": us-central1-a 및 us-central1-b과 일치합니다. 변형을 생성합니다.

    • us-central1-a
    • us-central1-b

  • variantsPattern: "us-central1-b/*.yaml": us-central1-b/gke-1.yaml 및 us-central1-b/blue-green.yaml과 일치합니다. 변형을 생성합니다.

    • gke-1
    • blue-green

variantNameTemplate 일치

변형이 정의되면 variantSelector 섹션의 variantNameTemplate 필드에 따라 각 클러스터에 적용되는 변형이 결정됩니다. 템플릿은 변수를 사용하여 다음 함대 멤버십 메타데이터에 액세스할 수 있습니다.

  • ${membership.name}: 클러스터의 Fleet 멤버십 이름입니다.
  • ${membership.location}: Fleet 멤버십 위치입니다.
  • ${membership.project}: Fleet 멤버십 프로젝트입니다.
  • ${membership.labels['KEY']}: 차량 멤버십의 라벨 KEY 값입니다.

예를 들어 라벨을 사용하여 변형을 일치시키는 다음 시나리오를 고려해 보세요.

  • variantNameTemplate: "${membership.labels['env']}": env: prod 라벨이 지정된 클러스터는 prod라는 변형에 동기화됩니다.
  • variantNameTemplate: "${membership.location}": 클러스터가 위치와 일치하는 변형 (예: us-central1-a)에 동기화됩니다.
  • variantNameTemplate: "default": 클러스터가 default이라는 변형에 동기화됩니다. variantSelector이 생략된 경우 기본 동작입니다. 저장소에 default.yaml 파일이나 default라는 디렉터리가 포함되어 있지 않으면 아무것도 동기화되지 않습니다.

variantsPattern 및 variantNameTemplate 결합

성공적인 배포를 위해서는 variantsPattern에서 생성된 변형 이름이 클러스터에서 variantNameTemplate와 일치시켜 동기화할 수 있는 이름이어야 합니다.

예를 들어 환경 라벨을 기반으로 클러스터에 배포하려면 dev, staging, prod와 같은 디렉터리로 Git 저장소를 구성할 수 있습니다. 그런 다음 다음 플릿 패키지 사양을 사용합니다.

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

이 구성을 사용하면 env: staging 라벨이 지정된 클러스터가 manifests/staging/ 디렉터리의 콘텐츠를 수신합니다.

배포 전략

Fleet 패키지를 사용하여 Git 저장소의 리소스를 전체 클러스터 Fleet에 배포할 수 있습니다. 또한 함대 패키지를 구성하여 리소스가 배포되는 방식, 위치, 유형을 제어할 수 있습니다.

다음 섹션에서는 다양한 FleetPackage 구성의 예를 보여줍니다. Fleet 패키지 적용에 대한 자세한 내용은 Fleet 패키지 배포를 참고하세요.

Fleet의 모든 클러스터에 배포

다음 FleetPackage는 순차적 전략을 사용하여 Kubernetes 리소스를 한 번에 세 개의 클러스터에 배포하고 Fleet의 모든 클러스터를 타겟팅합니다.

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

클러스터 하위 집합에 배포

다음 FleetPackage는 라벨 선택기를 사용하여 멤버십 라벨 country이 fleet의 "us"와 일치하는 클러스터에만 Kubernetes 리소스를 배포합니다.

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

다음 단계

Fleet 패키지 배포