구성 동기화 설치

구성 동기화 연산자는 Kubernetes 클러스터에서 구성 동기화를 관리하는 컨트롤러입니다. 구성 동기화를 사용하여 관리하려는 각 클러스터에 연산자를 설치하고 구성하려면 다음 단계를 따르세요.

리소스 요청

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

구성요소 CPU 메모리
구성 동기화 연산자 100m 20Mi
구성 동기화 360m 210Mi

시작하기 전에

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

로컬 환경 준비

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

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

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

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

클러스터 준비

클러스터는 GKE 버전 1.14.x 이상을 실행해야 합니다.

권한 준비

Config Sync를 설치하는 Google Cloud 사용자에게는 클러스터에서 새 역할을 만들 수 있는 ID 및 액세스 관리(IAM) 권한이 필요합니다.

클러스터 등록

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

  1. Operator 배포합니다.
  2. 연산자에게 Git에 대한 읽기 전용 액세스 권한을 부여합니다.
  3. 연산자를 구성합니다.

연산자 배포

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

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

    gsutil cp gs://config-management-release/released/latest/config-sync-operator.yaml config-sync-operator.yaml
    
  2. CRD를 적용합니다.

    kubectl apply -f config-sync-operator.yaml

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

연산자에게 Git에 대한 읽기 전용 액세스 권한 부여

구성 동기화는 저장소에 커밋된 구성을 읽고 이를 클러스터에 적용할 수 있도록 Git 저장소에 대한 읽기 전용 액세스 권한이 필요합니다. 사용자 인증 정보가 필요한 경우 등록된 각 클러스터의 git-creds 보안 비밀에 저장됩니다.

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

하지만 대부분의 사용자는 저장소에 대한 읽기 액세스가 제한되므로 사용자 인증 정보를 만들어야 합니다. 구성 동기화는 다음과 같은 인증 메커니즘을 지원합니다.

  • SSH 키 쌍
  • cookiefile
  • 토큰
  • Google 서비스 계정(Google 소스 저장소만)

저장소에서 무엇을 지원하는지에 따라 선택할 수 있는 메커니즘이 다릅니다. 모든 메커니즘을 사용할 수 있는 경우에는 SSH 키 쌍을 사용하는 것이 좋습니다. GitHub, Cloud Source Repositories, Bitbucket 모두 SSH 키 쌍 사용을 지원합니다. 조직에서 저장소를 호스팅하고 지원되는 인증 방법을 모르는 경우 관리자에게 문의하세요.

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

cookiefile

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

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

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

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

    /path/to/COOKIEFILE을 적절한 경로와 파일 이름으로 바꿉니다.

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

토큰

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

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

  1. GitHub 또는 Bitbucket을 사용하여 토큰을 만듭니다.

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

    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: 이전 단계에서 만든 토큰을 추가합니다.
  3. 토큰이 로컬에서 계속 필요하면 토큰을 보호합니다. 그렇지 않으면 삭제합니다.

Google 서비스 계정

저장소가 Cloud Source Repositories에 있으면 secretType: gcenode를 사용하여 관리형 클러스터와 동일한 프로젝트의 저장소에 구성 동기화 액세스 권한을 부여할 수 있습니다.

기본 요건

시작하기 전에 다음 기본 요건을 충족하는지 확인하세요.

  • 클러스터의 노드 액세스 범위에는 cloud-source-repos-ro가 포함되어야 합니다. 기본적으로 Compute Engine 기본 서비스 계정 PROJECT_ID-compute@developer.gserviceaccount.com에는 동일한 프로젝트의 저장소에 대한 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: 조직의 프로젝트 번호를 추가합니다.
  • 클러스터의 노드 액세스 범위에는 cloud-source-repos-ro가 포함되어야 합니다. 클러스터 생성 시 지정된 --scopes 목록에 cloud-source-repos-ro를 포함하거나 클러스터 생성 시 cloud-platform 범위를 사용하여 이 범위를 추가할 수 있습니다.

    gcloud container clusters create example-cluster --scopes=cloud-platform
    

Cloud Source Repositories를 SyncRepo로 사용

이러한 기본 요건이 충족되면 연산자를 구성할 때 원하는 Cloud Source Repositories의 URL에 spec.git.syncRepo를 설정합니다.

Cloud Source Repositories를 SyncRepo로 사용하려면 다음 단계를 완료합니다.

  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
    
  3. URL을 syncRepo로 추가합니다. 예를 들면 다음과 같습니다.

    spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr
    

워크로드 아이덴티티로 Cloud Source Repositories 사용

클러스터에서 워크로드 아이덴티티가 사용 설정된 경우 secretType: gcenode를 사용하려면 추가 단계가 필요합니다. 위 단계를 완료하고 구성 동기화 구성(다음 섹션에서 수행)을 완료한 다음 Kubernetes 서비스 계정과 Google 서비스 계정 간에 IAM 정책 binding을 생성합니다. 구성 동기화를 처음 구성할 때까지는 Kubernetes 서비스 계정이 생성되지 않습니다.

이 binding을 사용하면 구성 동기화 Kubernetes 서비스 계정을 Compute Engine 기본 서비스 계정으로 사용할 수 있습니다.

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

다음으로 바꿉니다. * PROJECT_ID: 조직의 프로젝트 ID * PROJECT_NUMBER: 조직의 프로젝트 번호

binding을 만든 후 Compute Engine 기본 서비스 계정의 이메일 주소를 사용하여 구성 동기화 Kubernetes 서비스 계정에 annotation을 추가합니다.

kubectl annotate serviceaccount -n config-management-system importer \
  iam.gke.io/gcp-service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

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

연산자 구성

구성 동기화의 동작을 구성하려면 ConfigManagement CustomResource의 구성 파일을 만든 후 kubectl apply 명령어를 사용하여 적용합니다.

  1. config-management.yaml 파일을 만들고 이 파일에 아래 YAML 파일을 복사합니다.

    # config-management.yaml
    
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      # clusterName is required and must be unique among all managed clusters
      clusterName: CLUSTER_NAME
      git:
        syncRepo: REPO
        syncBranch: BRANCH
        secretType: TYPE
        policyDir: "DIRECTORY"
    

    다음을 바꿉니다.

    • CLUSTER_NAME: 이 구성을 적용할 등록된 클러스터의 이름을 추가합니다.
    • REPO: 정보 소스로 사용할 Git 저장소의 URL을 추가합니다. 필수 입력란입니다.
    • BRANCH: 동기화할 저장소의 분기를 추가합니다. 기본값은 기본(마스터) 분기입니다.
    • TYPE: 다음 SecretTypes 중 하나를 추가합니다.

      • none
      • ssh
      • cookiefile
      • token
      • gcenode
    • : DIRECTORY저장소 내에서 동기화할 정책 계층 구조 최상위까지의 경로를 추가합니다. 기본값은 저장소의 루트 디렉터리입니다.

    spec 필드에 추가할 수 있는 필드의 전체 목록은 다음 Git 저장소 구성 섹션을 참조하세요. spec 필드 이외의 구성 값을 변경하지 마세요.

  2. kubectl apply 명령어로 구성을 적용합니다.

    kubectl apply -f config-management.yaml
    

    각 클러스터 또는 각 유형의 클러스터마다 별도의 구성 파일을 만들어야 할 수도 있습니다. --context 옵션을 사용하여 클러스터를 지정할 수 있습니다.

    kubectl apply -f config-management1.yaml --context=CLUSTER_NAME
    

    CLUSTER_NAME을 사용하려는 클러스터 이름으로 바꿉니다.

Git 저장소 구성
설명
spec.git.syncRepo 정보 소스로 사용할 Git 저장소의 URL입니다. 필수 항목입니다.
spec.git.syncBranch 동기화할 저장소의 분기입니다. 기본값: master
spec.git.policyDir 동기화할 저장소의 최상위 수준을 나타내는 Git 저장소 내의 경로입니다. 기본값: 저장소의 루트 디렉터리
spec.git.syncWait 연속 동기화 간격(초)입니다. 기본값: 15
spec.git.syncRev 체크아웃할 Git 버전(태그 또는 해시)입니다. 기본값: HEAD
spec.git.secretType Git 저장소에 액세스할 수 있도록 구성된 보안 비밀 유형입니다. ssh, cookiefile, token, gcenode 또는 none 중 하나입니다. 필수 항목입니다.
spec.sourceFormat unstructured로 설정하면 비계층적 저장소를 구성합니다. 기본값: hierarchy
Git 저장소의 프록시 구성

조직 보안 정책에 따라 HTTP(S) 프록시를 통해 트래픽을 라우팅해야 하는 경우 구성 동기화가 프록시 URI를 사용하여 Git 호스트와 통신하도록 구성할 수 있습니다.

설명
spec.git.proxy.httpProxy httpProxy는 Git 저장소에 액세스하는 데 사용되는 HTTP_PROXY env 변수를 정의합니다.
spec.git.proxy.httpsProxy httpsProxy는 Git 저장소에 액세스하는 데 사용되는 HTTPS_PROXY env 변수를 정의합니다.

httpProxyhttpsProxy 필드가 모두 지정되면 httpProxy가 무시됩니다.

ConfigManagement 객체 동작 구성
설명
spec.clusterName ClusterSelector에서 클러스터를 함께 그룹화하는 데 사용되는 클러스터의 사용자 정의 이름입니다. 구성 동기화 설치 내에서 고유합니다.

설치 확인

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

연산자가 성공적으로 배포되면 kube-system 네임스페이스에 있는 config-management-operator로 시작하는 이름의 Pod에서 실행됩니다. Pod를 초기화하는 데 시간이 다소 걸릴 수 있습니다. Pod가 실행 중인지 확인합니다.

kubectl -n kube-system get pods | grep config-management

Pod가 실행 중인 경우 명령어의 응답은 다음과 비슷하지만 동일하지는 않습니다.

config-management-operator-6f988f5fdd-4r7tr 1/1 Running 0 26s

