고급 설치 옵션

이 주제에서는 Google Kubernetes Engine(GKE) 클러스터에 Config Connector를 설치하는 두 가지 추가 설치 옵션을 제공합니다.

  • 수동 설치: 수동 방법으로 설치하면 부가기능을 사용하는 것보다 더 신속하게 업데이트할 수 있습니다. 이 방법은 추가 구성 옵션도 제공합니다. 예를 들어 Config Connector 연산자의 CPU 한도를 늘릴 수 있습니다.
  • 네임스페이스 모드: 이 방법은 Config Connector 설치의 확장입니다. 네임스페이스 모드에서는 각각 자체 Google Cloud ID를 사용하는 여러 프로젝트를 관리할 수 있습니다.

이러한 설치 유형에 대한 자세한 정보는 설치 유형 선택을 참조하세요.

Config Connector 연산자 수동 설치

다음 섹션에서는 Config Connector 연산자를 수동으로 설치하는 방법을 보여줍니다.

시작하기 전에

Config Connector 연산자를 수동으로 설치하기 전에 다음 단계를 완료하세요.

Config Connector 연산자 설치

Config Connector는 Kubernetes 연산자를 사용하여 설치를 최신 상태로 유지합니다. 이 연산자를 설치하려면 다음 단계를 완료하세요.

  1. 최신 Config Connector 연산자 tar 파일을 다운로드합니다.

    gsutil cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
    
  2. tar 파일의 압축을 풉니다.

    tar zxvf release-bundle.tar.gz
    
  3. 클러스터에 Config Connector 연산자를 설치합니다.

    kubectl apply -f operator-system/configconnector-operator.yaml
    

ID 만들기

Config Connector는 IAM 서비스 계정을 Kubernetes 서비스 계정과 연결하기 위해 ID 및 액세스 관리(IAM) 서비스 계정과 GKE의 워크로드 아이덴티티를 사용하여 Google Cloud 리소스를 만들고 관리합니다.

ID를 만들려면 다음 단계를 완료하세요.

  1. IAM 서비스 계정을 만듭니다. 기존 서비스 계정을 사용하려면 해당 계정을 사용하여 이 단계를 건너뛸 수 있습니다.

    서비스 계정을 만들려면 다음 명령어를 사용합니다.
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
    SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.
  2. 서비스 계정 만들기에 대한 자세한 내용은 서비스 계정 만들기 및 관리를 참조하세요.

  3. 프로젝트에 대해 높은 권한을 IAM 서비스 계정에 부여합니다.
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/owner"
    다음을 바꿉니다.
    • PROJECT_ID를 프로젝트 ID로 바꿉니다.
    • SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.
  4. IAM 서비스 계정과 Config Connector가 실행되는 사전 정의된 Kubernetes 서비스 계정 간에 IAM 정책 binding을 만듭니다.
    gcloud iam service-accounts add-iam-policy-binding \
    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
        --role="roles/iam.workloadIdentityUser"
    다음을 바꿉니다.
    • SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.
    • PROJECT_ID를 프로젝트 ID로 바꿉니다.

Config Connector 구성

설치를 완료하려면 ConfigConnector CustomResource를 위한 구성 파일을 만든 다음 kubectl apply 명령어를 사용하여 적용합니다. Config Connector 연산자가 Google Cloud 리소스 CRD 및 Config Connector 구성요소를 클러스터에 설치합니다.

연산자를 구성하려면 다음 단계를 완료하세요.

  1. 다음 YAML 파일을 configconnector.yaml이라는 파일에 복사합니다.
    # configconnector.yaml
    apiVersion: core.cnrm.cloud.google.com/v1beta1
    kind: ConfigConnector
    metadata:
      # the name is restricted to ensure that there is only one
      # ConfigConnector resource installed in your cluster
      name: configconnector.core.cnrm.cloud.google.com
    spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
    
    다음을 바꿉니다.
    • SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.
    • PROJECT_ID를 프로젝트 ID로 바꿉니다.
  2. kubectl apply로 클러스터에 구성을 적용합니다.
      kubectl apply -f configconnector.yaml

리소스를 만들 위치 지정

Config Connector는 프로젝트, 폴더 또는 조직별로 리소스를 정리할 수 있으며 이는 Google Cloud에서 리소스를 정리하는 방법과 동일합니다.

Config Connector를 사용하여 리소스를 생성하기 전에 리소스를 생성할 위치를 구성해야 합니다. 리소스를 생성할 위치를 결정하기 위해 Config Connector는 리소스 구성 또는 기존 네임스페이스에 주석을 사용합니다. 자세한 정보는 리소스 구성을 참조하세요.

