忽略未指定的字段

本页面介绍了 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，那么您会发现预设回复中显示了另一个名为 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. 确保在 ConfigConnector CR 或 ConfigConnectorContext CR 中将集群级或命名空间级的 stateIntoSpec 替换值设为 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. 将 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 以获取 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].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 资源的状态没有变化。

Kubernetes 资源规范中的 Config Connector 填充的未指定字段是 GET 请求的结果。这意味着在未来的协调中，Config Connector 可能会向底层 Google Cloud API 发送 PUT/PATCH 请求，并从 GET 请求中获知这些未指定的字段值。这通常不是问题，但某些 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
  • 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