kubectl을 사용하여 구성 동기화 수동 설치(권장하지 않음)

이 페이지에서는 kubectl 명령어를 사용하여 구성 동기화를 설치하는 방법을 보여줍니다. ConfigManagement Operator는 Kubernetes 클러스터에서 구성 동기화를 관리하는 컨트롤러입니다. 구성 동기화를 사용하여 관리하려는 각 클러스터에 연산자를 설치하고 구성하려면 다음 단계를 따르세요.

시작하기 전에

이 섹션에서는 kubectl을 사용하여 구성 동기화를 설치하기 전에 충족해야 하는 기본 요건을 설명합니다.

로컬 환경 준비

Operator를 설치하기 전에 다음 작업을 수행하여 로컬 환경을 준비했는지 확인합니다.

  • 정보 소스를 만들거나 정보 소스에 대한 액세스 권한을 얻습니다.

  • 이 안내에서 사용되는 gcloud, kubectl, nomos 명령어를 제공하는 Google Cloud CLI를 설치하고 초기화합니다. Cloud Shell을 사용하는 경우 Google Cloud CLI가 사전 설치되어 제공됩니다.

  • Google Cloud CLI는 kubectl을 기본으로 설치하지 않습니다. kubectl을 설치하려면 다음 명령어를 사용하세요.

    gcloud components install kubectl

  • gcloud auth login 명령어를 사용하여 Google Cloud에 인증하면 구성 동기화의 구성요소를 다운로드할 수 있습니다.

클러스터 준비

구성 동기화 요구사항을 충족하는 Google Kubernetes Engine(GKE) Enterprise 버전 클러스터를 만들거나 액세스 권한을 준비합니다.

권한 준비

구성 동기화를 설치하는 Google Cloud 사용자는 클러스터에서 새 역할을 만들기 위해 IAM 권한이 필요합니다. 필요한 경우 다음 명령어로 해당 역할을 부여하세요.

gcloud container clusters get-credentials CLUSTER_NAME

kubectl create clusterrolebinding cluster-admin-binding \
    --clusterrole cluster-admin --user USER_ACCOUNT

다음을 바꿉니다.

  • CLUSTER_NAME: 클러스터 이름입니다.
  • USER_ACCOUNT: Google Cloud 계정의 이메일 주소입니다.

로컬 시스템에서 Google Cloud CLI를 구성한 방법에 따라 --project 및 --zone 필드를 추가해야 할 수도 있습니다.

정책 바인딩을 만들기 위해 gcpserviceaccount를 인증 유형으로 사용해서 작업자에게 OCI 액세스를 부여하려면 iam.serviceAccounts.setIamPolicy 권한도 있어야 합니다. 서비스 계정 관리자(roles/iam.serviceAccountAdmin)에 IAM 역할을 부여하여 이 권한을 얻을 수 있습니다. 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

클러스터 등록

구성 동기화에서 클러스터를 등록하려면 다음 단계를 완료합니다.

  1. 작업자 배포
  2. 작업자에게 다음 중 하나에 대한 읽기 전용 액세스를 부여합니다.
  3. 작업자 구성

작업자 배포

모든 기본 요건을 충족하는지 확인한 후 YAML 매니페스트를 다운로드하고 적용하여 연산자를 배포할 수 있습니다.

  1. 다음 명령어를 사용하여 최신 버전의 연산자 매니페스트를 다운로드합니다. 특정 버전을 대신 다운로드하려면 다운로드를 참조하세요.

    gcloud storage cp gs://config-management-release/released/latest/config-management-operator.yaml config-management-operator.yaml

  2. 매니페스트를 적용합니다.

    kubectl apply -f config-management-operator.yaml

YAML 또는 JSON 구문 오류에 기인하지 않고 ConfigManagement 객체 문제로 인해 실패하는 경우 클러스터에서 객체가 인스턴스화되더라도 올바르게 작동하지 않을 수 있습니다. 이 경우 nomos status 명령어를 사용하여 객체의 오류를 확인할 수 있습니다.

문제가 없는 유효한 설치 상태는 PENDING 또는 SYNCED입니다.

유효하지 않은 설치 상태는 NOT CONFIGURED이며, 다음 오류 중 하나가 표시됩니다.

  • missing git-creds Secret
  • missing required syncRepo field
  • git-creds Secret is missing the key specified by secretType

