Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

구성 커넥터 컨트롤러 유형

구성 커넥터는 계층화된 아키텍처를 사용하여 Google Cloud 환경의 리소스를 Kubernetes 사양과 조정합니다. 최상위 상위 컨트롤러는 각 리소스의 조정을 4가지 기본 컨트롤러 구현 중 하나로 라우팅합니다.

각 컨트롤러 유형, 기술적 차이점, 네임스페이스 전체 라우팅을 제어하는 방법을 이해하면 성능을 최적화하고 구성 문제를 해결하는 데 도움이 됩니다.

기본 컨트롤러 유형

구성 커넥터는 다음 컨트롤러 유형을 사용합니다.

직접 컨트롤러: 이 컨트롤러는 표준 Kubernetes controller-runtime 라이브러리를 사용하고 공식 Google Cloud Go SDK를 사용하여 Google Cloud API와 직접 통신합니다. 가능하면 직접 컨트롤러를 사용하는 것이 좋습니다. 일부 리소스는 직접 컨트롤러를 지원하지 않습니다. 새 리소스는 기본적으로 직접 컨트롤러를 사용합니다. 기존 리소스는 정기적으로 이전됩니다. 자세한 내용은 출시 노트를 참조하세요.
Terraform 기반 컨트롤러 (TF): 이 컨트롤러는 Terraform Google 프로바이더의 '래퍼' 역할을 합니다. 컨트롤러는 Kubernetes 리소스 모델 (KRM) 사양을 Terraform 호환 상태로 변환하고 plan 및 apply Terraform 작업을 구현합니다.
DCL 기반 컨트롤러: 이 컨트롤러 유형은 Google Cloud 선언적 클라이언트 라이브러리 (DCL)의 '래퍼' 역할을 합니다.
IAM 관련 컨트롤러: IAMPolicy, IAMPartialPolicy, IAMPolicyMember, IAMAuditConfig를 비롯한 ID 및 액세스 관리 (IAM) 리소스를 관리하도록 특별히 설계된 특수 컨트롤러입니다. 일부 IAM 리소스는 선택적으로 직접 컨트롤러를 지원합니다.

직접 컨트롤러의 이점

일부 리소스 유형은 여러 컨트롤러 유형을 지원합니다. 리소스가 직접 컨트롤러를 지원하는 경우 다음과 같은 이유로 다른 컨트롤러 유형 대신 직접 컨트롤러를 사용하는 것이 좋습니다.

리소스 소비 감소: 직접 컨트롤러에는 Terraform 기반 또는 DCL 기반 상태의 실행 및 변환과 관련된 CPU 및 메모리 오버헤드가 없습니다.
조정 지연 시간 개선: 직접 컨트롤러는 엔드포인트에 대해 직접 작업을 실행하여 리소스 상태의 일관성에 도달하는 데 필요한 평균 시간을 줄일 수 있습니다. Google Cloud
세분화된 상태 및 구조화된 차이점: 직접 컨트롤러는 cnrm-controller-manager 로그에서 구조화된 차이점 보고를 제공합니다. 이러한 로그에는 조정 루프와 같은 오류를 시작한 정확한 필드 변경사항이 포함되어 있어 문제 해결을 더 쉽게 할 수 있습니다.
기본 관찰된 상태: 직접 컨트롤러는 리소스 상태에서 status.observedState를 채워 API에서 직접 반환된 리소스 필드의 투명한 서버 측 뷰를 제공합니다. Google Cloud
수명 주기 처리 개선: 직접 컨트롤러에는 정상적인 고아 삭제와 같은 추가 기능이 포함되어 있습니다.

상위 라우팅 컨트롤러

리소스 유형과 관계없이 구성 커넥터는 중앙 상위 컨트롤러 내에서 모든 조정 요청을 가로챕니다. 상위 컨트롤러는 다음 우선순위 규칙을 사용하여 활성 동기화를 처리하는 하위 논리를 평가하는 라우터 역할을 합니다.

네임스페이스 재정의: 상위 컨트롤러는 먼저 대상 리소스의 네임스페이스에서 명시적 컨트롤러 재정의가 있는지 ConfigConnectorContext 리소스 구성을 확인합니다.
정적 기본값: 로컬 재정의가 지정되지 않은 경우 상위 컨트롤러는 구성 커넥터 정적 매핑 구성에 정의된 빌드 시간 조정자를 기본값으로 사용합니다.

리소스의 컨트롤러 식별

활성 코드 매핑을 사용하거나 Google Kubernetes Engine (GKE)에서 CustomResourceDefinition (CRD) 구조를 검사하여 특정 Google Cloud 리소스에 구성되거나 활성화된 컨트롤러 유형을 확인할 수 있습니다.

리소스의 정적 구성을 조회하려면 GitHub의 pkg/controller/resourceconfig/static_config.go에서 리소스를 검사하고 다음 예와 같이 리소스의 구성 블록을 찾습니다.

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}

DefaultController: 네임스페이스 수준 컨텍스트 재정의 규칙이 지정되지 않은 경우 사용되는 기본 조정자를 나타냅니다.
SupportedControllers: 이 리소스에 구현되고 사용 가능한 모든 조정자를 나열합니다. 재정의는 여기에 나열된 조정자로 전환됩니다.

CRD 라벨을 검사하려면 kubectl get crd 명령어를 사용합니다.

