Ignorer les champs non spécifiés


Cette page explique le comportement de remplissage par défaut des champs spec et comment remplacer le comportement par défaut Merge par le comportement recommandé Absent. Il est possible que cette page ne s'applique pas si vous utilisez un objet CRD ajouté à partir de la version 1.114.0, car ces objets CRD n'utilisent que le comportement Absent. Pour obtenir la liste des objets CRD compatibles avec Merge, consultez la section CRD compatibles avec Merge de cette page.

Remplissage des comportements par les champs spec

Lorsque Config Connector crée une ressource, les champs non spécifiés dans la spécification de ressource Kubernetes peuvent avoir deux comportements de remplissage par défaut différents : Absent et Merge.

Manquante

Absent est le comportement recommandé. Config Connector ne renseigne aucun champ non spécifié dans la spécification.

Pour les objets CRD ajoutés à partir de la version 1.114.0, le comportement de remplissage par défaut est Absent. Il s'agit également du seul comportement de remplissage pris en charge par ces CRD. La valeur de l'annotation cnrm.cloud.google.com/state-into-spec est absent dans ces RS de ressources.

Fusionner

Merge n'est pas un comportement non compatible dans les CRD ajoutées à partir de la version 1.114.0. Les champs spec utilisent des valeurs de l'API après un rapprochement réussi, sauf si elles ne sont pas lisibles. Pour en savoir plus, consultez la section Gérer les champs en externe.

Pour les objets CRD compatibles avec la version 1.113.0 et les versions antérieures de Config Connector, le comportement de remplissage par défaut est Merge. Pour obtenir la liste des objets CRD compatibles avec Merge, consultez la section CRD compatibles avec Merge de cette page. La valeur par défaut de l'annotation cnrm.cloud.google.com/state-into-spec est merge dans ces RS de ressources. Vous pouvez également configurer le comportement de remplissage sur Absent en suivant les instructions de la section Ignorer le remplissage des champs non spécifiés dans la spécification.

Par défaut, dans ces RS concernant les ressources, les champs qui n'ont pas été spécifiés dans le fichier YAML d'origine apparaissent toujours dans la spécification de la RS. Cela signifie que lorsque vous exécutez kubectl get <resource kind> <resource name> -oyaml, de nombreux champs de la spécification ne figurent pas dans le fichier YAML appliqué.

Par exemple, supposons que le schéma CRD vous permette de spécifier deux champs nommés foo et bar dans la spécification, alors que seul foo est spécifié dans le fichier YAML appliqué:

spec:
  foo: "foo"

Vous remarquerez qu'un autre champ nommé bar apparaît dans la RS si le fichier YAML a bien été appliqué et que la ressource est UpToDate:

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

En raison de la complexité des interactions entre Config Connector et les API Google Cloud, vous pouvez modifier ce comportement par défaut et ignorer l'ajout de champs non spécifiés à la spécification de ressource Kubernetes.

Ignorer le remplissage des champs non spécifiés dans la spécification

Vous pouvez ignorer l'insertion des champs non spécifiés dans les spécifications des objets CRD compatibles avec la version 1.113.0 et les versions antérieures de Config Connector de l'une des manières suivantes:

  • Configurez le remplacement stateIntoSpec au niveau du cluster ou de l'espace de noms sur Absent.
  • Spécifiez la valeur de l'annotation cnrm.cloud.google.com/state-into-spec comme absent pour la ressource.

Configurer le forçage stateIntoSpec au niveau du cluster ou de l'espace de noms

Lors de l'installation de Config Connector ou de la mise à jour de l'installation de Config Connector, vous pouvez configurer le remplacement stateIntoSpec au niveau du cluster ou de l'espace de noms sur Absent dans la RS de ConfigConnector ou de ConfigConnectorContext.

spec:
  stateIntoSpec: Absent

Ainsi, Absent devient le champ spec par défaut qui remplit le comportement pour toutes les nouvelles ressources créées dans le cluster ou dans l'espace de noms lorsque vous ne spécifiez pas l'annotation cnrm.cloud.google.com/state-into-spec dans les fichiers YAML de nouvelle ressource. Cela signifie que Config Connector ignore le remplissage des champs non spécifiés dans la spécification de ressource Kubernetes pour ces ressources.

