Ignorar campos não especificados

Nesta página, explicamos o comportamento padrão de preenchimento dos campos spec e como mudar o comportamento padrão de Merge para o recomendado Absent. Esta página pode não ser aplicável se você estiver usando um CRD adicionado na versão 1.114.0 e mais recente, porque esses CRDs usam apenas o comportamento Absent. Para uma lista de CRDs que oferecem suporte a Merge, consulte a seção CRDs com suporte a Merge desta página.

spec comportamentos de preenchimento de campos

Quando o Config Connector cria um recurso, os campos não especificados na especificação de recurso do Kubernetes podem ter dois comportamentos padrão de preenchimento diferentes: Absent e Merge.

Ausente

Absent é o comportamento recomendado. O Config Connector não vai preencher campos não especificados na especificação.

Para CRDs adicionados na versão 1.114.0 e mais recentes, o comportamento de preenchimento padrão é Absent. Esse também é o único comportamento de preenchimento compatível com esses CRDs. O valor da anotação cnrm.cloud.google.com/state-into-spec é absent nesses CRs de recurso.

Mesclar

Merge é um comportamento sem suporte em CRDs adicionados na versão 1.114.0 e mais recentes. Os campos spec assumem valores da API após uma conciliação bem-sucedida, a menos que não sejam legíveis. Confira mais detalhes em Gerenciar campos externamente.

Para CRDs compatíveis com o Config Connector versão 1.113.0 e anteriores, o comportamento padrão de preenchimento é Merge. Para conferir uma lista de CRDs que são compatíveis com Merge, consulte a seção CRDs com suporte a Merge nesta página. O valor padrão da anotação cnrm.cloud.google.com/state-into-spec é merge nesses CRs de recursos. Também é possível configurar o comportamento de preenchimento como Absent seguindo as instruções em Ignorar o preenchimento de campos não especificados na especificação.

Por padrão, nesses CRs de recursos, os campos que não foram especificados no YAML original sempre aparecem na especificação do CR. Isso significa que, quando você executa kubectl get <resource kind> <resource name> -oyaml, muitos campos na especificação não estão no YAML aplicado.

Por exemplo, suponha que o esquema CRD permita especificar dois campos chamados foo e bar na especificação, enquanto o arquivo YAML aplicado tenha apenas foo especificado:

spec:
  foo: "foo"

Você vai notar outro campo chamado bar no CR se o YAML for aplicado com sucesso e o recurso estiver UpToDate:

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

Devido à complexidade da interação entre o Config Connector e as APIsGoogle Cloud , talvez seja necessário mudar esse comportamento padrão e pular o preenchimento da especificação de recursos do Kubernetes com campos não especificados.

Ignorar o preenchimento de campos não especificados na especificação

É possível pular o preenchimento de campos não especificados na especificação para CRDs compatíveis com o Config Connector versão 1.113.0 e anteriores de uma das seguintes maneiras:

• Configure a substituição de stateIntoSpec no nível do cluster ou do namespace para ser Absent.
• Especifique o valor da anotação cnrm.cloud.google.com/state-into-spec como absent para o recurso.

Configure a substituição de stateIntoSpec no nível do cluster ou do namespace

Ao instalar ou atualizar o Config Connector, é possível configurar a substituição de stateIntoSpec no nível do cluster ou do namespace para ser Absent no CR do ConfigConnector ou no CR do ConfigConnectorContext.

spec:
  stateIntoSpec: Absent

Isso faz com que Absent seja o comportamento padrão de preenchimento de campos spec para qualquer novo recurso criado no cluster ou no namespace quando você não especifica a anotação cnrm.cloud.google.com/state-into-spec nos arquivos YAML de recursos novos. Isso significa que o Config Connector vai pular o preenchimento de campos não especificados na especificação de recursos do Kubernetes para esses recursos.

O campo stateIntoSpec não tem um valor padrão. O Config Connector determina o comportamento de preenchimento dos campos spec com base no valor da anotação cnrm.cloud.google.com/state-into-spec e segue a lógica abaixo para determinar o valor da anotação:

