GKE 부가기능으로 설치

Standard

---

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

각 설치 옵션의 장단점에 대한 자세한 내용은 설치 유형 선택을 참조하세요.

시작하기 전에

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

• Google Kubernetes Engine API를 사용 설정합니다.
Google Kubernetes Engine API 사용 설정
• 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화하세요. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
  참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.

• 구성 커넥터를 설치할 Google Cloud 프로젝트를 생성하거나 선택합니다.

• 이전에 구성 커넥터를 수동으로 설치한 경우 구성 커넥터 부가기능을 설치하기 전에 제거합니다.

  • 클러스터 모드 제거
  • 네임스페이스 모드 제거

구성 커넥터 부가기능 설치

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

참고: 구성 커넥터 부가기능을 사용 설정하면 구성 커넥터가 configconnector-operator-system이라는 네임스페이스를 만듭니다. 이 네임스페이스를 변경하거나 네임스페이스에 리소스를 추가하지 마세요.

요구사항

구성 커넥터 부가기능에는 다음과 같은 요구사항이 있습니다.

• 다음 버전의 GKE 버전을 사용해야 합니다.

  • 1.15.11-gke.5 이상
  • 1.16.8-gke.8 이상
  • 1.17.4-gke.5 이상

• 구성 커넥터를 사용 설정한 클러스터에서 워크로드 아이덴티티 풀 및 Kubernetes Engine Monitoring을 사용 설정해야 합니다.

GKE 클러스터 설정

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

구성 커넥터 부가기능을 사용 설정하여 새 클러스터 만들기

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

gcloud

Google Cloud CLI로 클러스터를 만들려면 다음 명령어를 실행합니다.

gcloud container clusters create CLUSTER_NAME \
    --release-channel CHANNEL \
    --addons ConfigConnector \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --logging=SYSTEM \
    --monitoring=SYSTEM

다음을 바꿉니다.

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

Google Cloud 콘솔

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

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

   Google Kubernetes Engine 메뉴로 이동

2. 만들기를 클릭합니다. Kubernetes 클러스터 만들기 페이지가 나타납니다.

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

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

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

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

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

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

9. 구성 커넥터 사용 체크박스를 선택합니다.

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

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

기존 클러스터에서 구성 커넥터 부가기능 사용 설정

기존 GKE 클러스터에서 gcloud 또는 Google Cloud 콘솔로 구성 커넥터 부가기능을 사용 설정합니다.

기본 요건

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

• 구성 커넥터 부가기능의 요구사항을 충족하는 클러스터가 필요합니다.

• 구성 커넥터를 설치할 클러스터에서 워크로드 아이덴티티를 설정합니다.

  참고: 기존 클러스터에서 워크로드 아이덴티티를 사용 설정해도 클러스터의 기존 노드 풀에서 워크로드 아이덴티티가 자동으로 사용 설정되지 않습니다. 구성 커넥터가 모든 노드 풀에서 실행될 수 있으므로 모든 클러스터의 노드 풀에서 워크로드 아이덴티티를 사용 설정하는 것이 좋습니다.

노드 풀의 워크로드 아이덴티티를 사용 설정하려면 gcloud 명령줄 도구를 사용합니다.

gcloud container node-pools update NODE_POOL \
    --workload-metadata=GKE_METADATA \
    --cluster CLUSTER_NAME

다음을 바꿉니다.

• NODE_POOL을 노드 풀 이름으로 바꿉니다.
• CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

구성 커넥터 부가기능 사용 설정

Google Cloud CLI 또는 Google Cloud 콘솔을 사용하여 기존 GKE 클러스터에서 구성 커넥터 부가기능을 사용 설정할 수 있습니다.

gcloud

기존 GKE 클러스터에서 구성 커넥터 부가기능을 사용 설정하려면 Google Cloud CLI를 사용합니다.

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

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

Google Cloud 콘솔

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

   Google Kubernetes Engine 메뉴로 이동

2. 구성 커넥터를 설치할 클러스터를 선택합니다. 클러스터 세부정보 페이지가 나타납니다.

