구성 컨트롤러 설정

이 페이지에서는 구성 컨트롤러를 설정하는 방법을 보여줍니다.

구성 컨트롤러는 Kubernetes를 기반으로 관리되는 제어 영역을 제공합니다. 또한 구성 컨트롤러 인스턴스는 정책 컨트롤러, 구성 동기화, 구성 커넥터가 사전 설치됩니다. 이러한 구성요소를 사용하면 Kubernetes 도구 및 워크플로를 활용하여 Google Cloud 리소스를 관리하고 GitOps 워크플로를 사용하여 일관성을 얻을 수 있습니다. 자세한 내용은 구성 컨트롤러 개요를 참조하세요.

처음 구성 컨트롤러 인스턴스를 만드는 경우 빠른 시작: 구성 컨트롤러로 리소스 관리를 참조하세요.

제한사항

  • 구성 컨트롤러가 완전 관리형이기 때문에 Fleet에 등록할 수 없습니다.

시작하기 전에

구성 컨트롤러를 설정하기 전에 다음 단계를 완료해야 합니다.

  1. 이 안내에서 사용되는 Google Cloud CLI를 제공하는 Google Cloud CLI를 설치하고 초기화합니다. Cloud Shell을 사용하는 경우 Google Cloud CLI가 이미 설치되어 있습니다.

  2. 기본적으로 Google Cloud CLI에서 설치되지 않으므로 kubectl을 설치합니다.

    gcloud components install kubectl

  3. 구성 컨트롤러를 호스팅하려는 Google Cloud 프로젝트를 설정합니다.

    gcloud config set project PROJECT_ID

    PROJECT_ID를 구성 컨트롤러를 호스팅하는 Google Cloud 프로젝트로 바꿉니다.

  4. 필요한 API를 사용 설정합니다.

    gcloud services enable krmapihosting.googleapis.com \
    anthos.googleapis.com  \
    cloudresourcemanager.googleapis.com \
    serviceusage.googleapis.com

구성 컨트롤러 인스턴스 만들기

Standard 클러스터 또는 Autopilot 클러스터로 지원되는 구성 컨트롤러 인스턴스를 만들 수 있습니다. 두 유형 모두 비공개입니다.

더 많은 맞춤화 옵션이 필요하면 표준 클러스터를 선택합니다. 빠른 설치, 수평 및 수직 포드 자동 확장, 향상된 보안 기능(예: Container-Optimized OS, 보안 GKE 노드, GKE용 워크로드 아이덴티티 제휴, 보안 부팅)이 필요하면 Autopilot 클러스터를 선택합니다.

  1. 구성 컨트롤러 인스턴스를 만듭니다.

    표준

    비공개 Standard GKE 클러스터로 지원되는 구성 컨트롤러 인스턴스를 만듭니다.

    gcloud anthos config controller create CONFIG_CONTROLLER_NAME \
    --location=LOCATION

    다음을 바꿉니다.

    • CONFIG_CONTROLLER_NAME: 구성 컨트롤러 인스턴스에 지정할 이름입니다.

    • LOCATION: 다음 리전 중 하나를 추가합니다.

      • us-central1
      • us-east1
      • us-east4
      • us-east5
      • us-west1
      • us-west2
      • us-west3
      • us-west4
      • us-south1
      • northamerica-northeast1
      • northamerica-northeast2
      • southamerica-west1
      • southamerica-east1
      • europe-north1
      • europe-west1
      • europe-west3
      • europe-west4
      • europe-west6
      • europe-west9
      • europe-west10
      • europe-west12
      • europe-central2
      • europe-southwest1
      • australia-southeast1
      • australia-southeast2
      • asia-east1
      • asia-east2
      • asia-northeast1
      • asia-northeast2
      • asia-northeast3
      • asia-southeast1
      • asia-southeast2
      • asia-south1
      • asia-south2
      • africa-south1
      • me-west1
      • me-central1

      구성 컨트롤러 인스턴스가 생성된 리전입니다. 다른 리전은 지원되지 않습니다.

    표준 구성 컨트롤러 인스턴스를 만드는 경우 여러 선택적인 매개변수를 설정할 수 있습니다. 전체 옵션 목록은 gcloud anthos config controller create 문서를 참조하세요.

    Autopilot

    비공개 Autopilot GKE 클러스터로 지원되는 구성 컨트롤러 인스턴스를 만들려면 다음 명령어를 실행합니다.

    gcloud anthos config controller create CONFIG_CONTROLLER_NAME \
    --location=LOCATION \
    --full-management

    다음을 바꿉니다.

    • CONFIG_CONTROLLER_NAME: 컨트롤러에 지정할 이름입니다.

    • LOCATION: 다음 리전 중 하나를 추가합니다.

      • us-central1
      • us-east1
      • us-east4
      • us-east5
      • us-west2
      • northamerica-northeast1
      • northamerica-northeast2
      • europe-north1
      • europe-west1
      • europe-west3
      • europe-west6
      • australia-southeast1
      • australia-southeast2
      • asia-northeast1
      • asia-northeast2
      • asia-southeast1

      다른 리전은 지원되지 않습니다.

    이 작업은 완료하는 데 최대 15분이 걸릴 수 있습니다. 만들기 중에 수행되는 작업을 관찰하려면 Google Cloud 콘솔에서 로그 탐색기를 보면 됩니다.

    로그 탐색기로 이동

    만들기 중에 오류가 발생하면 구성 컨트롤러 문제 해결에서 일반적인 문제 해결 안내를 참조하세요.

  2. 구성 컨트롤러가 생성되었는지 확인하려면 구성 컨트롤러 인스턴스 목록을 확인합니다.

    gcloud anthos config controller list --location=LOCATION

    상태 열에 RUNNING 값이 표시됩니다. 상태가 CREATING이면 구성 컨트롤러 인스턴스가 아직 생성되는 중이므로 계속 기다려야 합니다. ERROR가 표시되면 직접 해결할 수 없는 문제가 발생한 것입니다. 도움이 필요한 경우 Google Cloud 지원팀에 문의하세요.

  3. 구성 컨트롤러 엔드포인트와 통신하려면 적합한 사용자 인증 정보 및 엔드포인트 정보를 가져옵니다.

    gcloud anthos config controller get-credentials CONFIG_CONTROLLER_NAME \
    --location LOCATION

