忽略未指定的欄位

本頁說明 spec 欄位的預設填入行為，以及如何將預設行為從 Merge 變更為建議行為 Absent。如果您使用 1.114.0 以上版本新增的 CRD，可能不適用本頁內容，因為這些 CRD 只會使用 Absent 行為。如需支援 Merge 的 CRD 清單，請參閱本頁的「支援 Merge 的 CRD」一節。

spec 欄位填入行為

Config Connector 建立資源時，Kubernetes 資源規格中未指定的欄位可能有兩種不同的預設填入行為：Absent 和 Merge。

缺席

Absent 是建議的行為。Config Connector 不會在規格中填入任何未指定的欄位。

如果是1.114.0 以上版本新增的 CRD，預設填入行為為 Absent。這也是這些 CRD 支援的唯一填入行為。在這些資源 CR 中，cnrm.cloud.google.com/state-into-spec 註解的值為 absent。

合併

在 1.114.0 以上版本中新增的 CRD 不支援 Merge 行為。成功對帳後，除非 spec 欄位無法讀取，否則會採用 API 中的值。詳情請參閱「從外部管理欄位」。

如果是 Config Connector 1.113.0 版及更早版本支援的 CRD，預設的填入行為是 Merge。如需支援 Merge 的 CRD 清單，請參閱本頁的「支援 Merge 的 CRD」一節。在這些資源 CR 中，cnrm.cloud.google.com/state-into-spec 註解的預設值為 merge。您也可以按照「略過將未指定的欄位填入規格」一文中的操作說明，將填入行為設定為 Absent。

根據預設，在這些資源 CR 中，原始 YAML 中未指定的欄位一律會顯示在 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"

由於 Config Connector 和Google Cloud API 之間的互動相當複雜，您可能想變更這項預設行為，並略過使用未指定欄位填入 Kubernetes 資源規格。

略過將未指定的欄位填入規格

對於 Config Connector 1.113.0 版及更早版本支援的 CRD，您可以透過下列任一方式，略過在規格中填入未指定的欄位：

  • 設定叢集層級或命名空間層級的 stateIntoSpec 覆寫，使其成為 Absent。
  • 將資源的 cnrm.cloud.google.com/state-into-spec 註解值指定為 absent。

設定叢集層級或命名空間層級的stateIntoSpec覆寫

安裝或更新 Config Connector 安裝項目時，您可以在 ConfigConnector CR 或 ConfigConnectorContext CR 中，將叢集層級或命名空間層級的 stateIntoSpec 覆寫設定為 Absent。

spec:
  stateIntoSpec: Absent

這樣一來，當您未在新資源 YAML 中指定 cnrm.cloud.google.com/state-into-spec 註解時，系統就會為叢集或命名空間中建立的任何新資源，填入預設的 spec 欄位。Absent也就是說，Config Connector 會略過將未指定的欄位填入這些資源的 Kubernetes 資源規格。

stateIntoSpec 欄位沒有預設值。Config Connector 會根據 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. 如果 ConfigConnector CR 不存在，或 stateIntoSpec 欄位未指定，請根據 spec 欄位填入行為中說明的 CRD，使用預設行為。

請注意，1.114.0 以上版本新增的唯一填入行為 CRD 會遵循 Absent，無論 ConfigConnector CR 或 ConfigConnectorContext CR 中的 cnrm.cloud.google.com/state-into-spec 註解或 stateIntoSpec 欄位為何。

如果您已建立資源，但想將 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，表示 Config Connector 會將所有未指定的欄位填入規格。這項註解不可變更，也就是說，您無法更新現有 Config Connector 資源的註解值。

如果您已建立資源，但想變更這個註解的值，以採用不同的填入行為，請按照下列步驟操作：

  1. 編輯並新增註解 cnrm.cloud.google.com/deletion-policy: abandon 至現有 Kubernetes 資源，確保下一步的刪除作業不會刪除基礎 Google Cloud 資源。

  2. 從 Kubernetes 叢集刪除資源。

  3. 在資源的 YAML 中加入 cnrm.cloud.google.com/state-into-spec: absent 註解。

  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

在大部分情況下，您會想設定 cnrm.cloud.google.com/state-into-spec: absent，以便取得 spec 欄位的 Absent 填入行為。以下是可從 Absent 填入行為獲益的常見情境。

從外部管理清單中未指定的欄位

