미지정 필드 무시

이 페이지에서는 spec 필드의 기본 채우기 동작 및 기본 동작을 Merge에서 권장되는 동작인 Absent로 변경하는 방법을 설명합니다. 버전 1.114.0 이상에 추가된 CRD를 사용하는 경우 이러한 CRD가 Absent 동작만 사용하므로 이 페이지가 적용되지 않을 수 있습니다. Merge를 지원하는 CRD 목록은 이 페이지의 Merge를 지원하는 CRD 섹션을 참조하세요

spec 필드 채우기 동작

구성 커넥터가 리소스를 만들 때 Kubernetes 리소스 사양에 지정되지 않은 필드에는 Absent 및 Merge라는 두 가지 기본 채우기 동작이 있을 수 있습니다.

없음

Absent는 권장되는 동작입니다. 구성 커넥터는 지정되지 않은 필드를 사양에 채우지 않습니다.

버전 1.114.0 이상에 추가된 CRD의 경우 기본 채우기 동작은 Absent입니다. 이러한 CRD가 지원하는 유일한 채우기 동작이기도 합니다. 이러한 리소스 CR의 cnrm.cloud.google.com/state-into-spec 주석 값은 absent입니다.

병합

Merge는 버전 1.114.0 이상에 추가된 CRD에서 지원되지 않는 동작입니다. 조정이 성공한 후 spec 필드는 읽을 수 없는 경우가 아닌 이상 API에서 값을 가져옵니다. 자세한 내용은 외부에서 필드 관리에서 확인할 수 있습니다.

구성 커넥터 버전 1.113.0 이하에서 지원되는 CRD의 경우 기본 채우기 동작은 Merge입니다. Merge를 지원하는 CRD 목록은 이 페이지의 Merge를 지원하는 CRD 섹션을 참조하세요 이러한 리소스 CR의 cnrm.cloud.google.com/state-into-spec 주석의 기본값은 merge입니다. 또는 지정되지 않은 필드를 사양으로 채우지 않고 건너뛰기 안내에 따라 기본 동작을 Absent로 구성할 수 있습니다.

기본적으로 원본 YAML에서 지정되지 않은 리소스 CR은 항상 CR 사양에 표시됩니다. 즉, kubectl get <resource kind> <resource name> -oyaml을 실행할 때 사양의 많은 필드가 적용된 YAML에 없습니다.

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

spec:
  foo: "foo"

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

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

구성 커넥터와 Google Cloud API 간의 상호작용의 복잡성으로 인해, 사용자는 이 기본 동작을 변경하고 미지정 필드로 Kubernetes 리소스 사양을 채우지 않고 건너뛰는 것이 좋습니다.

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

구성 커넥터 버전 1.113.0 이하에서 지원되는 CRD의 경우 다음 중 한 가지 방법으로 지정되지 않은 필드를 사양에 입력하는 과정을 건너뛸 수 있습니다.

  • 클러스터 수준 또는 네임스페이스 수준 stateIntoSpec 재정의를 Absent로 구성합니다.
  • cnrm.cloud.google.com/state-into-spec 주석의 값을 리소스에 대해 absent로 지정합니다.

클러스터 수준 또는 네임스페이스 수준 stateIntoSpec 재정의 구성

구성 커넥터를 설치하거나 구성 커넥터 설치를 업데이트할 때 클러스터 수준 또는 네임스페이스 수준 stateIntoSpec 재정의를 ConfigConnector CR 또는 ConfigConnectorContext CR에서 Absent로 구성합니다.

spec:
  stateIntoSpec: Absent

이렇게 하면 새 리소스에 cnrm.cloud.google.com/state-into-spec 주석을 지정하지 않을 때 Absent가 클러스터 또는 네임스페이스에서 생성된 모든 새 리소스의 기본 spec 필드 채우기 동작이 됩니다. 즉, 구성 커넥터가 이러한 리소스의 Kubernetes 리소스 사양에 지정되지 않은 필드를 채우는 과정을 건너뜁니다.

stateIntoSpec 필드에는 기본값이 없습니다. 구성 커넥터가 cnrm.cloud.google.com/state-into-spec 주석 값에 따라 spec 필드 채우기 동작을 결정하며 주석 값을 결정하기 위해 아래의 로직을 따릅니다.

  1. cnrm.cloud.google.com/state-into-spec 주석이 지정되고 유효한 경우 해당 값을 직접 사용합니다.
  2. 주석이 지정되지 않은 경우 ConfigConnectorContext CR에서 상응하는 stateIntoSpec 필드 값을 사용합니다.
  3. ConfigConnectorContext CR이 없거나 stateIntoSpec 필드가 지정되지 않은 경우 ConfigConnector CR의 stateIntoSpec 필드의 해당 값을 사용합니다.
  4. ConfigConnectorContext CR이 없거나 stateIntoSpec 필드가 지정되지 않은 경우 spec 필드 채우기 동작에 설명된 CRD에 따라 기본 동작을 사용합니다.

버전 1.114.0 이상에 추가된 유일한 채우기 동작 CRD는 cnrm.cloud.google.com/state-into-spec 주석이나 ConfigConnector CR 또는 ConfigConnectorContext CR의 stateIntoSpec 필드에 관계없이 Absent입니다.

리소스를 이미 만들었지만 spec 필드 채우기 동작을 Absent로 변경하려면 다음 단계를 수행합니다.

  1. 클러스터 수준 또는 네임스페이스 수준 stateIntoSpec 재정의가 ConfigConnector CR 또는 ConfigConnectorContext CR에서 Absent인지 확인합니다.

  2. 리소스를 폐기하고 확보합니다. 확보에 사용된 YAML 구성에 cnrm.cloud.google.com/state-into-spec 주석이 없는지 확인합니다.

리소스 수준 cnrm.cloud.google.com/state-into-spec 주석 지정

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

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

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

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

  1. 다음 단계에서 삭제해도 기본 Google Cloud 리소스가 삭제되지 않게 하려면 cnrm.cloud.google.com/deletion-policy: abandon 주석을 수정하여 기존 Kubernetes 리소스에 추가합니다.

  2. Kubernetes 클러스터에서 리소스를 삭제합니다.

  3. cnrm.cloud.google.com/state-into-spec: absent 주석을 리소스 YAML에 추가합니다.

  4. (선택사항) YAML에서 cnrm.cloud.google.com/deletion-policy: abandon을 삭제합니다.

  5. 업데이트된 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 사용 시점

대부분의 경우 spec 필드의 Absent 채우기 동작을 가져오도록 cnrm.cloud.google.com/state-into-spec: absent를 설정하는 것이 좋습니다. 다음은 Absent 채우기 동작의 이점을 활용하는 가장 일반적인 시나리오입니다.

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

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

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

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

  1. Config Connector는 사양의 목록에 지정되지 않은 값을 채우고 기본값을 사용합니다. 예를 들어 spec.bars[0].br2가 이에 해당합니다.
  2. 구성 관리 도구와 구성 커넥터 모두에서 목록 필드를 원자적으로 취급하므로 추가된 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 응답입니다.

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

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

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

Merge 지원 종류

다음은 Merge 채우기 동작을 지원하는 모든 구성 커넥터 종류입니다.

  • AccessContextManagerAccessLevel
  • AccessContextManagerAccessPolicy
  • AccessContextManagerServicePerimeter
  • AlloyDBBackup
  • AlloyDBCluster
  • AlloyDBInstance
  • AlloyDBUser
  • ApigeeEnvironment
  • ApigeeOrganization
  • ArtifactRegistryRepository
  • BigQueryDataset
  • BigQueryJob
  • BigQueryTable
  • BigtableAppProfile
  • BigtableGCPolicy
  • BigtableInstance
  • BigtableTable
  • BillingBudgetsBudget
  • BinaryAuthorizationAttestor
  • BinaryAuthorizationPolicy
  • CertificateManagerCertificate
  • CertificateManagerCertificateMap
  • CertificateManagerCertificateMapEntry
  • CertificateManagerDNSAuthorization
  • CloudBuildTrigger
  • CloudFunctionsFunction
  • CloudIdentityGroup
  • CloudIdentityMembership
  • CloudSchedulerJob
  • ComputeAddress
  • ComputeBackendBucket
  • ComputeBackendService
  • ComputeDisk
  • ComputeExternalVPNGateway
  • ComputeFirewall
  • ComputeFirewallPolicy
  • ComputeFirewallPolicyAssociation
  • ComputeFirewallPolicyRule
  • ComputeForwardingRule
  • ComputeHTTPHealthCheck
  • ComputeHTTPSHealthCheck
  • ComputeHealthCheck
  • ComputeImage
  • ComputeInstance
  • ComputeInstanceGroup
  • ComputeInstanceGroupManager
  • ComputeInstanceTemplate
  • ComputeInterconnectAttachment
  • ComputeNetwork
  • ComputeNetworkEndpointGroup
  • ComputeNetworkFirewallPolicy
  • ComputeNetworkPeering
  • ComputeNodeGroup
  • ComputeNodeTemplate
  • ComputePacketMirroring
  • ComputeProjectMetadata
  • ComputeRegionNetworkEndpointGroup
  • ComputeReservation
  • ComputeResourcePolicy
  • ComputeRoute
  • ComputeRouter
  • ComputeRouterInterface
  • ComputeRouterNAT
  • ComputeRouterPeer
  • ComputeSSLCertificate
  • ComputeSSLPolicy
  • ComputeSecurityPolicy
  • ComputeServiceAttachment
  • ComputeSharedVPCHostProject
  • ComputeSharedVPCServiceProject
  • ComputeSnapshot
  • ComputeSubnetwork
  • ComputeTargetGRPCProxy
  • ComputeTargetHTTPProxy
  • ComputeTargetHTTPSProxy
  • ComputeTargetInstance
  • ComputeTargetPool
  • ComputeTargetSSLProxy
  • ComputeTargetTCPProxy
  • ComputeTargetVPNGateway
  • ComputeURLMap
  • ComputeVPNGateway
  • ComputeVPNTunnel
  • ConfigControllerInstance
  • ContainerAnalysisNote
  • ContainerAttachedCluster
  • ContainerCluster
  • ContainerNodePool
  • DLPDeidentifyTemplate
  • DLPInspectTemplate
  • DLPJobTrigger
  • DLPStoredInfoType
  • DNSManagedZone
  • DNSPolicy
  • DNSRecordSet
  • DataFusionInstance
  • DataflowFlexTemplateJob
  • DataflowJob
  • DataprocAutoscalingPolicy
  • DataprocCluster
  • DataprocWorkflowTemplate
  • EdgeContainerCluster
  • EdgeContainerNodePool
  • EdgeContainerVpnConnection
  • EdgeNetworkNetwork
  • EdgeNetworkSubnet
  • EventarcTrigger
  • FilestoreBackup
  • FilestoreInstance
  • FirestoreIndex
  • 폴더
  • GKEHubFeature
  • GKEHubFeatureMembership
  • GKEHubMembership
  • IAMAccessBoundaryPolicy
  • IAMAuditConfig
  • IAMCustomRole
  • IAMPartialPolicy
  • IAMPolicy
  • IAMPolicyMember
  • IAMServiceAccount
  • IAMServiceAccountKey
  • IAMWorkforcePool
  • IAMWorkforcePoolProvider
  • IAMWorkloadIdentityPool
  • IAMWorkloadIdentityPoolProvider
  • IAPBrand
  • IAPIdentityAwareProxyClient
  • IdentityPlatformConfig
  • IdentityPlatformOAuthIDPConfig
  • IdentityPlatformTenant
  • IdentityPlatformTenantOAuthIDPConfig
  • KMSCryptoKey
  • KMSKeyRing
  • LoggingLogBucket
  • LoggingLogExclusion
  • LoggingLogSink
  • LoggingLogView
  • MemcacheInstance
  • MonitoringAlertPolicy
  • MonitoringDashboard
  • MonitoringGroup
  • MonitoringMetricDescriptor
  • MonitoringMonitoredProject
  • MonitoringNotificationChannel
  • MonitoringService
  • MonitoringServiceLevelObjective
  • MonitoringUptimeCheckConfig
  • NetworkConnectivityHub
  • NetworkConnectivitySpoke
  • NetworkSecurityAuthorizationPolicy
  • NetworkSecurityClientTLSPolicy
  • NetworkSecurityServerTLSPolicy
  • NetworkServicesEndpointPolicy
  • NetworkServicesGRPCRoute
  • NetworkServicesGateway
  • NetworkServicesHTTPRoute
  • NetworkServicesMesh
  • NetworkServicesTCPRoute
  • NetworkServicesTLSRoute
  • OSConfigGuestPolicy
  • OSConfigOSPolicyAssignment
  • PrivateCACAPool
  • PrivateCACertificate
  • PrivateCACertificateAuthority
  • PrivateCACertificateTemplate
  • 프로젝트
  • PubSubLiteReservation
  • PubSubSchema
  • PubSubSubscription
  • PubSubTopic
  • RecaptchaEnterpriseKey
  • RedisInstance
  • ResourceManagerLien
  • ResourceManagerPolicy
  • RunJob
  • RunService
  • SQLDatabase
  • SQLInstance
  • SQLSSLCert
  • SQLUser
  • SecretManagerSecret
  • SecretManagerSecretVersion
  • 서비스
  • ServiceDirectoryEndpoint
  • ServiceDirectoryNamespace
  • ServiceDirectoryService
  • ServiceIdentity
  • ServiceNetworkingConnection
  • SourceRepoRepository
  • SpannerDatabase
  • SpannerInstance
  • StorageBucket
  • StorageBucketAccessControl
  • StorageDefaultObjectAccessControl
  • StorageNotification
  • StorageTransferJob
  • VPCAccessConnector

다음 종류는 해당 버전부터 Merge 채우기 동작을 지원하지 않습니다.

종류 이름 버전
LoggingLogMetric 1.118.1