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

구성 동기화 설치 맞춤설정

구성 동기화를 사용하면 Git 저장소, OCI 이미지, Helm 차트와 같은 중앙의 단일 정보 소스에서 구성을 동기화하여 Kubernetes 리소스를 관리할 수 있습니다. 기본 설치 안내가 요구사항에 맞지 않으면 구성 동기화 설치를 맞춤설정해야 할 수 있습니다.

이 페이지에서는 구성 동기화의 고급 설치 및 구성을 실행하는 방법을 보여줍니다. 설치 프로세스에는 다음이 포함됩니다.

Google Cloud 콘솔, Google Cloud CLI 또는 Terraform을 사용하여 개별 클러스터에 구성 동기화를 설치합니다.
소스 유형, 형식, 인증을 비롯한 루트 저장소 구성
구성 동기화의 설치 및 구성이 성공적으로 완료되었는지 확인합니다.

제한사항

구성 동기화에서는 Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 helm을 소스 유형으로 구성하는 것을 지원하지 않습니다. Kubernetes API를 사용하여 Helm 저장소에서 동기화하도록 RootSync 또는 RepoSync 객체를 구성하거나 다른 단일 정보 소스에서 선언할 수 있습니다. 자세한 내용은 Helm 저장소 구성을 참고하세요.

시작하기 전에

구성 동기화를 설치하기 전에 정보 소스와 적합한 클러스터를 준비합니다.

구성 동기화에 정보 소스 액세스 권한 부여

정보 소스의 구성을 클러스터에 동기화하려면 구성 동기화에 저장소에 대한 읽기 전용 액세스 권한이 필요합니다. 구성 동기화가 구성을 읽도록 승인하려면 다음 단계를 완료하세요.

구성 동기화가 클러스터에 동기화할 구성 파일이 포함된 정보 소스를 만들거나 이에 대한 액세스 권한을 갖습니다. 자세한 내용은 다음 리소스를 참조하세요.
- 정보 소스에 구성 추가: 구성에 관한 개념 정보입니다.
- GitOps 권장사항: 저장소를 정리하고 관리하기 위한 도움말과 일반 권장사항입니다.
- 구조화되지 않은 저장소 사용: 구조화되지 않은 저장소를 사용하고 정리하기 위한 권장사항입니다.
신뢰할 수 있는 정보의 출처가 공개된 경우 추가 조치가 필요하지 않습니다. 구성 동기화에는 추가 권한이 필요하지 않습니다.
신뢰할 수 있는 정보의 소스가 비공개인 경우 다음 페이지 중 하나의 안내를 따르세요.
- 구성 동기화에 Git 액세스 권한 부여
- OCI 또는 Helm에 대한 액세스 권한을 구성 동기화에 부여

클러스터 요구사항 검토

클러스터를 만들기 전에 클러스터 요구사항을 검토하세요.

구성 동기화 설치

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치하면 구성 동기화는 root-sync라는 RootSync 객체를 자동으로 만듭니다. kubectl 명령어를 사용하여 root-sync를 수정하고 구성 동기화 구성을 추가할 수 있습니다. 자세한 내용은 kubectl 명령어로 구성 동기화 구성을 참고하세요.

콘솔

구성 동기화 설치

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

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

구성으로 이동

구성 동기화 설치를 클릭합니다.
사용할 구성 동기화 버전을 선택합니다.
설치 옵션에서 다음 옵션 중 하나를 선택합니다.
- 전체 Fleet에 구성 동기화 설치 (권장): 구성 동기화가 Fleet의 모든 클러스터에 설치됩니다.
- 개별 클러스터에 구성 동기화 설치: 선택한 클러스터에 구성 동기화가 설치됩니다. 선택한 클러스터는 Fleet에 자동으로 등록됩니다.
개별 클러스터에 구성 동기화를 설치하는 경우 사용 가능한 클러스터 표에서 구성 동기화를 설치할 클러스터를 선택합니다.
구성 동기화 설치를 클릭합니다. 몇 분 후 설정 탭에서 Fleet에 있는 클러스터의 상태 열에 사용 설정됨이 표시됩니다.

패키지 배포

클러스터를 Fleet에 등록하고 구성 동기화를 설치한 후 구성 동기화를 구성하여 정보 소스에서 클러스터에 패키지를 배포할 수 있습니다. 여러 클러스터에 동일한 패키지를 배포하거나 여러 클러스터에 서로 다른 패키지를 배포할 수 있습니다. 패키지 이름 및 동기화 유형과 같은 일부 설정을 제외하고는 패키지를 배포한 후 편집할 수 있습니다. 자세한 내용은 패키지 관리를 참고하세요.

패키지를 배포하려면 다음 단계를 완료하세요.

Google Cloud 콘솔에서 구성 동기화 대시보드로 이동합니다.

구성 동기화 대시보드로 이동
패키지 배포를 클릭합니다.
패키지 배포를 위한 클러스터 선택 테이블에서 패키지를 배포할 클러스터를 선택한 다음 계속을 클릭합니다.
Git에서 호스팅되는 패키지 또는 OCI에서 호스팅된 패키지를 소스 유형으로 선택하고 계속을 클릭합니다.
패키지 세부정보 섹션에 RootSync 또는 RepoSync 객체를 식별하는 패키지 이름을 입력합니다.
동기화 유형 필드에서 동기화 유형으로 클러스터 범위 동기화 또는 네임스페이스 범위 동기화를 선택합니다.

클러스터 범위 동기화는 RootSync 객체를 만들고 네임스페이스 범위 동기화는 RepoSync 객체를 만듭니다. 이러한 객체에 대한 자세한 내용은 구성 동기화 아키텍처를 참고하세요.
소스 섹션에서 다음을 완료합니다.
- Git 저장소에서 호스팅되는 소스의 경우 다음 필드를 입력하세요.
  1. 저장소 URL로 정보 소스로 사용하는 Git 저장소의 URL을 입력합니다.
  2. (선택사항): 기본 HEAD를 사용하지 않는지 확인하려면 버전 필드를 업데이트합니다.
  3. (선택사항): 루트 저장소에서 동기화하지 않으려면 경로 필드를 업데이트합니다.
  4. (선택사항): 기본 main 브랜치를 사용하지 않는 경우 브랜치 필드를 업데이트합니다.
- OCI 이미지에서 호스팅되는 소스의 경우 다음 필드를 입력하세요.
  1. 정보 소스로 사용하는 OCI 이미지의 URL을 이미지로 입력합니다.
  2. 루트 디렉터리를 기준으로 동기화할 디렉터리의 경로를 디렉터리로 입력합니다.
(선택사항): 고급 설정 섹션을 펼친 후 다음을 완료합니다.
1. 인증 유형을 선택합니다. 구성 동기화는 소스의 구성 파일을 읽고 이를 클러스터에 적용할 수 있도록 정보 소스에 대한 읽기 전용 액세스 권한이 필요합니다. 공개 저장소와 같이 소스에 인증이 필요하지 않은 경우를 제외하고 구성 동기화에 Git 저장소, OCI 이미지 또는 Helm 차트(gcloud CLI만 해당)에 대한 읽기 전용 액세스 권한을 부여해야 합니다. 구성 동기화를 설치할 때 구성한 것과 동일한 인증 유형을 선택합니다.
  
  참고: OCI의 경우 인증을 위해 워크로드 아이덴티티만 선택할 수 있습니다.
  - None: 인증을 사용하지 않습니다.
  - SSH: SSH 키 쌍을 사용하여 인증합니다.
  - Cookiefile: cookiefile을 사용하여 인증합니다.
  - 토큰: 액세스 토큰 또는 비밀번호를 사용하여 인증합니다.
  - Google Cloud Repository: Google 서비스 계정을 사용하여 Cloud Source Repositories 저장소에 액세스합니다. GKE용 워크로드 아이덴티티 제휴가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  - 워크로드 아이덴티티: Google 서비스 계정을 사용하여 Cloud Source Repositories 저장소에 액세스합니다.
2. 동기화 대기 시간을 설정하려면 숫자(초)를 입력하세요. 여기서는 구성 동기화가 정보 소스에서 가져오기를 시도하는 사이에 대기하는 시간을 결정합니다.
3. 정보 소스와 통신할 때 사용될 HTTPS 프록시의 Git 프록시 URL을 입력합니다.
4. 계층 구조를 선택하여 소스 형식을 변경합니다.
  
  기본값인 구조화되지 않음은 원하는 방식으로 소스를 구성할 수 있으므로 대부분의 경우에 권장됩니다.
패키지 배포를 클릭합니다.

구성 동기화 패키지 페이지로 리디렉션됩니다. 몇 분 후에 구성한 클러스터의 동기화 상태 열에 Synced(동기화됨)가 표시됩니다.

gcloud

계속하기 전에 Fleet에 클러스터를 등록했는지 확인하세요.

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

gcloud beta container fleet config-management enable

apply-spec.yaml 파일을 만들고 다음 YAML 파일을 복사하여 구성을 준비합니다.

매니페스트를 만들 때 필요한 모든 선택적 spec.configSync 필드를 설정하고 나중에 구성을 위해 kubectl 명령어를 사용할 수 있습니다. spec.configSync.enabled 필드만 true로 설정하고 선택적 필드를 생략할 수도 있습니다. 그런 다음 나중에 kubectl 명령어를 사용하여 추가 RootSync 객체를 만들거나 이후 kubectl 명령어를 사용하여 완전히 관리할 수 있는 RepoSync를 만들 수 있습니다.
```
# apply-spec.yaml

     applySpecVersion: 1
     spec:
       configSync:
         enabled: true
         # If you don't have a source of truth yet, omit the
         # following fields. You can configure them later.
         sourceType: SOURCE_TYPE
         sourceFormat: FORMAT
         syncRepo: REPO
         syncRev: REVISION
         secretType: SECRET_TYPE
         gcpServiceAccountEmail: EMAIL
         metricsGcpServiceAccountEmail: METRICS_EMAIL
         policyDir: DIRECTORY
         preventDrift: false
```
다음을 바꿉니다.
- SOURCE_TYPE: Git 저장소에서 동기화하려면 git을, OCI 이미지에서 동기화하려면 oci를, Helm 차트에서 동기화하려면 helm을 추가합니다. 값을 지정하지 않으면 기본값은 git입니다.
- FORMAT: unstructured를 추가하여 구조화되지 않은 저장소를 사용하거나 hierarchy를 추가하여 계층 구조의 저장소를 사용합니다. 이러한 값은 대소문자를 구분합니다. 이 필드는 선택사항이며 기본값은 hierarchy입니다. 이 형식을 사용하면 가장 편리한 방식으로 구성을 조직화할 수 있기 때문에 unstructured를 추가하는 것이 좋습니다.
- REPO:정보 소스의 URL을 추가합니다. Git 및 Helm 저장소 URL은 HTTPS 또는 SSH 프로토콜을 사용합니다. 예를 들면 https://github.com/GoogleCloudPlatform/anthos-config-management-samples입니다. SSH를 secretType으로 사용하려면 SSH 프로토콜로 URL을 입력합니다. 이 필드는 필수 항목이며 프로토콜을 입력하지 않으면 URL이 HTTPS URL로 취급됩니다.
  
  OCI URL에는 LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME 형식이 사용됩니다. 기본적으로 이미지는 latest 태그에서 가져오지만 대신 TAG 또는 DIGEST로 이미지를 가져올 수 있습니다. PACKAGE_NAME에서 TAG 또는 DIGEST를 지정합니다.
  - TAG로 가져오려면: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
  - DIGEST로 가져오려면: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
  주의: 구성 동기화를 사용하려면 tar 또는 tar+gzip 형식으로 압축해야 합니다. 다른 형식(예: tar+bz2)은 구성 동기화에서 인식되지 않습니다. 유효한 REPO에서 지원되지 않는 형식의 OCI 이미지로 전환하면 관리형 리소스가 오류 없이 잘립니다.
- REVISION: 동기화할 Git 버전(태그 또는 해시) 또는 브랜치 이름입니다. 해시를 사용하는 경우 축약된 양식이 아닌 전체 해시 양식을 사용해야 합니다.
- SECRET_TYPE: 다음 secretTypes 중 하나입니다.
  git
  - none: 인증을 사용하지 않습니다.
  - ssh: SSH 키 쌍을 사용합니다.
  - cookiefile: cookiefile을 사용합니다.
  - token: 토큰을 사용합니다.
  - gcpserviceaccount: Google 서비스 계정을 사용하여 Cloud Source Repositories 또는 Secure Source Manager 저장소에 액세스합니다. 이 인증 유형을 선택하는 경우 구성 동기화 구성을 완료한 후 IAM 정책 바인딩을 만들어야 합니다. 자세한 내용은 Google 서비스 계정으로 Git에 대한 구성 동기화 액세스 권한 부여 섹션의 Google 서비스 계정 탭을 참고하세요.
  - gcenode: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다. GKE용 워크로드 아이덴티티 제휴가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  - githubapp: GitHub 앱을 사용하여 GitHub 저장소에 인증합니다.
  이러한 인증 유형에 대한 자세한 내용은 Git에 대한 구성 동기화 액세스 권한 부여를 참고하세요.
  oci
  - none: 인증 사용 안함
  - gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. GKE용 워크로드 아이덴티티 제휴가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  - gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.
  helm
  - token: 토큰을 사용합니다.
  - gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. GKE용 워크로드 아이덴티티 제휴가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  - gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.
  - EMAIL: gcpserviceaccount를 secretType으로 추가한 경우 Google 서비스 계정 이메일 주소를 추가합니다. 예를 들면 acm@PROJECT_ID.입니다.
  - METRICS_EMAIL: 구성 동기화 측정항목을 Cloud Monitoring으로 내보내기 위해 사용되는 Google Cloud서비스 계정(GSA)의 이메일입니다. GSA에는 모니터링 측정항목 작성자(roles/monitoring.metricWriter) IAM 역할이 있어야 합니다. config-management-monitoring 네임스페이스의 Kubernetes 서비스 계정 default가 GSA에 바인딩되어야 합니다.
  - DIRECTORY: Git 저장소의 루트를 기준으로 동기화할 디렉터리의 경로입니다. 지정한 디렉터리의 모든 하위 디렉터리가 포함되어 클러스터에 동기화됩니다. 기본값은 저장소의 루트 디렉터리입니다.
spec 필드에 추가할 수 있는 전체 필드 목록은 gcloud 필드를 참조하세요.

참고:정보 소스가 아직 준비되지 않은 경우 아무 설정도 구성하지 않고 spec.configSync.enabled를 true로 설정하고 다른 모든 spec.configSync 필드를 생략하여 구성 동기화를 사용 설정할 수 있습니다. 저장소를 준비했으면 apply-spec.yaml을 수정하여 구성 설정을 추가합니다.
apply-spec.yaml 파일을 적용합니다. 기존 매니페스트를 사용하는 경우 이전 명령어에서 가져온 설정으로 구성하려는 클러스터에 파일을 적용해야 합니다.
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=CONFIG_YAML_PATH \
    --project=PROJECT_ID
```
다음을 바꿉니다.
- MEMBERSHIP_NAME: 클러스터를 등록할 때 선택한 Fleet 멤버십 이름으로 gcloud container fleet memberships list를 사용하여 찾을 수 있습니다.
- CONFIG_YAML_PATH: apply-spec.yaml 파일에 대한 경로입니다.
- PROJECT_ID: 프로젝트 ID

Terraform

구성 동기화를 구성하려는 각 클러스터에 다음 예와 같이 configmanagement 및 config_sync 블록이 포함된 google_gkehub_feature_membership 리소스 블록을 적용합니다.

git

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      git {
        sync_repo   = "REPO"
        sync_branch = "BRANCH"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

다음을 바꿉니다.

REPO: 구성 파일이 포함된 Git 저장소의 URL
BRANCH: 저장소 브랜치(예: main)
DIRECTORY: 동기화하려는 저장소의 최상위 수준을 나타내는 Git 저장소 내의 경로
SECRET: 보안 비밀 인증 유형

oci

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      oci {
        sync_repo   = "REPO"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

다음을 바꿉니다.

REPO: 구성 파일이 포함된 OCI 이미지 저장소의 URL
DIRECTORY: 동기화할 리소스가 포함된 디렉터리의 절대 경로. 루트 디렉터리를 사용하려면 이 필드를 비워 두세요.
SECRET: 보안 비밀 인증 유형

동기화하려는 클러스터마다 이 프로세스를 반복합니다.

Terraform 사용에 대한 자세한 내용은 구성 동기화에 대한 Terraform 지원을 참고하세요.

루트 저장소를 구성한 후 선택적으로 다른 루트 저장소 및 네임스페이스 저장소를 포함하여 여러 저장소로부터 동기화를 구성할 수 있습니다. 네임스페이스 저장소는 클러스터 간 특정 네임스페이스에 동기화된 네임스페이스 범위 구성이 포함된 저장소를 원하는 경우에 유용합니다.

설치 확인

구성 동기화를 설치하고 구성한 후에는 설치가 성공적으로 완료되었는지 확인할 수 있습니다.

gcloud

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

nomos status

설치가 완료되면 SYNCED 또는 PENDING 상태가 표시됩니다.

보고된 오류를 비롯해 nomos status에서 제공하는 정보에 대한 자세한 내용은 nomos 명령줄 도구 문서의 구성 동기화 상태 확인을 참고하세요.

Console

다음 단계를 완료합니다.

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

구성으로 이동

패키지 탭에서 클러스터 테이블의 동기화 상태 열을 확인합니다. 구성 동기화 설치에 성공한 경우 설치됨 상태가 표시됩니다. 정보 소스가 성공적으로 구성되면 동기화됨 상태가 표시됩니다.

다음 단계

구성 동기화 업그레이드 방법 알아보기
구성 동기화 구성에 사용되는 gcloud 명령어 자세히 알아보기
여러 저장소에서 동기화 구성하는 방법 알아보기
nomos 명령어 사용하기
구성 동기화 문제 해결 소개 읽어보기
구성 동기화 제거 방법 알아보기
기본 구성 동기화 권한 검토하기