GKE 부가기능으로 설치

이 페이지에서는 Config Connector 부가기능을 사용하여 Google Kubernetes Engine(GKE) 클러스터에 Config Connector를 설치하는 방법을 설명합니다.

Google Cloud 기반 GKE를 사용하는 경우 이 부가기능을 사용하여 Config Connector를 설치하는 것이 좋습니다. 다른 설치 옵션에 대한 자세한 내용은 설치 유형 선택을 참조하세요.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

다음 방법 중 하나를 사용하여 기본 gcloud 설정을 진행합니다.

  • gcloud init를 사용하여 기본값 설정 과정을 진행합니다.
  • gcloud config를 사용하여 프로젝트 ID, 영역, 리전을 개별적으로 설정합니다.

gcloud init 사용

One of [--zone, --region] must be supplied: Please specify location 오류가 표시되면 이 섹션을 완료합니다.

  1. gcloud init를 실행하고 다음 안내를 따르세요.

    gcloud init

    원격 서버에서 SSH를 사용하는 경우 --console-only 플래그를 사용하여 다음 명령어로 브라우저를 실행하지 못하게 할 수 있습니다.

    gcloud init --console-only
  2. 안내를 따라 gcloud에서 Google Cloud 계정을 사용하도록 승인합니다.
  3. 새 구성을 만들거나 기존 구성을 선택합니다.
  4. Google Cloud 프로젝트를 선택합니다.
  5. 기본 Compute Engine 영역을 선택합니다.

gcloud config 사용

  • 기본 프로젝트 ID를 설정합니다.
    gcloud config set project project-id
  • 영역 클러스터를 사용하는 경우 기본 컴퓨팅 영역을 설정합니다.
    gcloud config set compute/zone compute-zone
  • 리전 클러스터를 사용하는 경우 기본 컴퓨팅 리전을 설정합니다.
    gcloud config set compute/region compute-region
  • gcloud를 최신 버전으로 업데이트합니다.
    gcloud components update

Config Connector 부가기능 설치

새 GKE 클러스터를 만들거나 기존 클러스터를 사용 설정하여 Config Connector 부가기능을 사용합니다. Config Connector 부가기능을 설치한 후 Google 서비스 계정 및 네임스페이스로 Config Connector 설치를 구성합니다.

요구사항

Config Connector 부가기능에는 다음과 같은 요구사항이 있습니다.

GKE 클러스터 설정

새 클러스터 또는 기존 클러스터에서 Config Connector 부가기능을 사용할 수 있습니다.

Config Connector 부가기능을 사용 설정하여 새 클러스터 만들기

gcloud 도구 또는 Google Cloud Console을 사용하여 GKE 클러스터를 만들 수 있습니다.

gcloud

gcloud 명령줄 도구를 사용하여 클러스터를 만들려면 다음 명령어를 실행합니다.

gcloud container clusters create CLUSTER_NAME \
    --release-channel CHANNEL \
    --addons ConfigConnector \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-stackdriver-kubernetes

다음을 바꿉니다.

  • CLUSTER_NAME을 GKE 클러스터 이름으로 바꿉니다.
  • GKE 출시 채널을 가지는 CHANNEL, rapidregular가 지원됩니다.
  • PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

Cloud Console

Google Cloud Console로 클러스터를 만들려면 다음 단계를 수행합니다.

  1. Cloud Console에서 Google Kubernetes Engine 메뉴로 이동합니다.

    Google Kubernetes Engine 메뉴로 이동

  2. 클러스터 추가 버튼을 클릭한 후 클러스터 만들기를 클릭합니다. Kubernetes 클러스터 만들기 화면이 표시됩니다.

  3. 클러스터의 이름을 지정합니다.

  4. 지원되는 마스터 버전을 선택합니다.

  5. 나머지 클러스터를 원하는 대로 구성합니다.

  6. 탐색창의 클러스터에서 보안을 클릭합니다.

  7. 워크로드 아이덴티티 사용 체크박스를 선택합니다.

  8. 왼쪽 탐색 창의 클러스터 아래에서 기능을 클릭합니다.

  9. Config Connector 사용 체크박스를 선택합니다.

  10. 만들기를 클릭합니다.

클러스터를 만든 후 ID 만들기로 이동합니다.

기존 클러스터에서 Config Connector 부가기능 사용 설정

기존 GKE 클러스터에서 gcloud 또는 Google Cloud Console로 Config Connector 부가기능을 사용 설정합니다.