구성 컨트롤러 인스턴스 사용

이제 구성 컨트롤러 인스턴스를 만들었으므로, 설치된 구성요소를 사용해서 다음 태스크를 완료할 수 있습니다.

  • 구성 커넥터를 사용하여 Google Cloud 리소스를 만듭니다. 구성 컨트롤러에 사용하려는 기존 Google Cloud 리소스가 있으면 기존 리소스 가져오기를 참조하세요.

  • 정책 컨트롤러를 사용하여 규제 준수 및 Kubernetes 표준을 시행하는 제약조건을 적용합니다.

  • 구성 동기화를 구성한 후 다음 섹션에서 구성 컨트롤러 인스턴스를 정보 소스에 저장된 구성(정책 컨트롤러 제약조건 및 구성 커넥터 리소스 포함)에 동기화합니다.

구성 컨트롤러를 사용하여 이러한 태스크를 완료하는 방법에 대한 안내식 예시를 보려면 빠른 시작: 구성 컨트롤러로 리소스 관리를 참조하세요.

구성 컨트롤러 인스턴스 구성

다음 섹션에서는 구성 컨트롤러 인스턴스의 구성요소 구성 방법을 설명합니다.

구성 커넥터 구성

구성 커넥터 설치에 대한 설정은 관리할 필요가 없습니다. 그러나 구성 컨트롤러에 Google Cloud 리소스 관리 권한을 부여해야 합니다.

  1. 서비스 계정 이메일에 대한 환경 변수를 설정합니다.

    export SA_EMAIL="$(kubectl get ConfigConnectorContext -n config-control \
    -o jsonpath='{.items[0].spec.googleServiceAccount}' 2> /dev/null)"

  2. 정책 바인딩을 만듭니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:${SA_EMAIL}" \
    --role "ROLE" \
    --project PROJECT_ID

    다음을 바꿉니다.

    이전 작업이 실패하면 컨트롤러가 준비되었는지 확인합니다.

    kubectl wait pod --all --all-namespaces --for=condition=Ready

이러한 권한을 부여한 후에는 Google Cloud 리소스 만들기를 시작할 수 있습니다.

정책 컨트롤러 구성

정책 컨트롤러가 측정항목을 전송하도록 허용하려면 IAM 정책을 추가하거나 업데이트해야 할 수 있습니다.

다음 명령어를 실행하여 정책 컨트롤러가 측정항목을 전송하도록 허용합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:PROJECT_ID.svc.id.goog[gatekeeper-system/gatekeeper-admin]" \
  --role=roles/monitoring.metricWriter

PROJECT_ID를 클러스터의 Google Cloud 프로젝트 ID로 바꿉니다.

구성 동기화 구성

구성 컨트롤러 인스턴스가 정보 소스에 저장된 구성으로부터 동기화되도록 하려면 구성 동기화를 구성해야 합니다.