이 목적을 위한 네임스페이스가 없는 경우 kubectl을 사용하여 네임스페이스를 만듭니다.
kubectl create namespace NAMESPACE

NAMESPACE를 네임스페이스 이름으로 바꿉니다. 예를 들면 config-connector입니다.

탭을 선택하여 Config Connector로 리소스를 만들 위치를 선택합니다.

프로젝트

특정 프로젝트에서 리소스를 만들려면 다음 명령어를 실행하세요.

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

다음을 바꿉니다.

  • NAMESPACE를 네임스페이스 이름으로 바꿉니다.
  • PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

폴더

특정 폴더에 리소스를 만들려면 다음 명령어를 실행합니다.

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

다음을 바꿉니다.

  • NAMESPACE를 네임스페이스 이름으로 바꿉니다.
  • FOLDER_ID를 Google Cloud 폴더 ID로 바꿉니다.

조직

특정 조직의 리소스를 만들려면 다음 명령어를 실행합니다.

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

다음을 바꿉니다.

  • NAMESPACE를 네임스페이스 이름으로 바꿉니다.
  • ORGANIZATION_ID를 Google Cloud 조직 ID로 바꿉니다.

네임스페이스에 주석을 달면 Config Connector는 해당 프로젝트, 폴더 또는 조직에 리소스를 만듭니다. Config Connector가 Kubernetes 네임스페이스를 사용하는 방법에 대한 자세한 내용은 Kubernetes 네임스페이스 및 Google Cloud 프로젝트를 참조하세요.

설치 확인

Config Connector는 cnrm-system이라는 네임스페이스에서 모든 구성요소를 실행합니다. 다음 명령어를 실행하여 pod가 준비되었는지 확인할 수 있습니다.

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

Config Connector가 올바르게 설치된 경우 출력은 다음과 유사합니다.

pod/cnrm-controller-manager-0 condition met

Config Connector 업그레이드

Config Connector 연산자의 최신 버전을 다운로드하고 설치하려면 다음 명령어를 실행합니다.

gsutil cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
tar zxvf release-bundle.tar.gz
kubectl apply -f operator-system/configconnector-operator.yaml

Config Connector 제거

kubectl delete를 사용하여 컨트롤러 구성요소와 함께 Config Connector CRD를 삭제합니다.

kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
    --wait=true

Config Connector 연산자를 제거하려면 다음 명령어를 실행합니다.

kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true

네임스페이스 모드를 사용하여 Config Connector 설치

다음 섹션에서는 네임스페이스 모드를 사용 설정하는 방법을 설명합니다.

시작하기 전에

네임스페이스 모드에서 실행되도록 Config Connector를 구성하기 전에 Config Connector GKE 부가기능 또는 수동으로 설치된 Config Connector 연산자를 사용 설정합니다.

네임스페이스 모드에서 실행되도록 Config Connector 구성

네임스페이스 모드를 사용하려면 다음 단계를 완료하세요.

  1. 다음 YAML 매니페스트를 configconnector.yaml이라는 파일에 복사합니다.

    apiVersion: core.cnrm.cloud.google.com/v1beta1
    kind: ConfigConnector
    metadata:
      # the name is restricted to ensure that there is only ConfigConnector resource installed in your cluster
      name: configconnector.core.cnrm.cloud.google.com
    spec:
     mode: namespaced
    
  2. kubectl apply로 클러스터에 구성을 적용합니다.

    kubectl apply -f configconnector.yaml
    

네임스페이스의 리소스를 관리하도록 Config Connector 구성

다음 섹션에서는 Config Connector를 설치하는 Google Cloud 프로젝트를 호스트 프로젝트 또는 HOST_PROJECT_ID라고 부릅니다. 리소스를 관리하는 다른 프로젝트는 관리형 프로젝트 또는 MANAGED_PROJECT_ID라고 부릅니다. 이는 Config Connector를 사용하여 클러스터와 동일한 프로젝트에 Google Cloud 리소스를 만들려는 경우에만 동일한 프로젝트일 수 있습니다.

네임스페이스 만들기

Google Cloud 리소스를 구성하는 데 사용할 네임스페이스가 이미 있는 경우 이 단계를 건너뛰어도 됩니다.

kubectl을 사용하여 다음 명령어를 실행하여 새 네임스페이스를 만듭니다.

kubectl create namespace NAMESPACE

NAMESPACE를 네임스페이스 이름으로 바꿉니다.

ID 만들기

