미지정 필드 무시

이 문서에서는 cnrm.cloud.google.com/state-into-spec 주석을 사용하여 기본 사양 필드를 채우는 동작을 변경하는 방법과, 이러한 동작을 변경해야 하는 때에 대해 설명합니다.

외부 필드 관리에 설명된 대로 Config Connector는 Google Cloud에서 리소스를 생성할 때 사양에서 지정되지 않은 채로 남겨진 필드는 값을 읽을 수 없는 경우를 제외하면 API의 값을 사용합니다(예를 들어 GET HTTP 요청은 사용하여 가져올 수 없는 값인 경우).

즉, 기본적으로 원래 YAML에 지정되지 않은 필드는 항상 Kubernetes 리소스 사양에 표시됩니다. 즉, kubectl get <resource kind> <resource name> -oyaml를 수행했을 때 리소스 사양의 많은 필드가 적용 YAML에 존재하지 않습니다.

예를 들어 CRD 스키마를 사용하여 사양에서 foo 및 bar라는 필드 두 개를 지정할 수 있고, 적용된 YAML 파일에는 foo만 지정되어 있다고 가정해 봅시다.

spec:
  foo: "foo"

YAML이 성공적으로 적용되고 리소스가 UpToDate이면 Kubernetes 리소스에 bar라는 다른 필드가 표시됩니다.

spec:
  foo: "foo"
  bar: "bar"

Config Connector와 Google Cloud API 간의 상호작용의 복잡성으로 인해, 사용자는 이 기본 동작을 변경하여 미지정 필드로 리소스 사양을 채우지 않고 건너뛰고 싶을 수 있습니다.

지정되지 않은 필드를 사양으로 채우지 않고 건너뛰기

YAML 파일을 만들 때 cnrm.cloud.google.com/state-into-spec 주석 값을 absent로 지정할 수 있습니다. 이 때 지정되지 않은 필드를 Kubernetes 리소스 사양에 채우는 단계를 건너뜁니다.

metadata:
  annotations:
    cnrm.cloud.google.com/state-into-spec: absent

이 주석이 지정되지 않으면 기본값은 merge입니다. 즉, 구성 커넥터에서 지정되지 않은 모든 필드를 사양에 채웁니다. 이 주석을 변경할 수 없습니다. 즉, 기존 구성 커넥터 리소스의 주석 값을 업데이트할 수 없습니다.

리소스를 이미 만들었지만 다른 채우기 동작을 위해 이 주석 값을 변경하려면 다음 단계를 수행해야 합니다.

다음 단계에서 삭제해도 기본 Google Cloud 리소스가 삭제되지 않게 하려면 cnrm.cloud.google.com/deletion-policy: abandon 주석을 수정하여 기존 Kubernetes 리소스에 추가합니다.
Kubernetes 클러스터에서 리소스를 삭제합니다.
cnrm.cloud.google.com/state-into-spec: absent 주석을 리소스 YAML에 추가합니다.
(선택사항) YAML에서 cnrm.cloud.google.com/deletion-policy: abandon을 삭제합니다.
업데이트된 YAML을 적용합니다.

이 주석으로 인한 차이점을 더 자세히 설명하기 위해 다음과 같은 스키마의 사양이 있다고 가정합시다.

foo1: string
foo2: string
bars:
- bar:
    br1: string
    br2: string
barz:
  bz1: string
  bz2: string

또한 YAML에서 사양을 다음과 같이 지정했다고 가정해 보겠습니다.

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

기본적으로 생성된 Kubernetes 리소스에 채워진 사양은 다음과 같습니다.

spec:
  foo1: "foo1"
  foo2: "foo2"
  bars:
  - br1: "1_br1"
    br2: "1_br2"
  - br1: "2_br1"
    br2: "2_br2"
  barz:
    bz1: "bz1"
    bz2: "bz2"

cnrm.cloud.google.com/state-into-spec: absent를 설정하면 생성된 Kubernetes 리소스의 최종 사양은 다음과 같습니다.

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

`cnrm.cloud.google.com/state-into-spec: absent` 사용 시점

cnrm.cloud.google.com/state-into-spec: absent를 설정하고 싶을 만한 몇 가지 일반적인 시나리오가 있습니다.

외부에서 목록의 지정되지 않은 필드 관리