3. 기능 섹션에서 구성 커넥터 행을 찾아 수정을 클릭합니다.

4. 구성 커넥터 사용 설정 체크박스를 선택하고 변경사항 저장을 클릭하여 클러스터를 업데이트합니다.

ID 만들기

구성 커넥터는 IAM 서비스 계정을 Kubernetes 서비스 계정과 연결하기 위해 Identity and Access Management(IAM) 서비스 계정과 GKE의 워크로드 아이덴티티를 사용하여 Google Cloud 리소스를 만들고 관리합니다.

참고: 이 단계는 클러스터당 한 번만 수행하면 됩니다.

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

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

     gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.

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

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

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/editor"

   다음을 바꿉니다.
   • PROJECT_ID를 프로젝트 ID로 바꿉니다.
   • SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.
   참고: 편집자 역할을 부여하면 IAM 수정과 같은 프로젝트 및 조직 전체 구성을 제외하고 대부분의 구성 커넥터 기능이 허용됩니다. 프로덕션 환경에서는 더 세부적인 권한을 설정하는 것이 좋습니다. IAM 역할에 대한 자세한 내용은 역할 이해를 참조하세요.
3. IAM 서비스 계정과 구성 커넥터가 실행되는 사전 정의된 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로 바꿉니다.

구성 커넥터 구성

참고: 구성 커넥터 부가기능을 사용 설정하면 네임스페이스 모드에서 구성된 ConfigConnector CustomResource가 자동으로 생성됩니다. 레거시와 관련된 이유로 인해 이 작업이 진행됩니다. 클러스터 모드를 사용하도록 ConfigConnector를 구성하려면 다음 단계를 완료해야 합니다. 네임스페이스 모드로 구성 커넥터를 설치하려면 네임스페이스 모드로 구성 커넥터 설치를 참조하세요.

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

연산자를 클러스터 모드로 구성하려면 다음 단계를 완료합니다.

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"
     # Setting `stateIntoSpec` to `Absent` is recommended. It means setting `cnrm.cloud.google.com/state-into-spec`
     # annotation to `absent` for all Config Connector resources created in the cluster in the future.
     # It prevents Config Connector from populating unspecified fields into the spec.
     stateIntoSpec: Absent

   다음을 바꿉니다.
   • SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.
   • PROJECT_ID를 프로젝트 ID로 바꿉니다.
2. kubectl apply로 클러스터에 구성을 적용합니다.

     kubectl apply -f configconnector.yaml

리소스를 만들 위치 지정

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

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

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

kubectl create namespace NAMESPACE

NAMESPACE를 네임스페이스 이름으로 바꿉니다. 예를 들면 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로 바꿉니다.

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

설치 확인

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

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

구성 커넥터가 올바르게 설치된 경우 출력은 다음과 유사합니다.

pod/cnrm-controller-manager-0 condition met

참고: 컨트롤러 포드를 시작하는 데 몇 분이 걸릴 수 있습니다.

구성 커넥터 업그레이드

클러스터의 구성 커넥터 부가기능 업그레이드는 Google Cloud에서 관리됩니다.

업그레이드될 때마다 클러스터의 리소스가 보존됩니다.

Google Cloud에서 구성 커넥터 부가기능 업그레이드를 관리하는 방법을 읽거나 최신 구성 커넥터 버전을 가져오는 방법으로 건너뜁니다.

Google Cloud에서 구성 커넥터 부가기능 업그레이드를 관리하는 방법

GKE 클러스터가 가져오는 구성 커넥터 버전은 클러스터의 GKE 마이너 버전에 따라 전적으로 달라집니다. 예를 들면 다음과 같습니다.

GKE 마이너 버전	구성 커넥터 버전
1.20	1.69.0
1.21	1.69.0
1.22	1.71.0
1.23	1.82.0
1.24	1.89.0

참고: 위 표는 예시일 뿐이며 위의 표기에 의존하여 클러스터에 제공되는 구성 커넥터 버전을 확인하려고 해서는 안 됩니다.