kubectl get crd RESOURCE_NAME -o jsonpath='{.metadata.labels}'

RESOURCE_NAME을 구성 커넥터 CRD의 정확한 이름(예: bigquerydatasets.bigquery.cnrm.cloud.google.com)으로 바꿉니다.

결과에서 다음 정보를 확인합니다.

cnrm.cloud.google.com/tf2crd: "true": Terraform 기반 (TF) 컨트롤러가 리소스를 관리합니다.
cnrm.cloud.google.com/dcl2crd: "true": DCL 기반 컨트롤러가 리소스를 관리합니다.
이러한 라벨이 없음: 직접 컨트롤러가 리소스를 관리합니다.

기본 컨트롤러 재정의

구성 커넥터에서 컨트롤러 유형을 재정의하는 기본 방법에는 두 가지가 있습니다. 이러한 방법의 차이점은 주로 운영 범위, 유지보수 오버헤드, 조정 중에 적용되는 우선순위와 관련이 있습니다.

다음 표에는 두 접근 방식의 차이점이 요약되어 있습니다.

기능	리소스 주석	ConfigConnectorContext 재정의
범위	단일 리소스 인스턴스	네임스페이스의 모든 리소스 종류
우선 적용	최고 (ConfigConnectorContext 재정의)	중간 (정적 기본값 재정의)
권장?	아니요	예
적합한 사용 사례	일회성 테스트	팀 또는 프로젝트 전체 출시

특정 리소스의 컨트롤러 재정의

리소스 메타데이터에 alpha.cnrm.cloud.google.com/reconciler 주석을 추가하여 특정 리소스 인스턴스가 특정 조정자로 실행되도록 강제할 수 있습니다. 이 접근 방식은 이전 섹션에 지정된 이유로 권장되지 않지만 단일 리소스 인스턴스의 구성을 테스트하거나 기존 구성을 유지보수하는 데 필요할 수 있습니다.

apiVersion: bigquery.cnrm.cloud.google.com/v1beta1
kind: BigQueryDataset
metadata:
  name: my-bq-ds
  namespace: NAMESPACE_NAME
  annotations:
    alpha.cnrm.cloud.google.com/reconciler: direct
spec:
  ...

주석에 지원되는 값은 direct, tf 또는 dcl입니다.

네임스페이스의 컨트롤러 재정의

ConfigConnectorContext 커스텀 리소스를 사용하여 네임스페이스 전체 재정의를 구성하려면 다음 단계를 완료하세요.

리소스 정의에서 이름과 그룹을 검색합니다. 예를 들어 BigQueryDataset 리소스의 경우 리소스 종류는 BigQueryDataset이고 그룹은 bigquery.cnrm.cloud.google.com입니다.
관리형 리소스가 포함된 네임스페이스 내에서 ConfigConnectorContext 객체를 수정합니다.
```
kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME
```
NAMESPACE_NAME을 대상 네임스페이스로 바꿉니다.

대상 재정의를 추가합니다. 예를 들어 이 네임스페이스의 모든 BigQueryDataset 인스턴스가 직접 컨트롤러로 실행되도록 재정의하려면 구성을 다음과 같이 정의합니다.

apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnectorContext
metadata:
  name: configconnectorcontext.core.cnrm.cloud.google.com
  namespace: NAMESPACE_NAME
spec:
  googleServiceAccount: "kcc-sa@my-project.iam.gserviceaccount.com"
  experiments:
    controllerOverrides:
      BigQueryDataset.bigquery.cnrm.cloud.google.com: direct

리소스를 저장하고 적용합니다. 상위 컨트롤러는 이 네임스페이스의 모든 일치하는 리소스에 새 직접 조정자 라우팅 규칙을 자동으로 동적으로 적용합니다.

네임스페이스 재정의 제약조건 및 사용 사례

명시적 지원 요구사항: 재정의가 성공하려면 대상 컨트롤러 유형이 리소스 종류에 구현되어야 합니다. 컨트롤러 유형이 지원되는지 확인하려면 리소스의 컨트롤러 식별을 참조하세요. 재정의에 지정한 컨트롤러 유형이 지원되지 않으면 상위 컨트롤러는 재정의를 무시하고 기본 조정자가 리소스 처리를 계속합니다.
네임스페이스 한도: ConfigConnectorContext의 재정의는 해당 특정 네임스페이스 내에 있는 해당 리소스 유형의 모든 인스턴스에 집합적으로 적용됩니다. 네임스페이스 범위 재정의로 개별 리소스 인스턴스를 타겟팅할 수 없습니다.
액세스 제어: ConfigConnectorContext 객체를 업데이트하려면 일반적으로 표준 리소스 수정에 비해 더 높은 수준의 플랫폼팀 권한이 필요합니다.
재정의 상태 보고: ConfigConnectorContext 재정의에 잘못되었거나 지원되지 않는 컨트롤러 유형이 지정된 경우 상위 컨트롤러는 컨텍스트를 비정상으로 표시합니다. kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml을 실행하고 .status.healthy 및 .status.errors 필드를 확인하여 이를 확인할 수 있습니다.
사용 시기: 컨트롤러를 재정의하는 데 권장되는 접근 방식입니다. 전체 네임스페이스를 최신 컨트롤러(예: 직접)로 선택하거나 프로젝트 전반에 아키텍처 일관성을 적용하는 데 사용합니다.