구성 동기화를 사용하여 구성 커넥터 리소스를 만들려면 또한 리소스 관리를 위해 구성 동기화 권한을 부여했는지 확인해야 합니다.

구성 동기화를 구성하려면 RootSync 객체를 만들고 수정합니다.

  1. 외부 저장소(예: GitHub)로부터 동기화하려면 GKE에 Cloud NAT 설정을 참조하세요. 비공개 클러스터 노드에 아웃바운드 인터넷 액세스 권한이 없기 때문에 이를 수행해야 합니다.

  2. 다음 매니페스트 중 하나를 root-sync.yaml로 저장합니다. 구성에 대한 정보 소스에 해당하는 매니페스트 버전을 사용합니다.

    Git

    # root-sync.yaml
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
    noSSLVerify: ROOT_NO_SSL_VERIFY
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다.
    • 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입니다. 구성 동기화 버전 1.17.0부터는 revision 필드에 브랜치 이름을 지정할 수도 있습니다. 버전 1.17.0 이상에서 해시를 사용하는 경우 축약된 양식이 아닌 전체 해시 양식을 사용해야 합니다.
    • ROOT_BRANCH: 동기화할 저장소의 브랜치를 추가합니다. 이 필드는 선택사항이며 기본값은 master입니다. 구성 동기화 버전 1.17.0부터는 간단히 revision 필드를 사용하여 브랜치 이름을 지정하는 것이 좋습니다. revision 필드와 branch 필드가 모두 지정된 경우 revision이 branch보다 우선 적용됩니다.
    • ROOT_DIRECTORY: 동기화하려는 구성이 포함된 루트 디렉터리에 Git 저장소의 경로를 추가합니다. 이 필드는 선택사항이며 기본값은 저장소의 루트 디렉터리(/)입니다.

    • ROOT_AUTH_TYPE: 다음 인증 유형 중 하나를 추가합니다.

      • none: 인증 사용 안함
      • ssh: SSH 키 쌍 사용
      • cookiefile: cookiefile 사용
      • token: 토큰 사용
      • gcpserviceaccount: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다.
      • gcenode: Google 서비스 계정을 사용하여 Cloud Source Repositories에 액세스합니다. GKE용 워크로드 아이덴티티 제휴가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.

      이러한 인증 유형에 대한 자세한 내용은 Git에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여를 참조하세요.

      필수 필드입니다.

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

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

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

    • ROOT_CA_CERT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 Git 제공업체가 이 인증 기관(CA)에서 발급한 인증서를 사용해야 합니다. 보안 비밀에는 cert라는 키 아래에 CA 인증서가 포함되어야 합니다. 이 필드는 선택사항입니다.

      CA 인증서의 보안 비밀 객체를 구성하는 방법에 대한 자세한 내용은 인증 기관 구성을 참조하세요.

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

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

    OCI

    # root-sync.yaml
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
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    다음을 바꿉니다.

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

      필수 필드입니다.

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

    • ROOT_CA_CERT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 OCI 제공업체가 이 인증 기관(CA)에서 발급한 인증서를 사용해야 합니다. 보안 비밀에는 cert라는 키 아래에 CA 인증서가 포함되어야 합니다. 이 필드는 선택사항입니다.

    CA 인증서의 보안 비밀 객체를 구성하는 방법에 대한 자세한 내용은 인증 기관 구성을 참조하세요.

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

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

    Helm

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: helm
  sourceFormat: ROOT_FORMAT
  helm:
    repo: ROOT_HELM_REPOSITORY
    chart: HELM_CHART_NAME
    version: HELM_CHART_VERSION
    releaseName: HELM_RELEASE_NAME
    namespace: HELM_RELEASE_NAMESPACE
    values:
      foo:
        bar: VALUE_1
      baz:
      - qux: VALUE_2
        xyz: VALUE_3
    includeCRDs: HELM_INCLUDE_CRDS
    auth: ROOT_AUTH_TYPE
      gcpServiceAccountEmail: ROOT_EMAIL
      secretRef:
        name: ROOT_SECRET_NAME
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    다음을 바꿉니다.

    • ROOT_SYNC_NAME: RootSync 객체의 이름을 추가합니다.
    • ROOT_FORMAT: unstructured를 추가하여 구조화되지 않은 저장소를 사용하거나 hierarchy를 추가하여 계층 구조의 저장소를 사용합니다. 이러한 값은 대소문자를 구분합니다. 이 필드는 선택사항이며 기본값은 hierarchy입니다. 이 형식을 사용하면 가장 편리한 방식으로 구성을 조직화할 수 있기 때문에 unstructured를 추가하는 것이 좋습니다.
    • ROOT_HELM_REPOSITORY: 루트 저장소로 사용할 Helm 저장소의 URL입니다. HTTPS 또는 SSH 프로토콜을 사용하여 URL을 입력할 수 있습니다. 예를 들어 https://github.com/GoogleCloudPlatform/anthos-config-management-samples는 HTTPS 프로토콜을 사용합니다. 필수 필드입니다.
    • HELM_CHART_NAME: Helm 차트의 이름을 추가합니다. 필수 필드입니다.
    • HELM_CHART_VERSION: 차트의 버전입니다. 이 필드는 선택사항입니다. 값을 지정하지 않으면 최신 버전이 사용됩니다.
    • HELM_RELEASE_NAME: Helm 출시 버전의 이름입니다. 이 필드는 선택사항입니다.
    • HELM_RELEASE_NAMESPACE: 출시 버전의 대상 네임스페이스입니다. 템플릿에 namespace: {{ .Release.Namespace }}이 포함된 리소스의 네임스페이스만 설정합니다. 이 필드는 선택사항입니다. 값을 지정하지 않으면 기본 네임스페이스 config-management-system이 사용됩니다.
    • HELM_INCLUDE_CRDS: Helm 템플릿에서 CustomResourceDefinition도 생성하도록 하려면 true로 설정합니다. 이 필드는 선택사항입니다. 값을 지정하지 않을 경우 기본값은 false이며 CRD가 생성되지 않습니다.
    • VALUE: 차트에 포함되는 기본값 대신 사용할 값입니다. 이 필드의 형식을 Helm 차트의 values.yaml 파일과 동일하게 지정합니다. 이 필드는 선택사항입니다.

    • ROOT_AUTH_TYPE: 다음 인증 유형 중 하나를 추가합니다.

      • none: 인증 사용 안함
      • token: 사용자 이름과 비밀번호를 사용하여 비공개 Helm 저장소에 액세스합니다.
      • gcenode: Compute Engine 기본 서비스 계정을 사용하여 Artifact Registry의 이미지에 액세스합니다. GKE용 워크로드 아이덴티티 제휴가 클러스터에 사용 설정되지 않은 경우에만 이 옵션을 선택합니다.
      • gcpserviceaccount: Google 서비스 계정을 사용하여 이미지에 액세스합니다.

      필수 필드입니다.

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

    • ROOT_SECRET_NAME: token이 ROOT_AUTH_TYPE이면 보안 비밀 이름을 추가합니다. 이 필드는 선택사항입니다.

    • ROOT_CA_CERT_SECRET_NAME: 보안 비밀의 이름을 추가합니다. 이 필드를 설정하면 Helm 제공업체가 이 인증 기관(CA)에서 발급한 인증서를 사용해야 합니다. 보안 비밀에는 cert라는 키 아래에 CA 인증서가 포함되어야 합니다. 이 필드는 선택사항입니다.

    CA 인증서의 보안 비밀 객체를 구성하는 방법에 대한 자세한 내용은 인증 기관 구성을 참조하세요.

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

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

  3. 구성 동기화 구성을 만들려면 매니페스트를 적용하여 RootSync 객체를 만듭니다.

    kubectl apply -f root-sync.yaml

  4. 변경사항이 적용되었는지 확인하려면 RootSync 객체를 확인합니다.

    kubectl describe rootsync ROOT_SYNC_NAME -n config-management-system

구성 컨트롤러 업그레이드

구성 컨트롤러는 Google에서 자동으로 업그레이드하는 관리형 서비스입니다. 새 기능과 구성 컨트롤러에서 사용하는 구성 동기화, 정책 컨트롤러, 구성 커넥터 버전에 대한 자세한 내용은 구성 커넥터 출시 노트를 참조하세요.

구성 컨트롤러 인스턴스 삭제

구성 컨트롤러 인스턴스 사용을 중지하려면 구성 컨트롤러 클러스터 자체를 삭제하기 전에 생성된 모든 구성 커넥터 리소스를 삭제합니다.

프로비저닝된 리소스를 먼저 삭제하지 않고 구성 컨트롤러 인스턴스를 삭제하면 리소스가 폐기된 상태로 유지됩니다. 리소스는 여전히 Google Cloud에 있어 요금이 청구되지만 선언적 구성에서 관리되지 않습니다.

모든 리소스가 삭제된 후 구성 컨트롤러 클러스터를 삭제합니다.

gcloud anthos config controller delete \
    --location=LOCATION CONFIG_CONTROLLER_NAME

프로덕션 고려사항

프로덕션으로 이동할 때는 먼저 구성 컨트롤러의 고가용성 고려사항을 검토해야 합니다.

다음 단계