구성 커넥터는 리소스 사양의 모든 목록 필드를 원자 필드로 취급합니다. 따라서 기본적으로 구성 커넥터 외부에서 목록의 하위 필드에 적용된 변경사항을 구성 커넥터에서 되돌립니다. 하지만 이 주석을 사용하여 구성 커넥터에서 목록의 하위 필드를 관리하지 않도록 할 수 있습니다. 자세한 내용은 리소스 사양의 목록 필드 동작을 참조하세요.

구성 관리 도구와 Config Connector 간의 충돌 해결

구성 동기화 또는 Argo CD와 같은 구성 관리 도구를 사용하는 경우 구성 관리 도구와 Config Connector 사이에서 충돌이 발생할 수 있습니다. 한 가지 예시로는 문제 해결 가이드에 설명된 KNV2005 오류가 있습니다. 이런 유형의 오류가 발생하는 근본 원인은 다음과 같습니다.

Config Connector는 사양의 목록에 지정되지 않은 값을 채우고 기본값을 사용합니다. 예를 들어 spec.bars[0].br2가 이에 해당합니다.
구성 관리 도구와 구성 커넥터 모두에서 목록 필드를 원자적으로 취급하므로 추가된 spec.bars[0].br2는 구성 관리 도구에서 드리프트로 처리되며 drift을 수정하기 위해 삭제됩니다.

이러한 문제를 해결하려면 구성 커넥터에서 지정되지 않은 필드 spec.bars[0].br2를 사양에 추가하지 않도록 cnrm.cloud.google.com/state-into-spec: absent를 설정하면 됩니다.

GET/PUT 균형 문제 해결

GET/PUT 균형은 REST API의 설계 원칙을 의미합니다. 특히, GET 응답이 PUT 요청으로 같은 URL에 전송될 때 예상 결과는 기본 REST 리소스 상태가 변경되지 않은 HTTP 200 OK 응답입니다.

구성 커넥터에서 리소스 사양에 채운 지정되지 않은 필드는 GET 요청 결과입니다. 즉, 향후 조정에서 구성 커넥터는 GET 요청에서 학습한 지정되지 않은 필드 값을 사용하여 PUT/PATCH 요청을 Google Cloud API에 전송할 수 있습니다. 일반적으로는 이는 문제가 되지 않지만 이러한 지정되지 않은 필드 값으로 인해 일부 Google Cloud API에서 PUT/PATCH 요청을 거부할 수 있습니다. 같은 예시에서 API 구현이 GET/PUT 대칭 원칙을 위반하면 값이 'bz2'인 채워진 spec.barz.bz2는 HTTP 400 클라이언트 오류 또는 기타 예상치 못한 응답을 초래할 수 있습니다.

이 카테고리의 문제를 방지하려면 cnrm.cloud.google.com/state-into-spec: absent 설정을 실험하고 조정 중에 오류가 사라지는지 확인하면 됩니다.

`cnrm.cloud.google.com/state-into-spec: absent`를 피해야 하는 경우

지정되지 않은 필드의 채워진 값에 솔루션이 의존하는 경우 cnrm.cloud.google.com/state-into-spec: absent을 설정하지 말아야 합니다. 예를 들어 ComputeAddress 리소스를 사용 중이고 원본 YAML의 지정되지 않은 필드일 수 있는 서버 생성 spec.address 값이 필요한 경우 이 주석을 사용해서는 안 됩니다. Kubernetes 리소스 사양에 spec.address 값 채우기를 건너뛰기 때문입니다.

관찰된 상태

cnrm.cloud.google.com/state-into-spec: absent를 설정해야 하지만 지정되지 않은 필드의 채워진 값에 따라 솔루션이 달라지는 경우 이러한 필드가 CRD 스키마의 status.observedState에 있는지 확인합니다. status.observedState 아래에 표시되면 cnrm.cloud.google.com/state-into-spec: absent를 설정할 수 있으며 조정 성공 후에도 지정되지 않은 필드의 값에 계속 액세스할 수 있습니다.

status.observedState 필드에는 구성 커넥터가 마지막으로 성공한 조정에서 관찰된 선택된 관찰된 리소스의 라이브 상태가 포함됩니다. 관찰된 필드는 일반적인 사용 사례의 종속 항목인 경우 선택되며 계산된 spec 필드입니다. CRD 스키마에서 관찰된 필드를 찾을 수 있습니다.

원하는 관찰된 필드를 찾을 수 없으면 기존 문제를 확인하거나 공개 Issue Tracker에서 새 문제를 엽니다.