문제를 해결하려면 구성 오류를 수정합니다. 오류 유형에 따라 ConfigManagement 매니페스트를 클러스터에 다시 적용해야 할 수도 있습니다.

git-creds 보안 비밀을 만드는 것을 잊어버린 경우에는 구성 동기화가 보안 비밀을 생성하는 즉시 이를 감지하므로 구성을 다시 적용할 필요가 없습니다.

작업자에게 읽기 전용 액세스 부여

Git에 구성을 저장할 경우 작업자에게 Git 읽기 전용 액세스를 부여해야 합니다. 구성을 OCI 이미지로 저장할 경우 작업자에게 OCI 읽기 전용 액세스를 부여해야 합니다. 구성을 Helm에 저장하는 경우 작업자에 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을 가져옵니다.

  1. 모든 저장소를 나열합니다.

    gcloud source repos list

  2. 출력에서 사용하려는 저장소의 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 키 쌍을 사용하려면 다음 단계를 완료하세요.

  1. 구성 동기화가 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에서 서비스 계정을 사용하려는 경우 별도의 계정을 사용하는 것이 좋습니다.

  2. 저장소가 새로 생성된 공개 키를 인식하도록 구성합니다. Git 호스팅 업체의 문서를 참조하세요. 편의를 위해 다음과 같이 자주 사용되는 Git 호스팅 업체용 안내가 포함되어 있습니다.

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

    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 서픽스가 없는 이름)으로 바꿉니다.

  4. (권장) 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

  5. 로컬 디스크에서 비공개 키를 삭제하거나 키를 보호합니다.

  6. 구성 동기화를 구성하고 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을 사용하려면 다음 단계를 완료하세요.

  1. 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입니다.

  2. cookiefile 콘텐츠가 로컬에서 계속 필요하면 이 콘텐츠를 보호합니다. 그렇지 않으면 삭제합니다.

토큰

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

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

  1. GitHub, GitLab, Bitbucket을 사용하여 토큰을 만듭니다.

  2. 토큰을 만들고 얻은 후에는 클러스터의 새 보안 비밀에 추가합니다.

    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입니다.

  3. 토큰이 로컬에서 계속 필요하면 토큰을 보호합니다. 그렇지 않으면 삭제합니다.

Google 서비스 계정

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

  1. 아직 서비스 계정이 없으면 서비스 계정을 만듭니다.

  2. 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

  3. Google Cloud 콘솔을 사용하여 구성 동기화를 구성하는 경우 워크로드 아이덴티티를 인증 유형으로 선택한 후 서비스 계정 이메일을 추가합니다.

    Google Cloud CLI를 사용하여 구성 동기화를 구성하는 경우 gcpserviceaccount를 secretType으로 추가한 후 서비스 계정 이메일을 gcpServiceAccountEmail에 추가합니다.

  4. 구성 동기화를 구성한 후, 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에 있고 클러스터가 워크로드 아이덴티티가 사용 중지된 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보다 권장됩니다.

  1. 워크로드 아이덴티티 풀이 있는 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: 저장소의 리전 또는 멀티 리전 위치입니다.

Google 서비스 계정

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

  1. 아직 서비스 계정이 없으면 서비스 계정을 만듭니다.

  2. 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

  3. 다음 명령어를 실행하여 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 차트를 저장하고 클러스터가 워크로드 아이덴티티가 사용 중지된 GKE인 경우 gcenode를 인증 유형으로 사용할 수 있습니다. 구성 동기화는 Compute Engine 기본 서비스 계정을 사용합니다. Compute Engine 기본 서비스 계정에 Artifact Registry에 대한 읽기 액세스를 부여해야 합니다.

  1. 다음 명령어를 실행하여 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를 조직의 프로젝트 번호로 바꿉니다.

인증 기관의 작업자 구성

아직 신뢰할 수 없는 인증 기관(CA)의 인증서로 구성된 서버의 경우, 구성 동기화는 CA 인증서를 사용하여 서버에 대한 HTTPS 연결을 확인하도록 구성할 수 있습니다. 이는 Git, Helm 또는 OCI 서버에서 지원됩니다. CA 인증서에는 전체 SSL 인증서(루트/중간/리프)가 포함되어야 합니다. 서버가 이미 신뢰할 수 있는 CA를 사용 중이거나 HTTPS를 통해 연결하지 않는 경우 이 단계를 건너뛰고 caCertSecretRef를 설정하지 않습니다.

RootSync

  1. Git 서버의 인증서를 발급하는 데 사용된 CA 인증서를 가져와서 파일에 저장합니다.

  2. RootSync 객체의 경우 config-management-system 네임스페이스에 보안 비밀을 만들어야 합니다. 예를 들면

    kubectl create ns config-management-system && 
    
kubectl create secret generic ROOT_CA_CERT_SECRET_NAME 
    
 --namespace=config-management-system 
    
 --from-file=cert=/path/to/CA_CERT_FILE
    입니다.

  3. 작업자를 구성할 때 RootSync 객체의 caCertSecretRef.name 필드 값을 ROOT_CA_CERT_SECRET_NAME으로 설정합니다.

RepoSync

  1. Git 서버의 인증서를 발급하는 데 사용된 CA 인증서를 가져와서 파일에 저장합니다.

  2. RepoSync 객체의 경우 RepoSync와 동일한 네임스페이스에 보안 비밀을 만들어야 합니다. 예를 들면

    kubectl create ns REPO_SYNC_NAMESPACE && 
    
kubectl create secret generic NAMESPACE_CA_CERT_SECRET_NAME 
    
 --namespace=REPO_SYNC_NAMESPACE 
    
 --from-file=cert=/path/to/CA_CERT_FILE
    입니다.

  3. RepoSync를 구성할 때 RepoSync 객체의 caCertSecretRef.name 필드 값을 NAMESPACE_CA_CERT_SECRET_NAME으로 설정합니다.

작업자에게 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보다 권장됩니다.

  1. 워크로드 아이덴티티 풀이 있는 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 정책 바인딩을 만드는 추가 단계가 필요하지 않습니다.

  1. 아직 서비스 계정이 없으면 서비스 계정을 만듭니다.

  2. 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

  3. 다음 명령어를 실행하여 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 기본 서비스 계정

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

  1. 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를 조직의 프로젝트 번호로 바꿉니다.

작업자 구성

루트 저장소에서 동기화를 구성하려면 ConfigManagement 객체에서 다중 저장소 모드를 사용 설정하고 루트 저장소를 클러스터에 동기화하는 RootSync 객체를 만들어야 합니다. 클러스터당 루트 저장소를 하나만 만들 수 있고 루트 저장소는 구조화되지 않은 저장소 또는 계층적 저장소일 수 있습니다.

  1. 구성 동기화 허용 웹훅을 사용 중이고(기본적으로 허용 웹훅이 사용 중지됨) 비공개 클러스터에 구성 동기화를 설치하는 경우 방화벽 규칙을 추가하여 10250 포트를 허용합니다. 구성 동기화 허용 웹훅은 드리프트 방지를 위해 포트 10250을 사용합니다.

  2. config-management.yaml 파일을 만들고 이 파일에 다음 YAML 파일을 복사합니다.

    # config-management.yaml
apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
metadata:
  name: config-management