IAM(Identity and Access Management) 서비스 계정을 만들고 IAM 서비스 계정과 Config Connector의 Kubernetes 서비스 계정 간에 binding을 만듭니다.

  1. IAM 서비스 계정을 만듭니다. 기존 서비스 계정이 있는 경우 새 서비스 계정을 만드는 대신 해당 계정을 사용할 수 있습니다. gcloud를 사용해서 다음 명령어를 실행하여 서비스 계정을 만듭니다.

    gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
    

    다음을 바꿉니다.

    • NAMESPACE_GSA를 네임스페이스에 결합된 Google 서비스 계정(GSA) 이름으로 바꿉니다.
    • HOST_PROJECT_ID를 호스트 프로젝트의 ID로 바꿉니다.

    서비스 계정 만들기에 대한 자세한 내용은 서비스 계정 만들기 및 관리를 참조하세요.

  2. 관리형 프로젝트에 대해 높은 권한을 IAM 서비스 계정에 부여합니다.

    gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
        --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/owner"
    

    다음을 바꿉니다.

    • MANAGED_PROJECT_ID를 관리 프로젝트 ID로 바꿉니다.
    • NAMESPACE_GSA를 네임스페이스에 결합된 Google 서비스 계정 이름으로 바꿉니다.
    • HOST_PROJECT_ID를 호스트 프로젝트의 ID로 바꿉니다.
  3. IAM 서비스 계정과 Config Connector Kubernetes 서비스 계정 간에 IAM 정책 binding을 만듭니다. 다음 gcloud 명령어를 실행하여 서비스 계정을 결합합니다.

    gcloud iam service-accounts add-iam-policy-binding \
    NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
        --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
        --role="roles/iam.workloadIdentityUser" \
        --project HOST_PROJECT_ID
    

    다음을 바꿉니다.

    • HOST_PROJECT_ID를 호스트 프로젝트의 ID로 바꿉니다.
    • NAMESPACE_GSA를 네임스페이스에 결합된 Google 서비스 계정 이름으로 바꿉니다.
    • NAMESPACE를 네임스페이스로 바꿉니다.
  4. 호스트 프로젝트의 Google Cloud 운영 제품군에 Prometheus 측정항목을 게시할 수 있는 권한을 IAM 서비스 계정에 부여합니다.

    gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
        --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/monitoring.metricWriter"
    

    다음을 바꿉니다.

    • HOST_PROJECT_ID를 호스트 프로젝트의 ID로 바꿉니다.
    • NAMESPACE_GSA를 네임스페이스에 결합된 Google 서비스 계정 이름으로 바꿉니다.

ConfigConnectorContext 만들기

Google Cloud 리소스를 만들려면 사용하려는 네임스페이스에 ConfigConnectorContext 객체를 추가하여 네임스페이스를 감시하도록 Config Connector를 구성해야 합니다.

ConfigConnectorContext를 만들려면 다음 단계를 완료합니다.

  1. 다음 YAML 매니페스트를 configconnectorcontext.yaml이라는 파일에 복사합니다.

    apiVersion: core.cnrm.cloud.google.com/v1beta1
    kind: ConfigConnectorContext
    metadata:
      # you can only have one ConfigConnectorContext per namespace
      name: configconnectorcontext.core.cnrm.cloud.google.com
      namespace: NAMESPACE
    spec:
      googleServiceAccount: "NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com"
    

    다음을 바꿉니다.

    • NAMESPACE를 네임스페이스 이름으로 바꿉니다.
    • NAMESPACE_GSA를 네임스페이스에 결합된 Google 서비스 계정 이름으로 바꿉니다.
    • HOST_PROJECT_ID를 호스트 프로젝트의 ID로 바꿉니다.
  2. kubectl로 클러스터에 파일을 적용합니다.

    kubectl apply -f configconnectorcontext.yaml
    
  3. 다음 명령어를 실행하여 Config Connector 연산자가 kubectl로 네임스페이스에 대해 Kubernetes 서비스 계정을 만들었는지 확인합니다.

    kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
    

    NAMESPACE를 네임스페이스의 이름으로 바꿉니다.

  4. 다음 명령어를 실행하여 Config Connector 컨트롤러 pod가 kubectl로 네임스페이스에 대해 실행 중인지 확인합니다.

    kubectl wait -n cnrm-system \
        --for=condition=Ready pod \
        -l cnrm.cloud.google.com/component=cnrm-controller-manager \
        -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE
    

    NAMESPACE를 네임스페이스의 이름으로 바꿉니다.

    Config Connector 컨트롤러가 실행 중인 경우 출력은 다음과 비슷합니다.

    cnrm-controller-manager-abcdefghijk-0 condition met.
    

네임스페이스에서 더 이상 리소스를 관리하지 않도록 Config Connector 구성

더 이상 네임스페이스를 관리하지 않도록 Config Connector를 구성하려면 네임스페이스에서 모든 Config Connector 리소스를 삭제하고 네임스페이스의 ConfigConnectorContext를 삭제합니다.

네임스페이스에서 Config Connector 리소스 삭제

ConfigConnectorContext 삭제를 완료하려면 네임스페이스에서 모든 Config Connector 리소스를 삭제합니다.

  1. 네임스페이스에서 모든 Config Connector 리소스를 검색하려면 각 Config Connector 커스텀 리소스 정의에 대해 모든 리소스를 나열합니다.

    kubectl get crds --selector cnrm.cloud.google.com/managed-by-kcc=true \
    -o=jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | xargs -n 1 \
    kubectl get -o jsonpath='{range .items[*]}{" Kind: "}{@.kind}{"Name: "}{@.metadata.name}{"\n"}{end}' \
    --ignore-not-found -n NAMESPACE
    

    NAMESPACE를 네임스페이스의 이름으로 바꿉니다.

  2. 모든 Config Connector 리소스를 삭제하려면 이전 단계의 출력에 있는 각 리소스에 대해 delete 명령을 실행합니다.

    kubectl delete -n NAMESPACE KIND NAME
    

    다음을 바꿉니다.

    • NAMESPACE: 네임스페이스의 이름입니다.
    • KIND: 이전 단계에서 검색한 리소스의 종류입니다.
    • NAME: 이전 단계에서 검색된 리소스의 이름입니다.

ConfigConnectorContext 삭제

네임스페이스에서 더 이상 Config Connector 리소스를 관리하지 않도록 Config Connector를 구성하려면 네임스페이스에서 ConfigConnectorContext를 삭제합니다.

  kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com

NAMESPACE를 네임스페이스의 이름으로 바꿉니다.

모든 Config Connector 리소스가 네임스페이스에서 제거될 때까지 ConfigConnectorContext 삭제가 완료되지 않습니다.

비연산자 설치에서 업그레이드

Config Connector 버전 1.33.0 이상에서는 GKE 부가기능 또는 연산자를 통한 설치만 지원합니다.

연산자로 업그레이드하고 모든 Config Connector 리소스를 유지하려면 CRD를 제외한 모든 Config Connector 시스템 구성요소를 삭제한 후 연산자를 설치해야 합니다.

  1. 다음 명령어를 실행하여 Config Connector 시스템의 CRD를 제외한 구성요소를 삭제합니다.

    kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
    kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
    kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
    kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
    
  2. GKE 부가기능 또는 연산자로 Config Connector를 설치합니다.

부가기능에서 수동 설치로 전환

부가기능으로 설치된 경우 Config Connector 버전이 설치된 GKE 버전에 직접 연결됩니다.

수동 설치를 사용하면 수동 업그레이드 비용으로 더 빠르게 업그레이드할 수 있습니다.

모든 리소스를 안전하게 보관하면서 전환하려면 다음 안내를 따르세요.

  1. ConfigConnector 또는 ConfigConnectorContext 객체를 삭제하지 않고 부가기능을 사용 중지합니다.

    gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
    

    CLUSTER_NAME을 Config Connector가 설치된 클러스터의 이름으로 바꿉니다.

  2. 안내에 따라 원하는 버전의 수동 연산자를 설치합니다.

문제 해결

다음 섹션에서는 Config Connector 설치에 대한 문제 해결 팁을 제공합니다.

리소스 조정 권한 문제 해결

Config Connector가 리소스를 조정할 수 없고 로그에 오류 메시지(The caller does not have permission, forbidden.)가 포함된 경우 GKE 클러스터 또는 노드 풀에서 워크로드 아이덴티티가 사용 설정되지 않았을 수 있습니다.

문제를 조사하려면 다음 단계를 완료하세요.

  1. 다음 Pod 구성을 wi-test.yaml로 저장합니다.
    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: cnrm-system
    spec:
      containers:
      - image: google/cloud-sdk:slim
        name: workload-identity-test
        command: ["sleep","infinity"]
      serviceAccountName: cnrm-controller-manager
    
  2. GKE 클러스터에 Pod를 만듭니다.
    kubectl apply -f wi-test.yaml
    
  3. Pod에서 대화형 세션을 엽니다.
    kubectl exec -it workload-identity-test \
      --namespace cnrm-system \
      -- /bin/bash
    
  4. ID를 나열합니다.
    gcloud auth list
    
  5. 나열된 ID가 리소스에 결합된 Google 서비스 계정과 일치하는지 확인합니다.

    Compute Engine 기본 서비스 계정이 표시되면 워크로드 아이덴티티가 GKE 클러스터 또는 노드 풀에서 사용 설정되지 않은 것입니다.

  6. 대화형 세션을 종료한 후 GKE 클러스터에서 Pod를 삭제합니다.
    kubectl delete pod workload-identity-test \
    --namespace cnrm-system
    

다음 단계