1. Use o valor da anotação cnrm.cloud.google.com/state-into-spec diretamente se ele for especificado e válido.
2. Se a anotação não for especificada, use o valor correspondente do campo stateIntoSpec no CR ConfigConnectorContext.
3. Se o CR ConfigConnectorContext não existir ou o campo stateIntoSpec não for especificado, use o valor correspondente do campo stateIntoSpec no CR ConfigConnector.
4. Se o CR do ConfigConnector não existir ou o campo stateIntoSpec não for especificado, use o comportamento padrão com base no CRD descrito em Comportamentos de preenchimento de campos spec.

Observe que o único comportamento de preenchimento de CRDs adicionado na versão 1.114.0 e mais recente é Absent, independente da anotação cnrm.cloud.google.com/state-into-spec ou dos campos stateIntoSpec no CR do ConfigConnector ou CR do ConfigConnectorContext.

Se você já tiver criado o recurso, mas quiser mudar o comportamento de preenchimento dos campos spec para Absent, faça o seguinte:

1. Verifique se a substituição de stateIntoSpec no nível do cluster ou do namespace é Absent no CR do ConfigConnector ou no CR do ConfigConnectorContext.

2. Abandone e adquira o recurso. Verifique se a configuração YAML usada para aquisição não tem a anotação cnrm.cloud.google.com/state-into-spec.

Especificar a anotação cnrm.cloud.google.com/state-into-spec no nível do recurso

Ao criar o arquivo YAML, você pode especificar o valor da anotação cnrm.cloud.google.com/state-into-spec como absent. Isso evita o preenchimento de campos não especificados na especificação de recursos do Kubernetes:

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

Se não for especificado, o valor padrão dessa anotação será merge, o que significa que o Config Connector vai preencher todos os campos não especificados em "spec". Essa anotação é imutável, ou seja, não é possível atualizar o valor de uma anotação de um recurso do Config Connector.

Se você já tiver criado o recurso, mas quiser mudar o valor dessa anotação para um comportamento de preenchimento diferente, siga estas etapas:

1. Edite e adicione a anotação cnrm.cloud.google.com/deletion-policy: abandon ao recurso do Kubernetes atual para garantir que a exclusão na próxima etapa não exclua o recurso Google Cloud subjacente.

2. Exclua o recurso do cluster do Kubernetes.

3. Adicione a anotação cnrm.cloud.google.com/state-into-spec: absent ao YAML do recurso.

4. (Opcional) Remova cnrm.cloud.google.com/deletion-policy: abandon do YAML.

5. Aplique o YAML atualizado.

Para explicar melhor a diferença introduzida por essa anotação, suponha que haja uma especificação com o seguinte esquema:

foo1: string
foo2: string
bars:
- bar:
    br1: string
    br2: string
barz:
  bz1: string
  bz2: string

Também suponha que você especificou a especificação no YAML como:

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

Por padrão, a especificação preenchida no recurso do Kubernetes criado pode ser:

spec:
  foo1: "foo1"
  foo2: "foo2"
  bars:
  - br1: "1_br1"
    br2: "1_br2"
  - br1: "2_br1"
    br2: "2_br2"
  barz:
    bz1: "bz1"
    bz2: "bz2"

Se você definir cnrm.cloud.google.com/state-into-spec: absent, a especificação final no recurso do Kubernetes criado será:

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

Quando usar cnrm.cloud.google.com/state-into-spec: absent

Na maioria dos casos, convém definir cnrm.cloud.google.com/state-into-spec: absent para receber o comportamento de preenchimento Absent para campos spec. Confira os cenários mais comuns que se beneficiam do comportamento de preenchimento do Absent.

Gerenciar campos não especificados em uma lista externamente

O Config Connector trata todos os campos de lista na especificação de recursos do Kubernetes como campos atômicos. Como resultado, por padrão, a mudança feita em um subcampo na lista de fora do Config Connector será revertida por ele. No entanto, você pode usar essa anotação para permitir que o Config Connector pare de gerenciar subcampos na lista. Para mais informações, consulte Comportamento dos campos de lista na especificação de recursos.