config-management-system 네임스페이스가 존재하는지 확인할 수도 있습니다.

kubectl get ns | grep 'config-management-system'

명령어의 출력은 다음과 비슷합니다.

config-management-system Active 1m

명령어가 여기에 표시된 출력과 비슷한 출력을 반환하지 않으면 로그에서 잘못된 점을 확인합니다.

kubectl -n kube-system logs -l k8s-app=config-management-operator

또한 kubectl get events를 사용하여 구성 동기화가 이벤트를 만들었는지도 확인할 수 있습니다.

kubectl get events -n kube-system

누락되거나 잘못된 git-creds 보안 비밀 등 즉시 감지되지 않는 잘못된 구성이 있을 수 있습니다. 문제 해결 단계는 이 주제의 문제 해결 섹션에서 유효하지만 잘못된 ConfigManagement 객체를 참조하세요.

구성 동기화 버전 업그레이드

이 섹션에서는 현재 버전으로 업그레이드하기 위한 일반적인 안내를 제공합니다. 업그레이드하기 전에 출시 노트에서 구체적인 안내를 확인하세요.

등록된 각 클러스터에 다음 명령어를 실행합니다.

  1. 새 버전에 대한 연산자 매니페스트 및 nomos 명령어를 다운로드합니다.

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

    kubectl apply -f config-sync-operator.yaml
    

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

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

클러스터에서 연산자 삭제

클러스터에서 연산자를 삭제하려면 다음 안내를 따르세요. 구성 동기화를 사용하여 더 이상 관리하지 않으려는 각 클러스터에 다음 단계를 수행해야 합니다.

  1. 클러스터에서 ConfigManagement 객체를 삭제합니다.

    kubectl delete configmanagement --all

    다음 작업이 수행됩니다.

    • 구성 동기화에서 클러스터에 생성된 ClusterRole 및 ClusterRoleBinding이 클러스터에서 삭제됩니다.
    • 구성 동기화로 설치된 허용 컨트롤러 구성이 모두 삭제됩니다.
    • config-management-system 네임스페이스의 콘텐츠는 삭제되지만 git-creds 보안 비밀은 삭제되지 않습니다. config-management-system 네임스페이스가 없으면 구성 동기화가 작동할 수 없습니다. 구성 동기화에서 생성되거나 수정된 CustomResourceDefinition은 CustomResourceDefinition이 생성 또는 수정된 클러스터에 삭제됩니다. 연산자를 실행하는 데 필요한 CRD(CustomResourceDefinition)는 Kubernetes의 관점에서 연산자를 설치한 사용자가 추가했으므로 아직 있습니다. 다음 단계에서 삭제에 대한 정보를 제공합니다.
  2. 이 시점에서 연산자는 클러스터에 여전히 존재하지만 아무것도 수행하지 않습니다.

    GKE를 사용 중이며 더 이상 구성 동기화를 사용하지 않으려면 다음 단계를 수행하여 연산자를 삭제하면 됩니다.

    1. 이전 단계에서 ConfigManagement 객체를 삭제한 후 config-management-system 네임스페이스가 비어 있는지 확인합니다. kubectl -n config-management-system get all 명령어가 No resources found.를 반환할 때까지 기다립니다.

    2. config-management-system 네임스페이스를 삭제합니다.

      kubectl delete ns config-management-system
      
    3. ConfigManagement CustomResourceDefinition을 삭제합니다.

      kubectl delete crd configmanagements.configmanagement.gke.io
      
    4. kube-system 네임스페이스에서 모든 구성 동기화 객체를 삭제합니다.

      kubectl -n kube-system delete all -l k8s-app=config-management-operator
      

문제 해결

다음 섹션은 Config Sync 설치 문제를 해결하는 데 유용합니다.

불충분한 CPU

kubectl get events의 출력에는 FailedScheduling 유형의 이벤트가 포함될 수 있습니다. 이벤트는 다음 예시와 같이 표시됩니다.

LAST SEEN   TYPE      REASON              OBJECT                                             MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

이 오류를 해결하려면 다음 옵션 중 하나를 선택합니다.

  • 기존 GKE 노드 풀에 노드 추가
  • 더 큰 노드로 노드 풀 만들기

오류: 추가 권한 부여 시도

다음 오류가 표시되는 경우:

Error from server (Forbidden): error when creating "config-sync-operator.yaml": clusterroles.rbac.authorization.k8s.io "config-management-operator" is forbidden: attempt to grant extra privileges: [...] ruleResolutionErrors=[]

config-management-operator.yaml 파일을 적용하려고 하면 설치에 필요한 만큼의 권한이 없습니다. 권한 준비를 검토하여 필요한 권한이 있는지 확인하세요.

유효하지만 잘못된 ConfigManagement 객체

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

문제가 없는 유효한 설치 상태는 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 보안 비밀을 만드는 것을 잊어버린 경우에는 보안 비밀을 생성하는 즉시 구성 동기화가 이를 감지하므로 구성을 다시 적용할 필요가 없습니다.

다음 단계