Le champ stateIntoSpec n'a pas de valeur par défaut. Config Connector détermine le comportement qui remplit les champs spec en fonction de la valeur de l'annotation cnrm.cloud.google.com/state-into-spec. Il suit la logique ci-dessous pour déterminer la valeur de l'annotation:

  1. Utilisez directement la valeur de l'annotation cnrm.cloud.google.com/state-into-spec si elle est spécifiée et valide.
  2. Si l'annotation n'est pas spécifiée, utilisez la valeur correspondante du champ stateIntoSpec dans la RS ConfigConnectorContext.
  3. Si la RS ConfigConnectorContext n'existe pas ou si le champ stateIntoSpec n'est pas spécifié, utilisez la valeur correspondante du champ stateIntoSpec dans la RS ConfigConnector.
  4. Si la RS ConfigConnector n'existe pas ou si le champ stateIntoSpec n'est pas spécifié, utilisez le comportement par défaut basé sur l'objet CRD décrit dans les comportements de remplissage des champs spec.

Notez que les seules CRD de comportement ajoutées à partir de la version 1.114.0 et ultérieures sont Absent, indépendamment de l'annotation cnrm.cloud.google.com/state-into-spec ou des champs stateIntoSpec de la RS ConfigConnector ou de la RS ConfigConnectorContext.

Si vous avez déjà créé la ressource, mais que vous souhaitez remplacer le comportement de remplissage des champs spec par Absent, procédez comme suit:

  1. Assurez-vous que le remplacement stateIntoSpec au niveau du cluster ou de l'espace de noms est défini sur Absent dans la RS ConfigConnector ou la RS ConfigConnectorContext.

  2. Abandonnez et acquérez la ressource. Assurez-vous que la configuration YAML utilisée pour l'acquisition ne comporte pas l'annotation cnrm.cloud.google.com/state-into-spec.

Spécifiez l'annotation cnrm.cloud.google.com/state-into-spec au niveau de la ressource.

Lorsque vous créez votre fichier YAML, vous pouvez spécifier la valeur de l'annotation cnrm.cloud.google.com/state-into-spec en tant que absent. Le remplissage des champs non spécifiés dans la spécification de ressource Kubernetes est ignoré:

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

La valeur par défaut de cette annotation est merge si elle n'est pas spécifiée, ce qui signifie que Config Connector renseigne tous les champs non spécifiés dans la spécification. Cette annotation est immuable, ce qui signifie que vous ne pouvez pas mettre à jour la valeur d'annotation d'une ressource Config Connector existante.

Si vous avez déjà créé la ressource, mais que vous souhaitez modifier la valeur de cette annotation pour un comportement de remplissage différent, procédez comme suit:

  1. Modifiez et ajoutez l'annotation cnrm.cloud.google.com/deletion-policy: abandon à la ressource Kubernetes existante pour vous assurer que la suppression à l'étape suivante ne supprimera pas la ressource Google Cloud sous-jacente.

  2. Supprimez la ressource du cluster Kubernetes.

  3. Ajoutez l'annotation cnrm.cloud.google.com/state-into-spec: absent au fichier YAML de la ressource.

  4. (Facultatif) Supprimez cnrm.cloud.google.com/deletion-policy: abandon du fichier YAML.

  5. Appliquez le fichier YAML mis à jour.

Pour expliquer plus en détail la différence introduite par cette annotation, supposons qu'il existe une spécification avec le schéma suivant:

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

Supposons également que vous ayez spécifié la spécification dans votre fichier YAML comme suit:

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

Ensuite, par défaut, la spécification renseignée dans la ressource Kubernetes créée peut être:

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

Alors que si vous définissez cnrm.cloud.google.com/state-into-spec: absent, la spécification finale de la ressource Kubernetes créée est la suivante:

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

Dans quel contexte utiliser cnrm.cloud.google.com/state-into-spec: absent ?

