구성 동기화 설치

구성 동기화를 사용하면 정보 소스에 저장된 구성 파일로 Kubernetes 리소스를 관리할 수 있습니다. 구성 동기화는 Git 저장소, OCI 이미지, Helm 차트를 정보 소스로 지원합니다. 이 페이지에서는 루트 저장소에서 동기화되도록 구성 동기화를 사용 설정하고 구성하는 방법을 보여줍니다. 구성 동기화는 Google Kubernetes Engine(GKE) Enterprise 버전에서 사용할 수 있습니다.

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치할 때는 RootSync 및 RepoSync API가 기본적으로 사용 설정됩니다. 이렇게 하면 여러 저장소에서 동기화하고 Kustomize 및 Helm 구성을 동기화하는 등의 추가 기능을 제공합니다.

시작하기 전에

구성 동기화를 설치하려면 먼저 환경을 준비하고, 클러스터 요구사항을 충족하는지 확인하고, 올바른 사용자 역할을 부여합니다.

로컬 환경 준비

다음 작업을 완료하여 로컬 환경을 준비합니다.

정보 소스를 만들거나 정보 소스를 이용할 수 있는지 확인합니다. 여기에서 구성 동기화가 동기화하는 구성을 추가합니다. 구성과 정보 소스를 설정하는 방법에 대한 자세한 내용은 다음 가이드 중 하나를 참조하세요.
gcloud 및 nomos 명령어를 제공하는 Google Cloud CLI를 설치 및 초기화합니다. Cloud Shell을 사용하는 경우 Google Cloud CLI가 사전 설치됩니다. 이전에 Google Cloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
GKE Enterprise API를 사용 설정합니다.

GKE Enterprise API 사용 설정

클러스터 요구사항

다음 요구사항을 충족하는 클러스터를 만들거나 이에 대한 액세스 권한을 얻습니다.

클러스터가 Google Kubernetes Engine(GKE) Enterprise 버전의 지원되는 플랫폼 및 버전에 있습니다.
Autopilot 클러스터를 사용하는 경우 Autopilot은 다음 규칙을 충족하도록 컨테이너 리소스 요구사항을 조정합니다.
참고: 리소스 요구사항이 조정되면 Autopilot에서 워크로드에 autopilot.gke.io/resource-adjustment 주석을 추가하여 입력 및 출력 리소스를 표시합니다.
이러한 규칙으로 인해 Autopilot 클러스터의 경우 구성 동기화는 다음을 수행합니다.
- 일치 요청에 대한 사용자 지정 리소스 재정의 한도를 조정합니다.
- 주석에 선언된 조정 출력보다 높은 리소스 요청이 하나 이상 있거나 주석에 선언된 해당 입력보다 낮은 리소스 요청이 하나 이상 있는 경우에만 재정의를 적용합니다.
(선택사항) GKE 클러스터를 사용하는 경우 클러스터에 워크로드 아이덴티티가 사용 설정되어 있습니다. 워크로드 아이덴티티는 향상된 보안 속성 및 관리 편의성으로 인해 GKE 내에서 실행되는 애플리케이션에서 Google Cloud 서비스에 액세스하는 데 권장되는 방식입니다. Autopilot 클러스터에는 기본적으로 워크로드 아이덴티티가 사용 설정되어 있습니다.
구성 동기화가 Cloud Monitoring에 측정항목을 전송할 수 있도록 올바른 측정항목 쓰기 권한을 부여합니다. 자동 업그레이드를 사용하려는 경우에 필요합니다.
구성 동기화 버전을 자동 업그레이드하려면 GKE 클러스터가 출시 채널에 등록되어 있어야 합니다. GKE 출시 채널을 사용하지 않는 클러스터는 안정화 버전의 출시 채널을 사용하는 클러스터로 취급됩니다.
비공개 GKE 클러스터를 사용하려면 비공개 GKE 노드에서 이그레스를 허용하도록 Cloud NAT를 구성합니다. 자세한 내용은 GKE 설정 예시를 참조하세요. 또는 Google API 및 서비스에서 사용되는 외부 IP 주소 집합에 연결하도록 비공개 Google 액세스를 사용 설정할 수 있습니다.

참고: 비공개 Google 액세스는 포트 2022에서 SSH를 지원하지 않습니다. 하지만 구성 동기화에 Git에 대한 읽기 전용 액세스 권한을 부여하면 cookiefile 사용자 인증 정보를 사용할 수 있습니다.
구성 동기화에 정보 소스에 대한 액세스 권한을 부여할 때 Google 서비스 계정을 사용하려면 Cloud Source Repositories의 클러스터에 있는 노드에 대한 액세스 범위에 읽기 전용 범위를 포함해야 합니다.

클러스터 생성 시 지정된 --scopes 목록에 cloud-source-repos-ro를 포함하거나 클러스터 생성 시 cloud-platform 범위를 사용하여 읽기 전용 범위를 추가할 수 있습니다. 예를 들면 다음과 같습니다.
```
gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform
```
노드 풀을 만든 후에는 액세스 범위를 수정할 수 없습니다. 그러나 동일한 클러스터를 사용하는 동안에 액세스 범위가 적절한 새 노드 풀을 만들 수 있습니다. 기본 gke-default 범위에는 cloud-source-repos-ro가 포함되지 않습니다.
불필요한 트래픽을 차단하는 엄격한 VPC 방화벽 요구사항이 있는 경우 방화벽 규칙을 만들어 공개 GKE 클러스터에서 다음 트래픽을 허용해야 합니다.
- TCP: 포트 53 및 443에서 인그레스 및 이그레스 허용
- UDP: 포트 53에서 이그레스 허용
이러한 규칙을 포함하지 않으면 구성 동기화가 올바르게 동기화되지 않고 nomos status가 다음 오류를 보고합니다.

Error: KNV2004: unable to sync repo Error in the git-sync container

비공개 GKE 클러스터를 사용하는 경우 이 단계를 건너뛸 수 있습니다.
amd64 노드 풀에서 구성 동기화를 실행해야 합니다. 구성 동기화 백엔드 구성요소 컨테이너 이미지는 amd64 머신 아키텍처에 대해서만 빌드, 배포, 테스트됩니다. 구성 동기화 구성요소가 Arm 노드에 예약된 경우 exec format 오류가 발생하고 비정상 종료됩니다.

클러스터에 Arm 노드가 있으면 클러스터에 하나 이상의 amd64 노드를 추가하고 GKE 클러스터를 사용하지 않는 경우 taint를 arm64 노드에 추가하여 특정 톨러레이션(toleration) 없이 arm64 노드에 포드를 예약하지 않도록 합니다. GKE Arm 노드에는 이미 기본 taint가 있으므로 추가할 필요가 없습니다.

클러스터 준비

적합한 클러스터를 만든 후 다음 단계를 완료합니다.

클러스터를 등록하는 사용자에게 필요한 IAM 역할을 부여합니다.
Google Cloud CLI를 사용하여 구성 동기화를 구성하거나 Google Cloud 외부의 클러스터를 사용하려는 경우 GKE 클러스터 또는 Google Cloud 외부의 클러스터가 지금 Fleet에 등록되어 있는지 확인합니다. Google Cloud 콘솔을 사용하려면 구성 동기화를 구성할 때 GKE 클러스터를 등록할 수 있습니다.

구성 동기화 설치

다음 섹션에서는 구성 동기화에 다음 정보 소스 중 하나에 대한 액세스 권한을 부여합니다.

Git 저장소
OCI 이미지
Helm 차트

액세스 권한을 부여한 후에 구성 동기화를 구성할 수 있습니다.

Git에 대한 액세스 권한 부여

구성 동기화에는 저장소에 커밋된 구성을 읽고 이를 클러스터에 적용할 수 있도록 Git 저장소에 대한 읽기 전용 액세스 권한이 필요합니다.

저장소에 읽기 전용 액세스에 대한 인증이 필요하지 않으면 계속 구성 동기화를 구성하고 none을 인증 유형으로 사용할 수 있습니다. 예를 들어 로그인하지 않고 웹 인터페이스를 사용하여 저장소를 탐색하거나 git clone을 사용하여 사용자 인증 정보를 제공하지 않거나 저장된 사용자 인증 정보를 사용하지 않고 저장소의 클론을 로컬로 만들 수 있는 경우에는 인증할 필요가 없습니다. 이 경우 보안 비밀을 만들 필요가 없습니다.

하지만 대부분의 사용자는 저장소에 대한 읽기 액세스가 제한되므로 사용자 인증 정보를 만들어야 합니다. 사용자 인증 정보가 필요한 경우 등록된 클러스터마다 git-creds 보안 비밀에 저장됩니다(Google 서비스 계정을 사용하지 않는 경우). 보안 비밀의 이름은 고정 값이므로 git-creds로 지정해야 합니다.

구성 동기화는 다음과 같은 인증 메커니즘을 지원합니다.

SSH 키 쌍(ssh)
Cookiefile(cookiefile)
토큰(token)
Google 서비스 계정(gcpserviceaccount)
Compute Engine 기본 서비스 계정(gcenode)

저장소에서 무엇을 지원하는지에 따라 선택할 수 있는 메커니즘이 다릅니다. 일반적으로 SSH 키 쌍을 사용하는 것이 좋습니다. GitHub와 Bitbucket 모두 SSH 키 쌍 사용을 지원합니다. 하지만 Cloud Source Repositories에서 저장소를 사용하는 경우에는 프로세스가 더 간단하므로 Google 서비스 계정을 대신 사용하는 것이 좋습니다. 조직에서 저장소를 호스팅하고 지원되는 인증 방법을 모르는 경우 관리자에게 문의하세요.

Cloud Source Repositories의 저장소를 구성 동기화 저장소로 사용하려면 다음 단계를 완료하여 Cloud Source Repositories URL을 가져옵니다.

모든 저장소를 나열합니다.
```
gcloud source repos list
```
출력에서 사용하려는 저장소의 URL을 복사합니다. 예를 들면 다음과 같습니다.
```
REPO_NAME  PROJECT_ID  URL
my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr
```
다음 섹션에서 구성 동기화를 구성할 때 이 URL을 사용해야 합니다. Google Cloud 콘솔을 사용하여 구성 동기화를 구성하는 경우 URL 필드에 URL을 추가합니다. Google Cloud CLI를 사용하여 구성 동기화를 구성하는 경우 구성 파일의 syncRepo 필드에 URL을 추가합니다.

SSH 키 쌍

SSH 키 쌍은 공개 키 파일과 비공개 키 파일로 구성됩니다. 일반적으로 공개 키에는 .pub 확장자가 있습니다.

SSH 키 쌍을 사용하려면 다음 단계를 완료하세요.

구성 동기화가 Git 저장소에 인증할 수 있도록 SSH 키 쌍을 만듭니다. 이 단계는 저장소를 클론하거나 읽기 위해 저장소에 인증해야 할 때 필요합니다. 보안 관리자가 키 쌍을 제공하는 경우에는 이 단계를 건너뛰세요. 보안 및 규정 준수 요구사항에 따라 모든 클러스터에 단일 키 쌍을 사용하거나 클러스터별로 키 쌍을 사용할 수 있습니다.

다음 명령어는 4096비트 RSA 키를 만듭니다. 이보다 낮은 값은 권장되지 않습니다.
```
ssh-keygen -t rsa -b 4096 \
-C "GIT_REPOSITORY_USERNAME" \
-N '' \
-f /path/to/KEYPAIR_FILENAME
```
다음을 바꿉니다.
- GIT_REPOSITORY_USERNAME: 구성 동기화가 저장소에 인증하기 위해 사용할 사용자 이름입니다.
- /path/to/KEYPAIR_FILENAME: 키 쌍의 경로입니다.
GitHub와 같은 타사 Git 저장소 호스트를 사용하거나 Cloud Source Repositories에서 서비스 계정을 사용하려는 경우 별도의 계정을 사용하는 것이 좋습니다.

참고: 암호 없이 SSH 키를 만들어야 합니다. 구성 동기화는 SSH 키 암호를 지원하지 않습니다.
저장소가 새로 생성된 공개 키를 인식하도록 구성합니다. Git 호스팅 업체의 문서를 참조하세요. 편의를 위해 다음과 같이 자주 사용되는 Git 호스팅 업체용 안내가 포함되어 있습니다.
- Cloud Source Repositories
- Bitbucket
- GitHub 별도의 배포 키를 만들어 단일 GitHub 저장소에 대한 읽기 전용 액세스 권한을 제공하는 것이 좋습니다.
- GitLab

클러스터의 새 보안 비밀에 비공개 키를 추가합니다.

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

/path/to/KEYPAIR_PRIVATE_KEY_FILENAME을 비공개 키 이름(.pub 서픽스가 없는 이름)으로 바꿉니다.

(권장) SSH 인증을 사용하여 알려진 호스트 확인을 구성하려면 git_creds 보안 비밀의 data.known_hosts 필드에 알려진 호스트 키를 추가하면 됩니다. known_hosts 검사를 중지하려면 보안 비밀에서 known_hosts 필드를 삭제하면 됩니다. 알려진 호스트 키를 추가하려면 다음을 실행합니다.
```
kubectl edit secret git-creds \
 --namespace=config-management-system
```
그런 다음 data 아래에 알려진 호스트 항목을 추가합니다.
```
known_hosts: KNOWN_HOSTS_KEY
```
로컬 디스크에서 비공개 키를 삭제하거나 키를 보호합니다.
구성 동기화를 구성하고 Git 저장소의 URL을 추가할 때 SSH 프로토콜을 사용합니다. Cloud Source Repositories에서 저장소를 사용하는 경우 URL을 입력할 때 다음 형식을 사용해야 합니다.
```
ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME
```
다음을 바꿉니다.
- EMAIL: Google Cloud 사용자 이름입니다.
- PROJECT_ID: 저장소가 있는 Google Cloud 프로젝트의 ID입니다.
- REPO_NAME: 저장소의 이름입니다.

Cookiefile

cookiefile을 획득하는 절차는 저장소 구성에 따라 다릅니다. 예시를 보려면 Cloud Source Repositories 문서의 정적 사용자 인증 정보 생성을 참조하세요. 사용자 인증 정보는 보통 홈 디렉터리의 .gitcookies 파일에 저장되거나 보안 관리자를 통해 제공받을 수 있습니다.

cookiefile을 사용하려면 다음 단계를 완료하세요.

cookiefile을 만들고 획득한 후에는 클러스터의 새 보안 비밀에 추가합니다.

HTTPS 프록시를 사용하지 않는 경우 다음 명령어를 사용하여 보안 비밀을 만듭니다.
```
kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE
```
HTTPS 프록시를 사용해야 할 경우 다음 명령어를 실행해서 cookiefile과 함께 보안 비밀에 추가합니다.
```
kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE \
 --from-literal=https_proxy=HTTPS_PROXY_URL
```
다음을 바꿉니다.
- /path/to/COOKIEFILE: 적절한 경로 및 파일 이름입니다.
- HTTPS_PROXY_URL: Git 저장소와 통신할 때 사용하는 HTTPS 프록시의 URL입니다.
참고: HTTP 프록시는 보안상의 이유로 지원되지 않습니다.
cookiefile 콘텐츠가 로컬에서 계속 필요하면 이 콘텐츠를 보호합니다. 그렇지 않으면 삭제합니다.

토큰

조직에서 SSH 키 사용을 허용하지 않으면 토큰을 대신 사용하는 것이 좋습니다. 구성 동기화를 사용하면 GitHub의 개인 액세스 토큰(PAT), GiLab의 PAT 또는 배포 키, Bitbucket의 앱 비밀번호를 토큰으로 사용할 수 있습니다.

토큰을 사용하여 보안 비밀을 만들려면 다음 단계를 완료합니다.

GitHub, GitLab, Bitbucket을 사용하여 토큰을 만듭니다.
- GitHub: PAT를 만듭니다. 비공개 저장소에서 읽을 수 있도록 토큰에 repo 범위를 부여합니다. PAT를 GitHub 계정에 결합하므로 머신 사용자를 만들고 PAT를 머신 사용자에게 결합하는 것도 좋습니다.
- GitLab: PAT를 만들거나 배포 토큰을 만듭니다.
- Bitbucket: 앱 비밀번호를 만듭니다.
토큰을 만들고 얻은 후에는 클러스터의 새 보안 비밀에 추가합니다.

HTTPS 프록시를 사용하지 않는 경우 다음 명령어를 사용하여 보안 비밀을 만듭니다.
```
kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace="config-management-system" \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN
```
다음을 바꿉니다.
- USERNAME: 사용할 사용자 이름입니다.
- TOKEN: 이전 단계에서 만든 토큰입니다.
HTTPS 프록시를 사용해야 할 경우 다음 명령어를 실행해서 username 및 token과 함께 보안 비밀에 추가합니다.
```
kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-literal=username=USERNAME \
  --from-literal=token=TOKEN \
 --from-literal=https_proxy=HTTPS_PROXY_URL
```
다음을 바꿉니다.
- USERNAME: 사용할 사용자 이름입니다.
- TOKEN: 이전 단계에서 만든 토큰입니다.
- HTTPS_PROXY_URL: Git 저장소와 통신할 때 사용하는 HTTPS 프록시의 URL입니다.
참고: HTTP 프록시는 보안상의 이유로 지원되지 않습니다.
토큰이 로컬에서 계속 필요하면 토큰을 보호합니다. 그렇지 않으면 삭제합니다.

Google 서비스 계정

저장소가 Cloud Source Repositories에 있고 클러스터가 GKE 워크로드 아이덴티티 또는 Fleet 워크로드 아이덴티티를 사용하는 경우 Google 서비스 계정을 사용하여 구성 동기화에 관리형 클러스터와 동일한 프로젝트의 저장소에 대한 액세스 권한을 부여할 수 있습니다.