spec:
  # The `enableMultiRepo` field is set to true to enable RootSync and RepoSync APIs.
  enableMultiRepo: true
  preventDrift: PREVENT_DRIFT

    다음을 바꿉니다.

    • PREVENT_DRIFT: true로 설정되었으면 충돌하는 변경사항이 라이브 클러스터로 푸시되지 않도록 거부하여 구성 동기화 허용 웹훅이 드리프트를 방지하도록 사용 설정합니다. 기본 설정은 false입니다. 구성 동기화는 이 필드 값에 관계없이 항상 드리프트를 조정합니다.

  3. 변경사항을 적용합니다.

    kubectl apply -f config-management.yaml

  4. RootSync 및 RepoSync CRD가 사용 가능해질 때까지 기다립니다.

    until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done

  5. 다음 매니페스트 중 하나를 root-sync.yaml로 저장합니다. 구성에 대한 정보 소스에 해당하는 매니페스트 버전을 사용합니다.

    Git

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: git
  sourceFormat: ROOT_FORMAT
  git:
    repo: ROOT_REPOSITORY
    revision: ROOT_REVISION
    branch: ROOT_BRANCH
    dir: ROOT_DIRECTORY
    auth: ROOT_AUTH_TYPE
    gcpServiceAccountEmail: ROOT_EMAIL
    secretRef:
      name: ROOT_SECRET_NAME
    noSSLVerify: ROOT_NO_SSL_VERIFY
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다.
    • ROOT_FORMAT: unstructured를 추가하여 구조화되지 않은 저장소를 사용하거나 hierarchy를 추가하여 계층 구조의 저장소를 사용합니다. 이러한 값은 대소문자를 구분합니다. 이 필드는 선택사항이며 기본값은 hierarchy입니다. 이 형식을 사용하면 가장 편리한 방식으로 구성을 조직화할 수 있기 때문에 unstructured를 추가하는 것이 좋습니다.
    • ROOT_REPOSITORY: 루트 저장소로 사용할 Git 저장소의 URL을 추가합니다. HTTPS 또는 SSH 프로토콜을 사용하여 URL을 입력할 수 있습니다. 예를 들어 https://github.com/GoogleCloudPlatform/anthos-config-management-samples는 HTTPS 프로토콜을 사용합니다. 필수 필드입니다.
    • ROOT_REVISION: 동기화할 Git 버전(태그 또는 해시)을 추가합니다. 이 필드는 선택사항이며 기본값은 HEAD입니다. 구성 동기화 버전 1.17.0부터는 revision 필드에 브랜치 이름을 지정할 수도 있습니다. 버전 1.17.0 이상에서 해시를 사용하는 경우 축약된 양식이 아닌 전체 해시 양식을 사용해야 합니다.
    • ROOT_BRANCH: 동기화할 저장소의 브랜치를 추가합니다. 이 필드는 선택사항이며 기본값은 master입니다. 구성 동기화 버전 1.17.0부터는 간단히 revision 필드를 사용하여 브랜치 이름을 지정하는 것이 좋습니다. revision 필드와 branch 필드가 모두 지정된 경우 revision이 branch보다 우선 적용됩니다.
    • ROOT_DIRECTORY: 동기화하려는 구성이 포함된 루트 디렉터리에 Git 저장소의 경로를 추가합니다. 이 필드는 선택사항이며 기본값은 저장소의 루트 디렉터리(/)입니다.

    • ROOT_AUTH_TYPE: 다음 인증 유형 중 하나를 추가합니다.

      • none: 인증 사용 안함
      • ssh: SSH 키 쌍 사용
      • cookiefile: cookiefile 사용
      • token: 토큰 사용
      • gcpserviceaccount: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다.
      • gcenode: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.

      이러한 인증 유형에 대한 자세한 내용은 Git에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여를 참조하세요.

      필수 필드입니다.

    • ROOT_EMAIL: gcpserviceaccount를 ROOT_AUTH_TYPE으로 추가한 경우 Google 서비스 계정 이메일 주소를 추가합니다. 예를 들면 acm@PROJECT_ID.iam.gserviceaccount.com입니다.

    • ROOT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 보안 비밀의 공개 키를 Git 제공업체에 추가해야 합니다. 이 필드는 선택사항입니다.

    • ROOT_NO_SSL_VERIFY: SSL 인증서 확인을 중지하려면 이 필드를 true로 설정합니다. 기본값은 false입니다.

    • ROOT_CA_CERT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 Git 제공업체가 이 인증 기관(CA)에서 발급한 인증서를 사용해야 합니다. 보안 비밀에는 cert라는 키 아래에 CA 인증서가 포함되어야 합니다. 이 필드는 선택사항입니다.

      CA 인증서의 보안 비밀 객체를 구성하는 방법에 대한 자세한 내용은 인증 기관의 작업자 구성을 참조하세요.

    필드에 대한 설명 및 spec 필드에 추가할 수 있는 전체 필드 목록은 RootSync 필드를 참조하세요.

    이 매니페스트는 Git를 소스로 사용하는 RootSync 객체를 만듭니다.

    OCI

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: oci
  sourceFormat: ROOT_FORMAT
  oci:
    image: ROOT_IMAGE
    dir: ROOT_DIRECTORY
    auth: ROOT_AUTH_TYPE
    gcpServiceAccountEmail: ROOT_EMAIL
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다.
    • ROOT_FORMAT: unstructured를 추가하여 구조화되지 않은 저장소를 사용하거나 hierarchy를 추가하여 계층 구조의 저장소를 사용합니다. 이러한 값은 대소문자를 구분합니다. 이 필드는 선택사항이며 기본값은 hierarchy입니다. 이 형식을 사용하면 가장 편리한 방식으로 구성을 조직화할 수 있기 때문에 unstructured를 추가하는 것이 좋습니다.
    • ROOT_IMAGE: 루트 저장소로 사용할 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
    • ROOT_DIRECTORY: 동기화하려는 구성이 포함된 루트 디렉터리에 저장소의 경로를 추가합니다. 이 필드는 선택사항이며 기본값은 저장소의 루트 디렉터리(/)입니다.

    • ROOT_AUTH_TYPE: 다음 인증 유형 중 하나를 추가합니다.

      • none: 인증 사용 안함
      • gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
      • gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.

      필수 필드입니다.

    • ROOT_EMAIL: gcpserviceaccount를 ROOT_AUTH_TYPE으로 추가한 경우 Google 서비스 계정 이메일 주소를 추가합니다. 예를 들면 acm@PROJECT_ID.iam.gserviceaccount.com입니다.

    • ROOT_CA_CERT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 OCI 제공업체가 이 인증 기관(CA)에서 발급한 인증서를 사용해야 합니다. 보안 비밀에는 cert라는 키 아래에 CA 인증서가 포함되어야 합니다. 이 필드는 선택사항입니다.

    CA 인증서의 보안 비밀 객체를 구성하는 방법에 대한 자세한 내용은 인증 기관의 작업자 구성을 참조하세요.

    필드에 대한 설명 및 spec 필드에 추가할 수 있는 전체 필드 목록은 RootSync 필드를 참조하세요.

    이 매니페스트는 OCI 이미지를 소스로 사용하는 RootSync 객체를 만듭니다.

    Helm

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: helm
  sourceFormat: ROOT_FORMAT
  helm:
    repo: ROOT_HELM_REPOSITORY
    chart: HELM_CHART_NAME
    version: HELM_CHART_VERSION
    releaseName: HELM_RELEASE_NAME
    namespace: HELM_RELEASE_NAMESPACE
    values:
      foo:
        bar: VALUE_1
      baz:
      - qux: VALUE_2
        xyz: VALUE_3
    includeCRDs: HELM_INCLUDE_CRDS
    auth: ROOT_AUTH_TYPE
      gcpServiceAccountEmail: ROOT_EMAIL
      secretRef:
        name: ROOT_SECRET_NAME
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다.
    • ROOT_FORMAT: unstructured를 추가하여 구조화되지 않은 저장소를 사용하거나 hierarchy를 추가하여 계층 구조의 저장소를 사용합니다. 이러한 값은 대소문자를 구분합니다. 이 필드는 선택사항이며 기본값은 hierarchy입니다. 이 형식을 사용하면 가장 편리한 방식으로 구성을 조직화할 수 있기 때문에 unstructured를 추가하는 것이 좋습니다.
    • ROOT_HELM_REPOSITORY: 루트 저장소로 사용할 Helm 저장소의 URL입니다. HTTPS 또는 SSH 프로토콜을 사용하여 URL을 입력할 수 있습니다. 예를 들어 https://github.com/GoogleCloudPlatform/anthos-config-management-samples는 HTTPS 프로토콜을 사용합니다. 필수 필드입니다.
    • HELM_CHART_NAME: Helm 차트의 이름을 추가합니다. 필수 필드입니다.
    • HELM_CHART_VERSION: 차트의 버전입니다. 이 필드는 선택사항입니다. 값을 지정하지 않으면 최신 버전이 사용됩니다.
    • HELM_RELEASE_NAME: Helm 출시 버전의 이름입니다. 이 필드는 선택사항입니다.
    • HELM_RELEASE_NAMESPACE: 출시 버전의 대상 네임스페이스입니다. 템플릿에 namespace: {{ .Release.Namespace }}이 포함된 리소스의 네임스페이스만 설정합니다. 이 필드는 선택사항입니다. 값을 지정하지 않으면 기본 네임스페이스 config-management-system이 사용됩니다.
    • HELM_INCLUDE_CRDS: Helm 템플릿에서 CustomResourceDefinition도 생성하도록 하려면 true로 설정합니다. 이 필드는 선택사항입니다. 값을 지정하지 않을 경우 기본값은 false이며 CRD가 생성되지 않습니다.
    • VALUE: 차트에 포함되는 기본값 대신 사용할 값입니다. 이 필드의 형식을 Helm 차트의 values.yaml 파일과 동일하게 지정합니다. 이 필드는 선택사항입니다.

    • ROOT_AUTH_TYPE: 다음 인증 유형 중 하나를 추가합니다.

      • none: 인증 사용 안함
      • token: 사용자 이름과 비밀번호를 사용하여 비공개 Helm 저장소에 액세스합니다.
      • gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
      • gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.

      필수 필드입니다.

    • ROOT_EMAIL: gcpserviceaccount를 ROOT_AUTH_TYPE으로 추가한 경우 Google 서비스 계정 이메일 주소를 추가합니다. 예를 들면 acm@PROJECT_ID.iam.gserviceaccount.com입니다.

    • ROOT_SECRET_NAME: token이 ROOT_AUTH_TYPE이면 보안 비밀 이름을 추가합니다. 이 필드는 선택사항입니다.

    • ROOT_CA_CERT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 Helm 제공업체가 이 인증 기관(CA)에서 발급한 인증서를 사용해야 합니다. 보안 비밀에는 cert라는 키 아래에 CA 인증서가 포함되어야 합니다. 이 필드는 선택사항입니다.

    CA 인증서의 보안 비밀 객체를 구성하는 방법에 대한 자세한 내용은 인증 기관의 작업자 구성을 참조하세요.

    필드에 대한 설명 및 spec 필드에 추가할 수 있는 전체 필드 목록은 RootSync 필드를 참조하세요.

    이 매니페스트는 Helm을 소스로 사용하는 RootSync 객체를 만듭니다.

  6. 변경사항을 적용합니다.

    kubectl apply -f root-sync.yaml

