忽略未指定的字段
本页面介绍了 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,您会注意到另一个名为 bar
的字段会显示在 CR 中:
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
字段的填充行为,并遵循以下逻辑来确定注解的值:
- 直接使用
cnrm.cloud.google.com/state-into-spec
注解的值(如果已指定且有效)。 - 如果未指定注解,请使用 ConfigConnectorContext CR 中
stateIntoSpec
字段的相应值。 - 如果 ConfigConnectorContext CR 不存在或
stateIntoSpec
字段未指定,请使用 ConfigConnector CR 中stateIntoSpec
字段的相应值。 - 如果 ConfigConnector CR 不存在或未指定
stateIntoSpec
字段,请使用基于spec
字段填充行为中所述的 CRD 的默认行为。
请注意,无论 ConfigConnector CR 或 ConfigConnectorContext CR 中的 cnrm.cloud.google.com/state-into-spec
注解或 stateIntoSpec
字段为何,在版本 1.114.0 及更高版本中添加的唯一填充行为 CRD 都是 Absent
。
如果您已创建资源,但想要将 spec
字段的填充行为更改为 Absent
,您应执行以下操作:
确保在 ConfigConnector CR 或 ConfigConnectorContext CR 中,将集群级或命名空间级
stateIntoSpec
替换值设为Absent
。放弃并获取资源。 确保用于获取数据的 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 资源的注解值。
如果您已创建资源,但想要更改此注解的值以适应不同的填充行为,则必须按照以下步骤操作:
修改现有 Kubernetes 资源并向其添加注解
cnrm.cloud.google.com/deletion-policy: abandon
,以确保下一步删除操作不会删除底层 Google Cloud 资源。从 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
以获取 spec
字段的 Absent
填充行为。以下是从 Absent
填充行为中受益的最常见场景。
在外部管理列表中的未指定字段
Config Connector 将 Kubernetes 资源规范中的所有列表字段视为原子字段。因此,默认情况下,Config Connector 会还原您在 Config Connector 之外对列表中的子字段所做的更改。但是,您可以使用此注解让 Config Connector 取消管理列表中的子字段。如需了解详情,请参阅资源规范中列表字段的行为。
解决配置管理工具和 Config Connector 之间的冲突问题
如果您使用的是 Config Sync 或 Argo CD 等配置管理工具,您可能会发现配置管理工具和 Config Connector 之间存在冲突。例如,问题排查指南中阐述的 KNV2005 错误。这类问题的根本原因在于:
- Config Connector 将在规范的列表中填充并默认未指定值,
spec.bars[0].br2
就是一个示例。 - 配置管理工具和 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
的 CRD
以下是支持 Merge
填充行为的所有 CRD:
- 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
- LoggingLogMetric
- 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