Resolver conflitos entre ferramentas de gerenciamento de configuração e o Config Connector

Se você estiver usando ferramentas de gerenciamento de configuração como Config Sync ou Argo CD, talvez note uma disputa entre a ferramenta de gerenciamento de configuração e o Config Connector. Um exemplo é o erro KNV2005 explicado no guia de solução de problemas. A causa principal desses tipos de problemas é:

1. O Config Connector vai preencher e definir como padrão valores não especificados na lista da especificação. spec.bars[0].br2 é um exemplo.
2. As ferramentas de gerenciamento de configuração e o Config Connector tratam os campos de lista como atômicos. Assim, o spec.bars[0].br2 adicionado é tratado como uma deriva pelas ferramentas de gerenciamento de configuração e será removido para corrigir o drift.

Para resolver esses problemas, defina cnrm.cloud.google.com/state-into-spec: absent para que o Config Connector não adicione o campo não especificado spec.bars[0].br2 à especificação.

Resolver problemas de simetria GET/PUT

A simetria GET/PUT se refere a um princípio de design na API REST. Especificamente, isso significa que, quando uma resposta GET é enviada como uma solicitação PUT para o mesmo URL, o resultado esperado é uma resposta HTTP 200 OK sem mudança no estado do recurso REST subjacente.

Os campos não especificados preenchidos pelo Config Connector na especificação de recursos do Kubernetes são resultado de uma solicitação GET. Isso significa que, em reconciliações futuras, o Config Connector poderá enviar uma solicitação PUT/PATCH para aGoogle Cloud API subjacente com esses valores de campo não especificados aprendidos com a solicitação GET. Isso geralmente não é um problema, mas é possível que algumas APIsGoogle Cloud rejeitem a solicitação PUT/PATCH devido a esses valores de campo não especificados. No mesmo exemplo, o spec.barz.bz2 preenchido com o valor "bz2" pode resultar em um erro de cliente HTTP 400 ou outras respostas inesperadas se a implementação da API violar o princípio de simetria GET/PUT.

Para evitar esse tipo de problema, teste definir cnrm.cloud.google.com/state-into-spec: absent e verifique se os erros durante o processo de reconciliação desaparecem.

Estado observado

Se você precisar definir cnrm.cloud.google.com/state-into-spec: absent, mas sua solução depender dos valores preenchidos de campos não especificados, verifique se esses campos existem em status.observedState no esquema CRD. Se eles forem representados em status.observedState, você poderá definir cnrm.cloud.google.com/state-into-spec: absent e ainda acessar os valores dos campos não especificados após uma conciliação bem-sucedida.

O campo status.observedState contém o estado ativo dos campos selecionados e observados do recurso que o Config Connector observou na última reconciliação bem-sucedida. Os campos observados são selecionados se forem dependências de casos de uso comuns e forem campos spec. É possível encontrar os campos observados nos esquemas de CRD.

Se você não encontrar os campos observados desejados, verifique se há um problema ou abra um novo nos issue trackers públicos .

Tipos com suporte a Merge

Estes são todos os tipos do Config Connector que oferecem suporte ao comportamento de preenchimento de Merge:

• 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
• Pasta
• 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
• Projeto
• PubSubLiteReservation
• PubSubSchema
• PubSubSubscription
• PubSubTopic
• RecaptchaEnterpriseKey
• RedisInstance
• ResourceManagerLien
• ResourceManagerPolicy
• RunJob
• RunService
• SQLDatabase
• SQLSSLCert
• SQLUser
• SecretManagerSecret
• SecretManagerSecretVersion
• Serviço
• ServiceDirectoryEndpoint
• ServiceDirectoryNamespace
• ServiceDirectoryService
• ServiceIdentity
• ServiceNetworkingConnection
• SourceRepoRepository
• SpannerDatabase
• SpannerInstance
• StorageBucket
• StorageBucketAccessControl
• StorageDefaultObjectAccessControl
• StorageNotification
• StorageTransferJob
• VPCAccessConnector

Os seguintes tipos não são compatíveis com o comportamento de preenchimento Merge a partir da versão correspondente: