kubectl을 사용하여 구성 동기화 수동 설치

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

시작하기 전에

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

로컬 환경 준비

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

  • 구성 동기화가 동기화되는 구성을 포함할 수 있는 Git 저장소 또는 Artifact Registry 또는 Container Registry(미리보기)에 저장된 OCI 이미지를 만들거나 액세스합니다.

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

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

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

클러스터 준비

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

권한 준비

구성 동기화를 설치하는 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. 작업자에게 Git 읽기 전용 액세스 부여 또는 작업자에게 OCI 읽기 전용 액세스 부여(미리보기)
  3. 작업자 구성

작업자 배포

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

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

    gsutil cp gs://config-management-release/released/latest/config-management-operator.yaml config-management-operator.yaml
    
  2. 매니페스트를 적용합니다.

    kubectl apply -f config-management-operator.yaml

이 방법이 실패하면 문제 해결을 참조하세요.

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

Git에 구성을 저장할 경우 작업자에게 Git 읽기 전용 액세스를 부여해야 합니다. 구성을 OCI 이미지로 저장할 경우 작업자에게 OCI 읽기 전용 액세스를 부여해야 합니다.

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

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

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

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

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

  • SSH 키 쌍
  • cookiefile
  • 토큰
  • Google 서비스 계정(Cloud Source Repositories 전용)

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

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. 로컬 디스크에서 비공개 키를 삭제하거나 키를 보호합니다.

  5. 구성 동기화를 구성하고 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 프록시를 사용해야 할 경우 다음 명령어를 실행해서 usernametoken과 함께 보안 비밀에 추가합니다.

    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에 있으면 Google 서비스 계정을 사용하여 구성 동기화에 관리형 클러스터와 동일한 프로젝트의 저장소에 대한 액세스 권한을 부여할 수 있습니다.

Cloud Source Repositories의 저장소를 구성 동기화 저장소로 사용하려면 다음 단계별 안내를 완료하세요.

  1. 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 Console을 사용하여 구성 동기화를 구성하는 경우 URL 필드에 URL을 추가합니다. Google Cloud CLI를 사용하여 구성 동기화를 구성하는 경우 구성 파일의 syncRepo 필드에 URL을 추가합니다.

  2. 구성 동기화를 구성할 때 적절한 인증 유형을 선택하세요. 선택해야 하는 인증 유형은 보유한 클러스터 유형과 워크로드 아이덴티티를 사용 설정한 방법에 따라 다릅니다.

    • 워크로드 아이덴티티 사용 설정: GKE 워크로드 아이덴티티가 사용 설정되었거나 Fleet 워크로드 아이덴티티를 사용하는 경우 이 방법을 사용합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 GKE 및 GKE 외의 클러스터 모두에 이 인증 방법을 사용할 수 있습니다.

    • 워크로드 아이덴티티 사용 설정되지 않음: GKE 클러스터에만 이 방법을 사용할 수 있습니다.

    워크로드 아이덴티티 사용 설정

    1. 필요한 경우 서비스 계정을 만듭니다. 서비스 계정에 source.reader 역할을 부여하여 Cloud Source Repositories에 대한 읽기 액세스 권한을 부여합니다.

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

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

    3. 구성 동기화를 구성, Kubernetes 서비스 계정과 Google 서비스 계정 간에 IAM 정책 바인딩을 만듭니다. 구성 동기화를 처음 구성할 때까지는 Kubernetes 서비스 계정이 생성되지 않습니다.

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

      이 바인딩을 사용하면 구성 동기화 Kubernetes 서비스 계정이 Google 서비스 계정 역할을 합니다.

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

      다음을 바꿉니다.

      • PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 조직의 프로젝트 ID를 추가합니다.

        Fleet 워크로드 아이덴티티를 사용하는 경우 두 개의 서로 다른 프로젝트 ID를 사용할 수 있습니다. serviceAccount:PROJECT_ID에서 클러스터가 등록된 Fleet의 프로젝트 ID를 추가합니다. GSA_NAME@PROJECT_ID에서 Cloud Source Repositories의 저장소에 대한 읽기 액세스 권한이 있는 프로젝트의 프로젝트 ID를 추가합니다.

      • KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다. 루트 저장소의 경우 RootSync 이름이 root-sync이면 KSA_NAMEroot-reconciler입니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME입니다.

        네임스페이스 저장소의 경우 RepoSync 이름이 repo-sync이면 KSA_NAMEns-reconciler-NAMESPACE입니다. 그렇지 않은 경우 ns-reconciler-NAMESPACE-REPO_SYNC_NAME입니다.

      • GSA_NAME: Cloud Source Repositories에 연결하기 위해 사용하려는 커스텀 Google 서비스 계정입니다. 선택한 Google 서비스 계정에 source.reader 역할이 있는지 확인합니다.

    워크로드 아이덴티티가 사용 설정되지 않음

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

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

    Google Cloud Repository 또는 gcenode를 선택하면 Compute Engine 기본 서비스 계정을 사용할 수 있습니다. 기본적으로 Compute Engine 기본 서비스 계정인 PROJECT_ID-compute@developer.gserviceaccount.com에는 동일 프로젝트의 저장소에 대한 source.reader 액세스 권한이 있습니다. 하지만 Cloud Source Repositories가 클러스터 프로젝트와 다른 프로젝트에 있으면 클러스터 프로젝트의 기본 Compute Engine 서비스 계정에 Cloud Source Repositories 프로젝트의 source.reader를 부여해야 합니다.

    다음 명령어를 사용하여 source.reader 역할을 추가할 수 있습니다.

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

    다음을 바꿉니다.

    • PROJECT_ID: 조직의 프로젝트 ID입니다.
    • PROJECT_NUMBER: 조직의 프로젝트 번호입니다.

    노드 풀을 만든 후에는 액세스 범위를 수정할 수 없습니다. 그러나 동일한 클러스터를 사용하는 동안에 액세스 범위가 적절한 새 노드 풀을 만들 수 있습니다. 기본 gke-default 범위에는 cloud-source-repos-ro가 포함되지 않습니다.

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

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

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

하지만 대부분의 사용자는 제한된 이미지에 액세스하기 위해 사용자 인증 정보를 만들어야 합니다. 제한된 읽기 액세스를 갖는 이미지의 경우 gcenode 또는 gcpserviceaccount를 인증 유형으로 사용해서 Google 서비스 계정을 인증에 사용할 수 있습니다.

gcenode

클러스터가 GKE 클러스터이고 워크로드 아이덴티티가 사용 설정되지 않았으면 gcenode를 인증 유형으로 사용할 수 있습니다. 구성 동기화는 Compute Engine 기본 서비스 계정을 사용합니다. Compute Engine 기본 서비스 계정에 Artifact Registry 또는 Container Registry에 대한 읽기 액세스를 부여해야 합니다.

  1. 다음 명령어를 실행하여 환경 변수에 프로젝트 번호를 저장합니다.

    export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID \
        --format=json | jq -r .projectNumber)
    

    여기서 PROJECT_ID프로젝트 ID로 바꿉니다.

  2. Compute Engine 서비스 계정에 Artifact Registry 또는 Container Registry에 대한 읽기 액세스를 부여합니다.

    Artifact Registry

    Artifact Registry에 대한 액세스를 부여하려면 다음 명령어를 실행합니다.

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

    Container Registry

    Container Registry에 대한 액세스를 부여하려면 다음 명령어를 실행합니다.

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

gcpserviceaccount

클러스터에 GKE 워크로드 아이덴티티 또는 Fleet 워크로드 아이덴티티가 사용되는 경우 gcpserviceaccount를 인증 유형으로 사용할 수 있습니다.

  1. 아직 서비스 계정이 없으면 서비스 계정을 만들고 Artifact Registry 또는 Container Registry에 대한 권한을 부여합니다.

    Artifact Registry

    서비스 계정에 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 부여합니다.

    Container Registry

    서비스 계정에 Container Registry 서비스 에이전트(roles/containerregistry.ServiceAgent) IAM 역할을 부여합니다.

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

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

    다음을 바꿉니다.

    • PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 조직의 프로젝트 ID입니다. Fleet 워크로드 아이덴티티를 사용하는 경우 두 개의 서로 다른 프로젝트 ID를 사용할 수 있습니다. serviceAccount:PROJECT_ID의 경우 클러스터가 등록된 Fleet의 프로젝트 ID를 추가합니다. GSA_NAME@PROJECT_ID의 경우 Cloud Source Repositories의 저장소에 대한 읽기 액세스 권한이 있는 프로젝트의 프로젝트 ID를 추가합니다.
    • KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다.
      • 루트 저장소의 경우 RootSync 이름이 root-sync이면 root-reconciler를 추가합니다. 그렇지 않으면 root-reconciler-ROOT_SYNC_NAME을 추가합니다.
      • 네임스페이스 저장소의 경우 RepoSync 이름이 repo-sync이면 ns-reconciler-NAMESPACE를 추가합니다. 그렇지 않으면 ns-reconciler-NAMESPACE-REPO_SYNC_NAME을 추가합니다.
    • GSA_NAME: Artifact Registry 또는 Container Registry에 연결하는 데 사용하려는 커스텀 Google 서비스 계정입니다.
      • Artifact Registry의 경우 서비스 계정에 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할이 있어야 합니다.
      • Container Registry의 경우 서비스 계정에 Container Registry 서비스 에이전트(roles/containerregistry.ServiceAgent) IAM 역할이 있어야 합니다.

작업자 구성

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

  1. 버전 1.7을 사용 중이고 비공개 클러스터에 구성 동기화를 설치하는 경우 포트 8676을 허용하도록 방화벽 규칙을 추가합니다. 구성 동기화 허용 웹훅은 드리프트 방지를 위해 포트 8676을 사용합니다. 버전 1.8.0부터는 포트가 10250으로 전환되며, 비공개 클러스터에서 기본적으로 열립니다. 버전 1.10.0부터는 구성 동기화 허용 웹훅이 기본적으로 사용 중지됩니다.

  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
      # The `preventDrift` field is supported in Anthos Config Management version 1.10.0 and later.
      preventDrift: PREVENT_DRIFT
    

    다음을 바꿉니다.

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

    kubectl apply -f config-management.yaml
    
  4. RootSyncRepoSync CRD가 사용 가능해질 때까지 기다립니다.

    until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done
    
  5. 다음 매니페스트 중 하나를 root-sync.yaml로 저장합니다. 구성을 Git에 저장하는 경우 git 사양 버전을 사용합니다. 구성을 OCI 이미지(미리보기)로 저장하는 경우 OCI 사양 버전을 사용합니다.

    git

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    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
        # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
        noSSLVerify: ROOT_NO_SSL_VERIFY
    

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다. 1.11.0 이전 버전의 경우 root-sync여야 합니다. 버전 1.11.0 이상의 경우 원하는 이름을 지정합니다.
    • 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입니다.
    • ROOT_BRANCH: 동기화할 저장소의 분기를 추가합니다. 이 필드는 선택사항이며 기본값은 master입니다.
    • 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: gcpserviceaccountROOT_AUTH_TYPE으로 추가한 경우 Google 서비스 계정 이메일 주소를 추가합니다. 예를 들면 acm@PROJECT_ID.iam.gserviceaccount.com입니다.

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

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

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

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

    OCI

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    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
    

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다. 1.11.0 이전 버전의 경우 root-sync여야 합니다. 버전 1.11.0 이상의 경우 원하는 이름을 지정합니다.
    • 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 또는 Container Registry의 이미지에 액세스합니다. 워크로드 아이덴티티가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
      • gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.

      필수 필드입니다.

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

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

    이 매니페스트는 OCI 이미지를 소스로 사용하는 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 객체가 올바르게 작동하는지 확인할 수 있습니다.

구성 동기화 버전 1.11.0 이전:

kubectl get -n config-management-system deployment/root-reconciler

구성 동기화 버전 1.11.0 이상:

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. 새 버전에 대한 Anthos Config Management 매니페스트 및 nomos 명령어를 다운로드합니다.

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

    kubectl apply -f config-management-operator.yaml
    

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

  3. 1.9.0 이상 버전에서는 Config Management Operator가 kube-system 네임스페이스가 아닌 config-management-system 네임스페이스에 설치됩니다. 1.9.0 이전 버전에서 1.9.0 이상으로 업그레이드하는 경우 kube-system 네임스페이스에서 이전 Config Management Operator를 삭제해야 합니다.

    kubectl delete -n kube-system serviceaccounts config-management-operator
    kubectl delete -n kube-system deployments config-management-operator
    
  4. 모든 클라이언트의 nomos 명령어를 새 버전으로 바꿉니다. 이렇게 변경하면 nomos 명령어가 항상 등록된 모든 클러스터의 상태를 가져오고 클러스터 구성을 확인할 수 있습니다.

구성 동기화 제거

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

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

    1. 문제 해결 안내에 따라 RootSync 객체에서 관리하는 리소스를 관리 해제하거나 삭제합니다.

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

      kubectl delete -f root-sync.yaml
      
  2. 저장소를 삭제합니다.

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

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

Anthos Config Management를 완전히 제거하려면 Config Management Operator 삭제를 참조하세요.

다음 단계