루트 저장소의 동기화 상태 확인

nomos status 명령어를 사용하여 루트 저장소의 동기화 상태를 검사할 수 있습니다.

nomos status

다음과 비슷한 출력이 표시됩니다.

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4

RootSync 설치 확인

RootSync 객체를 만들면 구성 동기화에서 root-reconciler 프리픽스가 있는 조정자를 만듭니다. 조정자는 배포로 배포되는 포드입니다. Git 저장소의 매니페스트를 클러스터에 동기화합니다.

root-reconciler 배포의 상태를 확인하면 RootSync 객체가 올바르게 작동하는지 확인할 수 있습니다.

kubectl get -n config-management-system deployment \
    -l configsync.gke.io/sync-name=ROOT_SYNC_NAME

ROOT_SYNC_NAME을 RootSync 이름으로 바꿉니다.

다음과 비슷한 출력이 표시됩니다.

NAME              READY   UP-TO-DATE   AVAILABLE   AGE
root-reconciler   1/1     1            1           3h42m

RootSync 객체의 상태를 확인하는 추가 방법은 RootSync 및 RepoSync 객체 모니터링을 참조하세요.

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

구성 동기화 업그레이드

구성 동기화를 업그레이드하려면 등록된 각 클러스터에 다음 명령어를 실행합니다.

  1. 새 버전에 대한 구성 동기화 매니페스트 및 nomos 명령어를 다운로드합니다.

  2. 구성 동기화 매니페스트를 적용합니다.

    kubectl apply -f config-management-operator.yaml

    이 명령어는 ConfigManagement 연산자 이미지를 업데이트합니다. Kubernetes는 새 버전을 검색하고 새 버전을 사용하여 구성 동기화 포드를 다시 시작합니다. 구성 동기화가 시작되면 새 이미지에 번들된 매니페스트 집합을 적용하는 조정 루프를 실행합니다. 이렇게 하면 각 구성요소 포드가 업데이트되고 다시 시작됩니다.

  3. 모든 클라이언트의 nomos 명령어를 새 버전으로 바꿉니다. 이렇게 변경하면 nomos 명령어가 항상 등록된 모든 클러스터의 상태를 가져오고 클러스터 구성을 확인할 수 있습니다.

구성 동기화 제거

구성 동기화를 제거하려면 다음 단계를 완료합니다.

  1. 중앙 관리자는 루트 저장소를 제거해야 합니다.

    1. 웹훅을 사용 설정했고 리소스를 유지하려면 폐기된 리소스에 대한 드리프트 방지를 사용 중지합니다. 웹훅을 사용 설정하지 않았으면 리소스 유지를 위해 추가 단계를 수행할 필요가 없습니다.

    2. 다음 명령어를 실행하여 RootSync 객체를 삭제합니다.

      kubectl delete -f root-sync.yaml

  2. 저장소를 삭제합니다.

  3. config-management.yaml 파일에서 spec.enableMultiRepo 필드를 삭제합니다.

  4. 클러스터에 config-management.yaml 파일을 적용합니다.

구성 동기화를 완전히 제거하려면 ConfigManagement 연산자 삭제를 참조하세요.

다음 단계