忽略未指定的欄位

本頁說明 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。

合併

Merge 是 1.114.0 以上版本新增的 CRD 中不支援的行為。除非無法讀取，否則 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」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 或更新 Config Connector 安裝作業時，您可以在 ConfigConnector CR 或 ConfigConnectorContext CR 中，將叢集層級或命名空間層級 stateIntoSpec 覆寫值設為 Absent。

spec:
  stateIntoSpec: Absent

如此一來，如果您未在新資源 YAML 中指定 cnrm.cloud.google.com/state-into-spec 註解，Absent 就會成為預設 spec 欄位，為叢集或命名空間中建立的任何新資源填入資料。這表示 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. 編輯現有 Kubernetes 資源並新增註解 cnrm.cloud.google.com/deletion-policy: abandon，確保在下一個步驟中刪除時不會刪除基礎 Google Cloud 資源。

  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 的時機

在大多數情況下，您會想設定 cnrm.cloud.google.com/state-into-spec: absent，以便讓 Absent 為 spec 欄位填入資料。以下是 Absent 填入行為最常見的應用情境。

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

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

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

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

  1. 設定連接器會在規格清單中填入預設值和未指定的值，spec.bars[0].br2 就是一例。
  2. 設定管理工具和 Config Connector 都會將清單欄位視為原子，因此新增的 spec.bars[0].br2 會被設定管理工具視為偏移，並且會移除以修正 drift。

如要解決這些問題，您可以設定 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 資源的狀態不會改變。

Config Connector 在 Kubernetes 資源規格中填入的未指定欄位，是 GET 要求的結果。也就是說，在日後的比對作業中，設定連接器可能會將從 GET 要求擷取到的這些未指定欄位值，傳送至底層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 欄位包含 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 名稱 版本
LoggingLogMetric 1.118.1