Config Connector 會將 Kubernetes 資源規格中的所有清單欄位視為不可分割的欄位。因此，根據預設，您在 Config Connector 外部對清單中的子欄位所做的變更，都會由 Config Connector 還原。不過，您可以使用這項註解，讓 Config Connector 取消管理清單中的子欄位。詳情請參閱「資源規格中的清單欄位行為」。

解決設定管理工具與 Config Connector 之間的衝突

如果您使用 Config Sync 或 Argo CD 等設定管理工具，可能會發現設定管理工具與 Config Connector 之間有衝突。例如，疑難排解指南中說明的 KNV2005 錯誤。這類問題的根本原因如下：

  1. Config Connector 會在規格中填入清單中未指定的值，並設為預設值，例如 spec.bars[0].br2。
  2. 設定管理工具和 Config Connector 都會將清單欄位視為不可分割的項目，因此設定管理工具會將新增的  視為差異，並移除該項目來修正 。spec.bars[0].br2drift

如要解決這些問題，您可以設定 cnrm.cloud.google.com/state-into-spec: absent，讓 Config Connector 不會將未指定的欄位 spec.bars[0].br2 新增至規格。

解決 GET/PUT 對稱問題

GET/PUT 對稱是指 REST API 的設計原則。具體來說，這表示當 GET 回應以 PUT 要求的形式傳送至相同網址時，預期結果是 HTTP 200 OK 回應，且基礎 REST 資源的狀態不會變更。

Kubernetes 資源規格中由 Config Connector 填入的未指定欄位，是 GET 要求的結果。這表示在日後的對帳中，Config Connector 可能會向基礎Google Cloud API 傳送 PUT/PATCH 要求，並使用從 GET 要求中瞭解到的這些未指定欄位值。這通常不是問題，但部分 API 可能會因為這些未指定的欄位值而拒絕 PUT/PATCH 要求。Google Cloud 在同一個範例中，如果 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 欄位包含 Config Connector 在上次成功調解時，觀察到的資源所選欄位的即時狀態。如果觀察到的欄位是常見用途的依附元件，且為spec計算欄位，系統就會選取這些欄位。您可以在 CRD 結構定義中找到觀察到的欄位。

如果找不到想要的觀察欄位，請在公開問題追蹤器中查看現有問題或開啟新問題。

支援 Merge 的種類

以下是支援 Merge 填入行為的所有 Config Connector 種類：

  • AccessContextManagerAccessLevel
  • AccessContextManagerAccessPolicy
  • AccessContextManagerServicePerimeter
  • AlloyDBBackup
  • AlloyDBCluster
  • AlloyDBUser
  • ApigeeEnvironment
  • ApigeeOrganization
  • ArtifactRegistryRepository
  • BigQueryDataset
  • BigQueryJob
  • BigQueryTable
  • BigtableAppProfile
  • BigtableGCPolicy
  • BigtableInstance
  • BigtableTable
  • BillingBudgetsBudget
  • BinaryAuthorizationAttestor
  • BinaryAuthorizationPolicy
  • CertificateManagerCertificate
  • CertificateManagerCertificateMap
  • CertificateManagerCertificateMapEntry
  • CloudBuildTrigger
  • CloudFunctionsFunction
  • CloudIdentityGroup
  • CloudIdentityMembership
  • CloudSchedulerJob
  • ComputeAddress
  • ComputeBackendBucket
  • ComputeBackendService
  • ComputeDisk
  • ComputeExternalVPNGateway
  • ComputeFirewall
  • ComputeFirewallPolicy
  • ComputeFirewallPolicyAssociation
  • 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
  • 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
  • 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
  • SQLSSLCert
  • SQLUser
  • SecretManagerSecret
  • SecretManagerSecretVersion
  • 服務
  • ServiceDirectoryEndpoint
  • ServiceDirectoryNamespace
  • ServiceDirectoryService
  • ServiceIdentity
  • ServiceNetworkingConnection
  • SourceRepoRepository
  • SpannerDatabase
  • SpannerInstance
  • StorageBucket
  • StorageBucketAccessControl
  • StorageDefaultObjectAccessControl
  • StorageNotification
  • StorageTransferJob
  • VPCAccessConnector

從對應版本開始，下列種類不支援 Merge 填入行為：

Kind Name 版本
LoggingLogMetric 1.118.1