Dans la plupart des cas, vous devez définir cnrm.cloud.google.com/state-into-spec: absent pour obtenir le comportement de remplissage Absent pour les champs spec. Voici les scénarios les plus courants qui bénéficieront du comportement de remplissage Absent.

Gérer les champs non spécifiés d'une liste en externe

Config Connector traite tous les champs de liste de la spécification de ressources Kubernetes comme des champs atomiques. Par conséquent, la modification apportée par défaut à un sous-champ de la liste en dehors de Config Connector sera annulée par Config Connector. Toutefois, vous pouvez utiliser cette annotation pour permettre à Config Connector d'annuler la gestion des sous-champs de la liste. Pour en savoir plus, consultez la section Comportement des champs de liste dans les spécifications de ressources.

Résoudre les conflits entre les outils de gestion de configuration et Config Connector

Si vous utilisez des outils de gestion de la configuration tels que Config Sync ou Argo CD, vous remarquerez peut-être un conflit entre l'outil de gestion des configurations et Config Connector. L'erreur KNV2005 décrite dans le guide de dépannage en est un exemple. La cause première de ces types de problèmes est les suivantes:

  1. Config Connector insérera les valeurs par défaut non spécifiées dans la liste de la spécification. spec.bars[0].br2 est un exemple.
  2. Les outils de gestion de la configuration et Config Connector traitent les champs de liste comme atomiques. Par conséquent, la spec.bars[0].br2 ajoutée est traitée comme une dérive par les outils de gestion de la configuration et sera supprimée pour corriger la drift.

Pour résoudre ces problèmes, vous pouvez définir cnrm.cloud.google.com/state-into-spec: absent afin que Config Connector n'ajoute pas de champ non spécifié spec.bars[0].br2 dans la spécification.

Résoudre les problèmes de symétrie GET/PUT

La symétrie GET/PUT fait référence à un principe de conception dans l'API REST. Plus précisément, cela signifie que lorsqu'une réponse GET est envoyée sous forme de requête PUT à la même URL, le résultat attendu est une réponse HTTP 200 OK sans modification de l'état de la ressource REST sous-jacente.

Les champs non spécifiés renseignés par Config Connector dans la spécification de ressource Kubernetes résultent d'une requête GET. Cela signifie que lors de futurs rapprochements, Config Connector peut envoyer une requête PUT/PATCH à l'API Google Cloud sous-jacente, avec ces valeurs de champ non spécifiées apprises de la requête GET. Ce n'est généralement pas un problème, mais il est possible que certaines API Google Cloud rejettent la requête PUT/PATCH en raison de ces valeurs de champ non spécifiées. Dans le même exemple, le spec.barz.bz2 renseigné avec la valeur "bz2" peut entraîner une erreur client HTTP 400 ou d'autres réponses inattendues si l'implémentation de l'API ne respecte pas le principe de symétrie GET/PUT.

Pour éviter cette catégorie de problèmes, vous pouvez tester le paramètre cnrm.cloud.google.com/state-into-spec: absent et vérifier si les erreurs vont disparaître lors du rapprochement.

État observé

Si vous devez définir cnrm.cloud.google.com/state-into-spec: absent, mais que votre solution dépend des valeurs renseignées à partir de champs non spécifiés, vérifiez si ces champs existent sous status.observedState dans le schéma CRD. S'ils sont représentés sous status.observedState, vous pouvez définir cnrm.cloud.google.com/state-into-spec: absent et continuer à accéder aux valeurs des champs non spécifiés après un rapprochement réussi.

Le champ status.observedState contient l'état actuel des champs observés et sélectionnés de la ressource que Config Connector a observé lors du dernier rapprochement réussi. Les champs observés sont sélectionnés s'ils sont des dépendances de cas d'utilisation courants et sont des champs calculés spec. Vous pouvez trouver les champs observés dans les schémas CRD.

Si vous ne trouvez pas les champs observés souhaités, recherchez un problème existant ou ouvrez un nouveau problème dans les outils publics de suivi des problèmes.

CRD compatibles avec Merge

Voici toutes les CRD compatibles avec le comportement de remplissage Merge:

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