버전이 적합하면 Google Cloud는 최신 GKE 마이너 버전을 새로 출시된 구성 커넥터 버전에 다시 매핑합니다. 이 작업은 일반 또는 공개 출시 채널에서 사용할 수 없을 만큼 새로운 모든 GKE 마이너 버전에 대해 수행됩니다.

클러스터가 가져오는 구성 커넥터 버전은 클러스터의 GKE 마이너 버전에 따라 달라지므로 클러스터의 구성 커넥터 부가기능이 Google Cloud에 의해 자동으로 업그레이드되는 경우는 두 가지가 있습니다.

1. 클러스터가 최신 구성 커넥터 버전에 매핑된 새 GKE 마이너 버전으로 업그레이드되는 경우

   참고: 새 마이너 버전이 최신 구성 커넥터 버전에 매핑되는 경우, GKE 클러스터가 새 마이너 버전으로 업그레이드된 후 구성 커넥터가 업그레이드되는 데 최대 1주일이 걸릴 수 있습니다.

2. 클러스터가 일반 또는 공개 버전 출시 채널에서 사용할 수 없을 정도로 최근에 나온 GKE 마이너 버전에 있으며, Google Cloud는 GKE 마이너 버전을 새로운 구성 커넥터 버전 버전으로 다시 매핑하는 경우

Google Cloud가 GKE 마이너 버전을 다시 매핑하고 기존 클러스터를 새 구성 커넥터 버전으로 업그레이드하는 경우 이 GKE 마이너 버전에 대한 '새 구성 커넥터 버전 출시'를 의미합니다.

광범위한 문제가 탐지된 긴급 상황을 제외하면 안정성을 위해 Google Cloud는 일반 또는 공개 출시 채널 버전에서 사용할 수 있을 만큼 오래된 GKE 마이너 버전에 새 구성 커넥터 버전을 출시하지 않습니다.

최신 Config Connector 버전을 가져오는 방법

구성 커넥터 부가기능을 통해 설치된 구성 커넥터 버전은 최대 12개월 이상 뒤쳐지는 경우가 많습니다. 최신 구성 커넥터 버전이 필요한 경우 구성 컨트롤러로 전환하거나 구성 커넥터를 수동으로 설치하고 업그레이드를 직접 수행하는 것이 좋습니다. 각 옵션의 마이그레이션 안내는 다음과 같습니다.

• 구성 컨트롤러로 전환하려면 구성 컨트롤러 마이그레이션 안내에 따라 기존 구성 커넥터 리소스를 구성 컨트롤러 인스턴스로 마이그레이션합니다.

• 구성 커넥터를 수동으로 설치하려면 안내에 따라 구성 커넥터 부가기능에서 수동 설치로 전환합니다.

구성 커넥터 제거

경고: 구성 컨트롤러 클러스터에서 구성 커넥터를 제거하지 마세요. 제거 시 클러스터에서 예기치 않은 동작이 발생할 수 있으므로 이는 구성 컨트롤러에서 지원되지 않는 변경사항입니다.

구성 커넥터를 제거하려면 다음 단계를 완료하세요.

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

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

2. gcloud CLI 또는 Google Cloud 콘솔을 사용하여 클러스터에서 구성 커넥터 부가기능을 사용 중지합니다.

   gcloud

   gcloud로 구성 커넥터 부가기능을 사용 중지하려면 다음 명령어를 실행합니다.

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

   CLUSTER_NAME을 구성 커넥터 부가기능이 설치된 클러스터 이름으로 바꿉니다.

   Cloud 콘솔

   Google Cloud 콘솔에서 구성 커넥터 부가기능을 사용 중지하려면 다음 단계를 수행하세요.

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

      Google Kubernetes Engine 메뉴로 이동

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

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

   4. 구성 커넥터를 선택하고 사용 중지됨을 선택합니다.

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

다음 단계

• 구성 커넥터 시작하기
• 구성 커넥터의 문제 해결 방법 알아보기