기본 요건

기존 클러스터에서 Config Connector 부가기능을 사용 설정하려면 다음 기본 요건을 충족해야 합니다.

Config Connector 부가기능 사용 설정

gcloud 명령줄 도구 또는 Google Cloud Console을 사용하여 기존 GKE 클러스터에서 Config Connector 부가기능을 사용 설정할 수 있습니다.

gcloud

gcloud 명령줄 도구를 사용하여 기존 GKE 클러스터에서 Config Connector 부가기능을 사용 설정하려면 다음 명령어를 실행합니다.

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

CLUSTER_NAME을 GKE 클러스터 이름으로 바꿉니다.

Cloud Console

  1. Cloud Console에서 Google Kubernetes Engine 메뉴로 이동합니다.

    Google Kubernetes Engine 메뉴로 이동

  2. Config Connector를 설치할 클러스터를 선택합니다. 클러스터 세부정보 화면이 표시됩니다.

  3. 수정을 클릭합니다.

  4. 부가기능을 클릭합니다. 메뉴가 펼쳐집니다.

  5. Config Connector에서 사용 설정됨을 선택합니다.

  6. 저장을 클릭하여 클러스터를 업데이트합니다.

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 instance 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는 리소스 구성 또는 기존 네임스페이스에 주석을 사용합니다. 자세한 정보는 리소스 구성을 참조하세요.

탭을 선택하여 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가 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 부가기능이 GKE 클러스터가 포함된 새로운 부 출시버전으로 업그레이드됩니다. 업그레이드될 때마다 클러스터의 리소스가 보존됩니다.

구성 커넥터 제거

Config Connector를 제거하려면 다음 단계를 완료하세요.

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

    kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com --wait=true
    
  2. gcloud 도구 또는 Google Cloud Console을 사용하여 클러스터에서 Config Connector 부가기능을 사용 중지합니다.

    gcloud

    gcloud로 Config Connector 부가기능을 사용 중지하려면 다음 명령어를 실행합니다.

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

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

    Cloud Console

    Google Cloud Console에서 Config Connector 부가기능을 사용 중지하려면 다음 단계를 수행하세요.

    1. Google Cloud Console에서 Google Kubernetes Engine 클러스터 페이지로 이동하고 업데이트하려는 클러스터를 선택합니다.

      Google Kubernetes Engine 메뉴로 이동

    2. 수정을 클릭합니다. 클러스터 수정 화면이 나타납니다.

    3. 부가기능을 클릭합니다.

    4. Config Connector를 선택하고 사용 중지됨을 선택합니다.

    5. 저장을 클릭하여 클러스터를 업데이트합니다.

문제해결

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

Config Connector 부가기능 설치 문제 해결

Config Connector 부가기능을 성공적으로 사용 설정할 수 없으면 다음 오류 메시지가 표시됩니다. Node version 1.15.x-gke.x s unsupported. 이 오류를 해결하려면 GKE 클러스터의 버전이 요구사항을 충족하는지 확인합니다. 클러스터의 모든 유효 버전을 가져오려면 다음 명령어를 실행합니다.

gcloud container get-server-config --format "yaml(validMasterVersions)" \
    --zone ZONE"

ZONE을 Compute Engine 영역으로 바꿉니다.

요구사항을 충족하는 버전을 목록에서 선택합니다. 워크로드 아이덴티티 또는 Kubernetes Engine Monitoring이 사용 중지된 경우에도 오류 메시지가 표시됩니다. 오류를 해결하려면 해당 기능이 사용 설정되었는지 확인합니다.

리소스 조정 권한 문제 해결

Google Cloud가 성공적으로 리소스를 조정할 수 없으면 로그에 다음 오류 메시지가 포함됩니다. The caller does not have permission, forbidden.

이 오류를 조사하려면 다음 단계를 완료하세요.

  1. cloud-sdk 이미지로 셸을 엽니다.
    kubectl run -it \
        --image google/cloud-sdk:slim \
        --serviceaccount cnrm-controller-manager \
        --namespace cnrm-system \
        workload-identity-test
  2. ID를 나열합니다.
    gcloud auth list
  3. 나열된 ID가 리소스에 결합된 Google 서비스 계정과 일치하는지 확인합니다.
  4. Google 서비스 계정에 Google Cloud 리소스 관리를 위해 필요한 역할이 있는지 확인합니다.

다음 단계