아직 서비스 계정이 없으면 서비스 계정을 만듭니다.
Cloud Source Repositories 리더(roles/source.reader) IAM 역할을 Google 서비스 계정에 부여합니다. Cloud Source Repositories 역할 및 권한에 대한 자세한 내용은 저장소를 볼 수 있는 권한 부여를 참조하세요.
- 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
```
- 서비스 계정이 프로젝트의 저장소마다 다른 수준의 액세스 권한을 갖도록 하려면 저장소별 권한을 부여합니다.
```
gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID
```
Google Cloud 콘솔을 사용하여 구성 동기화를 구성하는 경우 워크로드 아이덴티티를 인증 유형으로 선택한 후 서비스 계정 이메일을 추가합니다.

Google Cloud CLI를 사용하여 구성 동기화를 구성하는 경우 gcpserviceaccount를 secretType으로 추가한 후 서비스 계정 이메일을 gcpServiceAccountEmail에 추가합니다.
구성 동기화를 구성한 후, Kubernetes 서비스 계정과 Google 서비스 계정 간에 IAM 정책 바인딩을 만듭니다. 구성 동기화를 처음 구성할 때까지는 Kubernetes 서비스 계정이 생성되지 않습니다.

Fleet에 등록된 클러스터를 사용하는 경우 Fleet당 한 번만 정책 바인딩을 만들면 됩니다. Fleet에 등록된 모든 클러스터는 동일한 워크로드 아이덴티티 풀을 공유합니다. Fleet의 동일성 개념에 따라 IAM 정책을 한 클러스터의 Kubernetes 서비스 계정에 추가하면 동일한 Fleet에 있는 다른 클러스터의 동일한 네임스페이스에 있는 Kubernetes 서비스 계정도 동일한 IAM 정책을 받습니다.

이 바인딩을 사용하면 구성 동기화 Kubernetes 서비스 계정이 Google 서비스 계정 역할을 합니다.
```
gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID
```

다음을 바꿉니다.

PROJECT_ID: 조직의 프로젝트 ID입니다.
FLEET_HOST_PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 PROJECT_ID와 동일합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 클러스터가 등록된 Fleet의 프로젝트 ID입니다.
GSA_NAME: Artifact Registry에 연결하는 데 사용할 커스텀 Google 서비스 계정입니다. 서비스 계정에는 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할이 있어야 합니다.
KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다.
- 루트 저장소의 경우 RootSync 이름이 root-sync이면 root-reconciler를 사용합니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME을 사용하세요. Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치하면 구성 동기화는 root-sync라는 RootSync 객체를 자동으로 만듭니다.
REPOSITORY: 저장소의 이름입니다.
POLICY_FILE: Identity and Access Management 정책이 포함된 JSON 또는 YAML 파일입니다.

Compute Engine 기본 서비스 계정

저장소가 Cloud Source Repositories에 있고 클러스터가 워크로드 아이덴티티가 사용 중지된 Google Cloud의 GKE인 경우 gcenode를 인증 유형으로 사용할 수 있습니다.

Google Cloud 콘솔을 사용하여 구성 동기화를 구성하는 경우 Google Cloud Repository를 인증 유형으로 선택합니다.

Google Cloud CLI를 사용하여 구성 동기화를 구성하는 경우 gcenode를 secretType으로 추가하세요.

Google Cloud Repository 또는 gcenode를 선택하면 Compute Engine 기본 서비스 계정을 사용할 수 있습니다. Compute Engine 기본 서비스 계정에 Cloud Source Repositories 리더(roles/source.reader) IAM 역할을 부여해야 합니다. Cloud Source Repositories 역할 및 권한에 대한 자세한 내용은 저장소를 볼 수 있는 권한 부여를 참조하세요.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

PROJECT_ID를 조직의 프로젝트 ID로 바꾸고 PROJECT_NUMBER를 조직의 프로젝트 번호로 바꿉니다.

구성 동기화에 OCI에 대한 읽기 전용 액세스 권한 부여

구성 동기화는 이미지에 포함된 구성을 읽고 이를 클러스터에 적용할 수 있도록 Artifact Registry에 저장된 OCI 이미지에 대한 읽기 전용 액세스 권한이 필요합니다.

이미지에 읽기 전용 액세스에 대한 인증이 필요하지 않으면 계속 구성 동기화를 구성하고 none을 인증 유형으로 사용할 수 있습니다. 예를 들어 이미지가 공개이고 인터넷에서 누구나 액세스할 수 있으면 인증이 필요하지 않습니다.

하지만 대부분의 사용자는 제한된 이미지에 액세스하기 위해 사용자 인증 정보를 만들어야 합니다. 구성 동기화는 다음과 같은 인증 메커니즘을 지원합니다.

Kubernetes 서비스 계정(k8sserviceaccount)
Google 서비스 계정(gcpserviceaccount)
Compute Engine 기본 서비스 계정(gcenode)

Kubernetes 서비스 계정

Artifact Registry에 OCI 이미지를 저장하고 클러스터에서 GKE 워크로드 아이덴티티 또는 Fleet 워크로드 아이덴티티를 사용하는 경우 버전 1.17.2 이상에서 k8sserviceaccount를 인증 유형으로 사용할 수 있습니다. 이 옵션은 간소화된 구성 프로세스로 인해 gcpserviceaccount보다 권장됩니다.

워크로드 아이덴티티 풀이 있는 Kubernetes 서비스 계정에 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 부여합니다. Artifact Registry 역할 및 권한에 대한 자세한 내용은 Artifact Registry의 역할 및 권한 구성을 참조하세요.
- 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
      --role=roles/artifactregistry.reader \
      --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
```
- 서비스 계정이 프로젝트의 저장소마다 다른 수준의 액세스 권한을 갖도록 하려면 저장소별 권한을 부여합니다.
```
gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID
```
다음을 바꿉니다.
- PROJECT_ID: 조직의 프로젝트 ID입니다.
- FLEET_HOST_PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 PROJECT_ID와 동일합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 클러스터가 등록된 Fleet의 프로젝트 ID입니다.
- KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다.
  - 루트 저장소의 경우 RootSync 이름이 root-sync이면 root-reconciler를 사용합니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME을 사용하세요. Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치하면 구성 동기화는 root-sync라는 RootSync 객체를 자동으로 만듭니다.
- REPOSITORY: 저장소 ID입니다.
- LOCATION: 저장소의 리전 또는 멀티 리전 위치입니다.
참고: 이 정책 바인딩을 만들려면 iam.serviceAccounts.setIamPolicy 권한이 필요합니다.

Google 서비스 계정

Artifact Registry에 OCI 이미지를 저장하고 클러스터에서 GKE 워크로드 아이덴티티 또는 Fleet 워크로드 아이덴티티를 사용하는 경우 gcpserviceaccount를 인증 유형으로 사용할 수 있습니다. 버전 1.17.2부터는 대신 k8sserviceaccount를 사용하는 것이 좋습니다. 이 옵션을 사용하면 Google 서비스 계정 및 연결된 IAM 정책 바인딩을 만드는 추가 단계가 필요하지 않습니다.

아직 서비스 계정이 없으면 서비스 계정을 만듭니다.
Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 Google 서비스 계정에 부여합니다. Artifact Registry 역할 및 권한에 대한 자세한 내용은 Artifact Registry의 역할 및 권한 구성을 참조하세요.
- 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID  \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
```
- 서비스 계정이 프로젝트의 저장소마다 다른 수준의 액세스 권한을 갖도록 하려면 저장소별 권한을 부여합니다.
```
gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID
```

다음 명령어를 실행하여 Kubernetes 서비스 계정과 Google 서비스 계정 사이에 IAM 정책 바인딩을 만듭니다.

gcloud iam service-accounts add-iam-policy-binding
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

다음을 바꿉니다.

PROJECT_ID: 조직의 프로젝트 ID입니다.
FLEET_HOST_PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 PROJECT_ID와 동일합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 클러스터가 등록된 Fleet의 프로젝트 ID입니다.
GSA_NAME: Artifact Registry에 연결하는 데 사용할 커스텀 Google 서비스 계정입니다. 서비스 계정에는 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할이 있어야 합니다.
KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다.
- 루트 저장소의 경우 RootSync 이름이 root-sync이면 root-reconciler를 사용합니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME을 사용하세요. Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치하면 구성 동기화는 root-sync라는 RootSync 객체를 자동으로 만듭니다.
REPOSITORY: 저장소 ID입니다.
LOCATION: 저장소의 리전 또는 멀티 리전 위치입니다.

Compute Engine 기본 서비스 계정

Artifact Registry에 Helm 차트를 저장하고 클러스터가 워크로드 아이덴티티가 사용 중지된 Google Cloud 기반 GKE인 경우 gcenode를 인증 유형으로 사용할 수 있습니다. 구성 동기화는 Compute Engine 기본 서비스 계정을 사용합니다. Compute Engine 기본 서비스 계정에 Artifact Registry에 대한 읽기 액세스를 부여해야 합니다.

다음 명령어를 실행하여 Compute Engine 서비스 계정에 Artifact Registry에 대한 읽기 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
   --role=roles/artifactregistry.reader
```
PROJECT_ID를 조직의 프로젝트 ID로 바꾸고 PROJECT_NUMBER를 조직의 프로젝트 번호로 바꿉니다.

구성 동기화에 Helm에 대한 읽기 전용 액세스 권한 부여

구성 동기화에는 저장소에서 Helm 차트를 읽고 이를 클러스터에 설치할 수 있도록 Helm 저장소에 대한 읽기 전용 액세스 권한이 필요합니다.

저장소에 읽기 전용 액세스에 대한 인증이 필요하지 않으면 계속 구성 동기화를 구성하고 none을 인증 유형으로 사용할 수 있습니다. 예를 들어 Helm 저장소가 공개 상태이고 인터넷의 모든 사용자가 액세스할 수 있으면 인증할 필요가 없습니다.

하지만 대부분의 사용자는 비공개 Helm 저장소에 액세스하기 위해 사용자 인증 정보를 만들어야 합니다. 구성 동기화는 다음과 같은 인증 메커니즘을 지원합니다.

토큰(token)
Kubernetes 서비스 계정(k8sserviceaccount)
Google 서비스 계정(gcpserviceaccount)
Compute Engine 기본 서비스 계정(gcenode)

토큰

Helm 저장소 사용자 이름과 비밀번호로 보안 비밀을 만듭니다.

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

다음을 바꿉니다.

SECRET_NAME: 보안 비밀에 지정할 이름입니다.
USERNAME: Helm 저장소 사용자 이름입니다.
PASSWORD: Helm 저장소 비밀번호입니다.

ConfigManagement Operator를 구성할 때 spec.helm.secretRef.name에 선택한 보안 비밀 이름을 사용합니다.

Kubernetes 서비스 계정

Artifact Registry에 Helm 차트를 저장하고 클러스터에서 GKE 워크로드 아이덴티티 또는 Fleet 워크로드 아이덴티티를 사용하는 경우 버전 1.17.2 이상에서 k8sserviceaccount를 인증 유형으로 사용할 수 있습니다. 이 옵션은 간소화된 구성 프로세스로 인해 gcpserviceaccount보다 권장됩니다.

워크로드 아이덴티티 풀이 있는 Kubernetes 서비스 계정에 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 부여합니다. Artifact Registry 역할 및 권한에 대한 자세한 내용은 Artifact Registry의 역할 및 권한 구성을 참조하세요.
- 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
```
- 서비스 계정이 프로젝트의 저장소마다 다른 수준의 액세스 권한을 갖도록 하려면 저장소별 권한을 부여합니다.
```
gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID
```
다음을 바꿉니다.
- PROJECT_ID: 조직의 프로젝트 ID입니다.
- FLEET_HOST_PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 PROJECT_ID와 동일합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 클러스터가 등록된 Fleet의 프로젝트 ID입니다.
- KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다.
  - 루트 저장소의 경우 RootSync 이름이 root-sync이면 root-reconciler를 사용합니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME을 사용하세요.
- REPOSITORY: 저장소 ID입니다.
- LOCATION: 저장소의 리전 또는 멀티 리전 위치입니다.

Google 서비스 계정

Artifact Registry에 Helm 차트를 저장하고 클러스터에서 GKE 워크로드 아이덴티티 또는 Fleet 워크로드 아이덴티티를 사용하는 경우 gcpserviceaccount를 인증 유형으로 사용할 수 있습니다. 버전 1.17.2부터는 대신 k8sserviceaccount를 사용하는 것이 좋습니다. 이 옵션을 사용하면 Google 서비스 계정 및 연결된 IAM 정책 바인딩을 만드는 추가 단계가 필요하지 않습니다.

아직 서비스 계정이 없으면 서비스 계정을 만듭니다.
Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 Google 서비스 계정에 부여합니다. Artifact Registry 역할 및 권한에 대한 자세한 내용은 Artifact Registry의 역할 및 권한 구성을 참조하세요.
- 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID  \
      --role=roles/artifactregistry.reader \
      --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
```
- 서비스 계정이 프로젝트의 저장소마다 다른 수준의 액세스 권한을 갖도록 하려면 저장소별 권한을 부여합니다.
```
gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID
```

다음 명령어를 실행하여 Kubernetes 서비스 계정과 Google 서비스 계정 사이에 IAM 정책 바인딩을 만듭니다.

gcloud iam service-accounts add-iam-policy-binding
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
    --project=PROJECT_ID

다음을 바꿉니다.

PROJECT_ID: 조직의 프로젝트 ID입니다.
FLEET_HOST_PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 PROJECT_ID와 동일합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 클러스터가 등록된 Fleet의 프로젝트 ID입니다.
GSA_NAME: Artifact Registry에 연결하는 데 사용할 커스텀 Google 서비스 계정입니다. 서비스 계정에는 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할이 있어야 합니다.
KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다.
- 루트 저장소의 경우 RootSync 이름이 root-sync이면 root-reconciler를 사용합니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME을 사용하세요.
REPOSITORY: 저장소 ID입니다.
LOCATION: 저장소의 리전 또는 멀티 리전 위치입니다.

Compute Engine 기본 서비스 계정

Compute Engine 서비스 계정에 Artifact Registry에 대한 읽기 권한을 부여합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.reader
```
PROJECT_ID를 조직의 프로젝트 ID로 바꾸고 PROJECT_NUMBER를 조직의 프로젝트 번호로 바꿉니다.

구성 동기화 구성

이 섹션에서는 루트 저장소의 설정을 구성합니다. Git 저장소에 동기화하는 경우 Google Cloud 콘솔을 사용하여 설치 과정을 안내받고 일부 단계를 자동화할 수 있습니다.

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 객체를 식별하는 패키지 이름을 입력합니다.
소스 섹션에서 다음을 완료합니다.
- Git 저장소에서 호스팅되는 소스의 경우 다음 필드를 입력합니다.
  1. RootSync 또는 RepoSync 객체를 식별하는 패키지 이름을 입력합니다.
  2. 정보 저장소 URL로 정보 소스로 사용하는 Git 저장소의 URL을 입력합니다.
  3. (선택사항): 기본 HEAD를 사용하지 않는지 확인하려면 버전 필드를 업데이트합니다.
  4. (선택사항): 루트 저장소에서 동기화하지 않으려면 경로 필드를 업데이트합니다.
  5. (선택사항): 기본 main 브랜치를 사용하지 않는 경우 브랜치 필드를 업데이트합니다.
- OCI 이미지에서 호스팅되는 소스에 다음 필드를 입력합니다.
  1. 정보 소스로 사용하는 OCI 이미지의 URL을 이미지로 입력합니다.
  2. 동기화할 디렉터리의 경로를 디렉터리로 루트 디렉터리를 기준으로 입력합니다.
동기화 유형 필드에서 RootSync 또는 RepoSync를 동기화 유형으로 선택합니다.

RootSync 객체는 클러스터 범위이고 RepoSync 객체는 네임스페이스 범위입니다. 이러한 객체에 대한 자세한 내용은 RootSync 및 RepoSync 필드를 참조하세요.
(선택사항): 고급 설정 섹션을 확장하여 다음을 완료합니다.
1. 인증 유형을 선택합니다.
  
  참고: OCI의 경우 인증에 워크로드 아이덴티티만 선택할 수 있습니다.
  - None: 인증을 사용하지 않습니다.
  - SSH: SSH 키 쌍을 사용합니다.
  - Cookiefile: cookiefile을 사용합니다.
  - Token: 토큰을 사용합니다.
  - Google Cloud Repository: Google 서비스 계정을 사용하여 Cloud Source Repositories 저장소에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  - 워크로드 아이덴티티: 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 매니페스트를 만들거나 기존 매니페스트를 추가하여 구성을 준비합니다. 기존 매니페스트를 사용하면 다른 클러스터에 사용되는 것과 동일한 설정으로 클러스터를 구성할 수 있습니다.
새 매니페스트 만들기
클러스터에 대해 구성 동기화를 새 설정으로 구성하려면 apply-spec.yaml이라는 파일을 만들고 이 파일에 다음 YAML 파일을 복사합니다.

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

applySpecVersion: 1
spec:
  upgrades: UPGRADE_SETTING
  configSync:
    # Set to true to install and enable Config Sync
    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
    syncBranch: BRANCH
    secretType: SECRET_TYPE
    gcpServiceAccountEmail: EMAIL
    metricsGcpServiceAccountEmail: METRICS_EMAIL
    policyDir: DIRECTORY
    preventDrift: PREVENT_DRIFT
```
다음을 바꿉니다.
- (미리보기) UPGRADE_SETTING: auto로 설정하여 구성 동기화가 자동으로 업그레이드되도록 구성합니다. 구성 동기화를 직접 수동으로 업그레이드하려면 manual로 설정합니다. 기본값은 manual입니다. 이 플래그는 Google Cloud의 GKE 클러스터에서만 지원됩니다.
  
  주의: 업그레이드 플래그를 다시 manual로 설정하여 자동 업그레이드를 사용 중지할 수 없습니다. 자동 업그레이드에서 수동 업그레이드로 전환하려면 구성 동기화를 제거하고 다시 설치해야 합니다.
- 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 버전(태그 또는 해시)입니다. 이 필드는 선택사항이며 기본값은 HEAD입니다. 구성 동기화 버전 1.17.0부터는 syncRev 필드에 브랜치 이름을 지정할 수도 있습니다. 버전 1.17.0 이상에서 해시를 사용하는 경우 축약된 양식이 아닌 전체 해시 양식을 사용해야 합니다.
- BRANCH: 동기화할 저장소의 브랜치입니다. 이 필드는 선택사항이며 기본값은 master입니다. 구성 동기화 버전 1.17.0부터는 간단히 syncRev 필드를 사용하여 브랜치 이름을 지정하는 것이 좋습니다. syncRev 필드와 syncBranch 필드 모두 지정되면 syncRev가 syncBranch보다 우선 적용됩니다.
- SECRET_TYPE: 다음 secretTypes 중 하나입니다.
  git
  
  none: 인증을 사용하지 않습니다.
  
  ssh: SSH 키 쌍을 사용합니다.
  
  cookiefile: cookiefile을 사용합니다.
  
  token: 토큰을 사용합니다.
  
  gcpserviceaccount: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다. 이 인증 유형을 선택하는 경우 구성 동기화 구성을 완료한 후 IAM 정책 바인딩을 만들어야 합니다. 자세한 내용은 Git에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여 섹션의 Google 서비스 계정 탭을 참조하세요.
  
  gcenode: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  
  이러한 인증 유형에 대한 자세한 내용은 Git에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여를 참조하세요.
  
  oci
  
  none: 인증 사용 안함
  
  gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  
  gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.
  
  helm
  
  token: 토큰을 사용합니다.
  
  gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
  
  gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.
- EMAIL: gcpserviceaccount를 secretType으로 추가한 경우 Google 서비스 계정 이메일 주소를 추가합니다. 예를 들면 acm@PROJECT_ID.iam.gserviceaccount.com입니다.
- METRICS_EMAIL: 구성 동기화 측정항목을 Cloud Monitoring으로 내보내기 위해 사용되는 Google Cloud 서비스 계정(GSA)의 이메일입니다. GSA에는 모니터링 측정항목 작성자(roles/monitoring.metricWriter) IAM 역할이 있어야 합니다. config-management-monitoring 네임스페이스의 Kubernetes 서비스 계정 default가 GSA에 바인딩되어야 합니다.
- DIRECTORY: Git 저장소의 루트를 기준으로 동기화할 디렉터리의 경로입니다. 지정한 디렉터리의 모든 하위 디렉터리가 포함되어 클러스터에 동기화됩니다. 기본값은 저장소의 루트 디렉터리입니다.
- PREVENT_DRIFT: true로 설정되었으면 충돌하는 변경사항이 라이브 클러스터로 푸시되지 않도록 거부하여 구성 동기화 허용 웹훅이 드리프트를 방지하도록 사용 설정합니다. 기본 설정은 false입니다. 구성 동기화는 이 필드 값에 관계없이 항상 드리프트를 조정합니다.
spec 필드에 추가할 수 있는 전체 필드 목록은 gcloud 필드를 참조하세요.

참고:정보 소스가 아직 준비되지 않은 경우 아무 설정도 구성하지 않고 spec.configSync.enabled를 true로 설정하고 다른 모든 spec.configSync 필드를 생략하여 구성 동기화를 사용 설정할 수 있습니다. 저장소를 준비했으면 apply-spec.yaml을 수정하여 구성 설정을 추가합니다.
기존 매니페스트 사용
다른 클러스터에서 사용하는 것과 동일한 설정으로 클러스터를 구성하려면 등록된 클러스터에서 설정을 가져옵니다.
```
gcloud alpha container fleet config-management fetch-for-apply \
    --membership=MEMBERSHIP_NAME \
    --project=PROJECT_ID \
    > CONFIG_YAML_PATH
```
다음을 바꿉니다.
- MEMBERSHIP_NAME: 사용할 구성 동기화 설정이 있는 등록된 클러스터의 멤버십 이름입니다.
- PROJECT_ID: 프로젝트 ID입니다.
- CONFIG_YAML_PATH: 클러스터에서 가져온 설정이 포함된 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입니다.

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

Fleet 수준 기본값 구성

Google Kubernetes Engine(GKE) Enterprise 버전을 사용 설정한 경우 구성 동기화를 클러스터의 Fleet 수준 기본값으로 사용 설정하고 구성할 수 있습니다. 즉, 클러스터 생성 중에 등록된 모든 새 Google Cloud 기반 GKE 클러스터는 지정한 설정으로 클러스터에 구성 동기화를 사용 설정합니다. Fleet 기본 구성에 대한 자세한 내용은 Fleet 수준 기능 관리를 참조하세요.

구성 동기화의 Fleet 수준 기본값을 구성하려면 다음 단계를 수행합니다.

Google Cloud 콘솔에서 기능 관리자 페이지로 이동합니다.

기능 관리자로 이동
구성 동기화 창에서 구성을 클릭합니다.
Fleet 수준 설정을 검토합니다. Fleet에 등록하는 새 클러스터가 모두 이러한 설정을 상속합니다.
선택사항: 기본 설정을 변경하려면 Fleet 맞춤설정을 클릭합니다. 대화상자가 나타나면 다음을 수행합니다.
1. 자동 업그레이드(미리보기)를 선택하여 구성 동기화 업그레이드 버전을 자동으로 만들거나 수동 업그레이드를 선택하여 구성 동기화 버전을 직접 관리합니다. 자동 업그레이드 작동 방식에 대한 자세한 내용은 구성 동기화 업그레이드를 참조하세요.
2. 수동 업그레이드를 선택한 경우 버전 목록에서 사용하려는 구성 동기화 버전을 선택합니다.
3. 변경사항 저장을 클릭합니다.
구성을 클릭합니다.
확인 대화상자에서 확인을 클릭합니다. 이전에 구성 동기화를 사용 설정하지 않은 경우 확인을 클릭하면 anthosconfigmanagement.googleapis.com API도 사용 설정됩니다.
선택사항: 기존 클러스터를 기본 설정으로 동기화합니다.
1. Fleet의 클러스터 목록에서 동기화할 클러스터를 선택합니다.
2. Fleet 설정과 동기화를 클릭하고 확인 대화상자가 나타나면 확인을 클릭합니다. 이 작업을 완료하는 데 몇 분 정도 걸릴 수 있습니다.

설치 확인

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

콘솔

다음 단계를 완료합니다.

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

구성으로 이동

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

gcloud

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

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

PROJECT_ID를 프로젝트 ID로 바꿉니다.

설치에 성공한 경우 SYNCED 상태가 표시됩니다. 구성 동기화 버전 1.18.0부터는 출력에 설치된 구성 동기화 버전과 구성 동기화의 업그레이드 설정도 표시됩니다.

위 명령어를 실행한 후 오류가 발생하면 git-creds 보안 비밀을 만들었는지 확인합니다. 보안 비밀을 만든 경우 다음 명령어를 다시 실행해 봅니다.

gcloud beta container fleet config-management apply

또한 nomos status 명령어를 사용하여 구성 동기화가 성공적으로 설치되었는지 확인할 수 있습니다. 문제가 없는 유효한 설치 상태는 PENDING 또는 SYNCED입니다. 설치가 유효하지 않거나 완료되지 않은 경우 상태는 NOT INSTALLED 또는 NOT CONFIGURED입니다. 출력에는 보고된 오류도 포함됩니다.

역할 기반 액세스 제어(RBAC) 및 권한

정책 컨트롤러, 구성 동기화, 구성 컨트롤러에는 권한이 높은 워크로드가 포함됩니다. 다음 표에는 이러한 워크로드에 대한 권한이 나와 있습니다.

구성요소	네임스페이스	서비스 계정	권한	설명
ConfigManagement Operator	`config-management-system`	`config-management-operator`	cluster-admin	ConfigManagement Operator는 이 테이블에 다른 구성요소를 설치합니다. 이러한 구성요소 중 일부는 클러스터 관리자 권한이 필요하므로 ConfigManagement Operator에도 해당 권한이 필요합니다.
구성 동기화	`config-management-system`			필요한 권한은 구성 동기화 권한을 참조하세요.

리소스 요청

다음 섹션에는 구성 동기화에 대한 리소스 요청이 나와 있습니다.

다음 표에는 구성 동기화 구성요소의 Kubernetes 리소스 요구사항이 나와 있습니다. 자세한 내용은 Kubernetes 문서의 컨테이너 리소스 관리를 참조하세요.

나열된 모든 구성요소가 생성되지는 않습니다. 다음 조건으로 인해 각 구성요소가 예약됩니다.

구성 동기화가 사용 설정되면 config-management-operator가 설치됩니다.
구성 동기화가 사용 설정되면 reconciler-manager가 설치됩니다.
드리프트 방지가 사용 설정되면 admission-webhook이 설치됩니다.
RootSync 및 RepoSync마다 reconciler가 설치됩니다.
구성 동기화가 사용 설정되면 otel-collector가 설치됩니다.

1.17

배포 이름	복제본당 CPU 요청(m)	복제본당 메모리 요청(Mi)
`config-management-operator`	100	100
`resource-group-controller-manager`	110	300
`admission-webhook¹`	10	100
`otel-collector`	200	400
`reconciler-manager`	20	150
`reconciler`(RootSync 및 RepoSync당 하나)	자세한 내용은 조정자 배포를 참조하세요.

¹ 허용 웹훅에는 복제본이 두 개 있으므로 총 리소스 요청을 계산할 때 허용 웹훅을 사용하는 경우 값에 2를 곱해야 합니다 허용 웹훅은 기본적으로 사용 중지되어 있습니다.

1.16

배포 이름	복제본당 CPU 요청(m)	복제본당 메모리 요청(Mi)
`config-management-operator`	100	100
`resource-group-controller-manager`	110	300
`admission-webhook¹`	10	100
`otel-collector`	200	400
`reconciler-manager`	20	150
`reconciler`(RootSync 및 RepoSync당 하나)	자세한 내용은 조정자 배포를 참조하세요.

1.15

배포 이름	복제본당 CPU 요청(m)	복제본당 메모리 요청(Mi)
`config-management-operator`	100	100
`resource-group-controller-manager`	110	300
`admission-webhook¹`	10	100
`otel-collector`	200	400
`reconciler-manager`	20	150
`reconciler`(RootSync 및 RepoSync당 하나)	자세한 내용은 조정자 배포를 참조하세요.

조정자 배포

구성 동기화는 RootSync 및 RepoSync 객체마다 동기화를 처리하기 위한 독립적인 조정자 배포를 만듭니다. 조정자 배포는 컨테이너 여러 개로 구성됩니다.

구성 동기화 버전 1.17.0 이상에서는 조정자에 대한 기본 리소스 요청이 표준 및 Autopilot 클러스터와 다릅니다. 다른 모든 클러스터 유형은 표준 기본값을 사용합니다.

Standard 클러스터

1.17

컨테이너 이름	CPU 요청(m)	메모리 요청(Mi)
`reconciler`	50	200
`otel-agent`	10	100
`hydration-controller`(선택사항)	10	100
`git-sync`	10	16
`gcenode-askpass-sidecar`(선택사항)	10	20
`helm-sync`	75	128
`oci-sync`	25	32

1.16

컨테이너 이름	CPU 요청(m)	메모리 요청(Mi)
`reconciler`	50	200
`otel-agent`	10	100
`hydration-controller`(선택사항)	10	100
`git-sync`	10	200
`gcenode-askpass-sidecar`(선택사항)	10	20
`helm-sync`	50	256
`oci-sync`	10	200

1.15

컨테이너 이름	CPU 요청(m)	메모리 요청(Mi)
`reconciler`	50	200
`otel-agent`	10	100
`hydration-controller`(선택사항)	10	100
`git-sync`	10	200
`gcenode-askpass-sidecar`(선택사항)	10	20
`helm-sync`	50	256
`oci-sync`	10	200

Autopilot 클러스터

1.17

컨테이너 이름	CPU 요청 및 한도(m)	메모리 요청 및 한도(Mi)
`reconciler`	700	512
`otel-agent`	10	64
`hydration-controller`(선택사항)	200	256
`git-sync`	20	32
`gcenode-askpass-sidecar`(선택사항)	50	64
`helm-sync`	150	256
`oci-sync`	50	64

1.16

1.17.0 이전 버전의 구성 동기화에서는 리소스 요청이 표준과 Autopilot에서 동일합니다.

1.15

1.17.0 이전 버전의 구성 동기화에서는 리소스 요청이 표준과 Autopilot에서 동일합니다.

기본 리소스 요청 및 한도를 재정의하는 방법을 알아보려면 리소스 재정의를 참조하세요.

번들 Helm 및 Kustomize 버전

구성 동기화는 내부적으로 Helm 및 Kustomize 실행 파일을 활용하여 구성을 렌더링합니다. 다음 표에서는 렌더링 기능을 지원하는 구성 동기화 버전 목록과 번들 Helm 및 Kustomize 버전을 보여줍니다.

구성 동기화 버전	Helm 버전	Kustomize 버전
1.16.0 이상	v3.11.3	v5.1.1
1.15.0에서 1.15.3	v3.11.3	v5.0.1
1.11.0에서 1.14.3	v3.6.3	v4.5.2

Kustomize를 통한 Helm 렌더링에 대한 자세한 내용은 Kustomize로 Kubernetes 구성을 참조하세요. Helm API 사용에 대해서는 Artifact Registry에서 Helm 차트 동기화를 참조하세요.

다음 단계

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

구성 동기화 설치

시작하기 전에

로컬 환경 준비

클러스터 요구사항

클러스터 준비

구성 동기화 설치

Git에 대한 액세스 권한 부여

SSH 키 쌍

Cookiefile

토큰

Google 서비스 계정

Compute Engine 기본 서비스 계정

구성 동기화에 OCI에 대한 읽기 전용 액세스 권한 부여

Kubernetes 서비스 계정

Google 서비스 계정

Compute Engine 기본 서비스 계정

구성 동기화에 Helm에 대한 읽기 전용 액세스 권한 부여

토큰

Kubernetes 서비스 계정

Google 서비스 계정

Compute Engine 기본 서비스 계정

구성 동기화 구성

콘솔

구성 동기화 설치

패키지 배포

gcloud

새 매니페스트 만들기

git

oci

helm

기존 매니페스트 사용

Fleet 수준 기본값 구성

설치 확인

콘솔

gcloud

역할 기반 액세스 제어(RBAC) 및 권한

리소스 요청

1.17

1.16

1.15

조정자 배포

Standard 클러스터

1.17

1.16

1.15

Autopilot 클러스터

1.17

1.16

1.15

번들 Helm 및 Kustomize 버전

다음 단계