API obsolètes de Kubernetes 1.22

Autopilot Standard

Cette page explique comment préparer des clusters pour les mises à niveau vers la version 1.22 de GKE. Vous pouvez trouver les clients API effectuant des appels vers des API obsolètes supprimées dans la version 1.22 et les mettre à jour pour qu'ils utilisent les API en disponibilité générale. Pour en savoir plus, consultez le guide de migration des API obsolètes de Kubernetes.

API supprimées dans la version 1.22

La plupart des API obsolètes dans la version 1.22 de Kubernetes sont d'anciennes API bêta qui sont passées depuis de la version bêta (v1beta1) à la disponibilité générale (v1). Les API en disponibilité générale offrent des garanties de compatibilité à long terme et doivent être utilisées à la place des API bêta obsolètes.

Vous pouvez interagir avec tous les objets existants à l'aide des API en disponibilité générale.

Important : Avant de passer à la version 1.22, vous devez mettre à jour les clients API et les fichiers manifestes afin qu'ils utilisent les API en disponibilité générale.

Ressources Webhook

La version d'API bêta de MutatingWebhookConfiguration et ValidatingWebhookConfiguration n'est plus diffusée à partir de la version 1.22.

• Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API admissionRegistration.k8s.io/v1.

• Reportez-vous au tableau suivant qui décrit les modifications notables apportées à la version de l'API en disponibilité générale :

  Champ	Modifier
  webhooks[*].failurePolicy	La valeur par défaut est passée de Ignore à Fail.
  webhooks[*].matchPolicy	La valeur par défaut est passée de Exact à Equivalent.
  webhooks[*].timeoutSeconds	La valeur par défaut est passée de 30s à 10s.
  webhooks[*].sideEffects	La valeur par défaut est supprimée et le champ est désormais obligatoire. Seuls None et NoneOnDryRun sont autorisés.
  webhooks[*].admissionReviewVersions	La valeur par défaut est supprimée et le champ est désormais obligatoire (les versions autorisées pour AdmissionReview sont v1 et v1beta1).
  webhooks[*].name	Le nom doit être unique dans la liste des objets créés via admissionregistration.k8s.io/v1.

CustomResourceDefinition

La version d'API bêta de CustomResourceDefinition n'est plus diffusée à partir de la version 1.22.

• Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API apiextensions.k8s.io/v1.

• Reportez-vous au tableau suivant qui décrit les modifications notables apportées à la version de l'API en disponibilité générale :

  Champ	Modifier
  spec.scope	N'est plus défini par défaut sur Namespaced. La valeur doit être spécifiée explicitement.
  spec.version	Supprimé. Utilisez plutôt spec.versions.
  spec.validation	Supprimé. Utilisez plutôt spec.versions[*].schema.
  spec.subresources	Supprimé. Utilisez plutôt spec.versions[*].subresources.
  spec.additionalPrinterColumns	Supprimé. Utilisez plutôt spec.versions[*].additionalPrinterColumns.
  spec.conversion.webhookClientConfig	Déplacé vers spec.conversion.webhook.clientConfig.
  spec.conversion.conversionReviewVersions	Déplacé vers spec.conversion.webhook.conversionReviewVersions.
  spec.versions[*].schema.openAPIV3Schema	Désormais requis pour créer des objets CustomResourceDefinition v1, il doit s'agir d'un schéma de structure.
  spec.preserveUnknownFields	La valeur true n'est pas autorisée lors de la création d'objets CustomResourceDefinition v1. La valeur doit être spécifiée dans les définitions de schéma en tant que x-kubernetes-preserve-unknown-fields: true.
  additionalPrinterColumns	Dans les éléments additionalPrinterColumns, le champ JSONPath a été renommé en jsonPath.

APIService

La version d'API bêta de APIService n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API apiregistration.k8s.io/v1.

TokenReview

La version d'API bêta de TokenReview n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API authentication.k8s.io/v1.

Ressources SubjectAccessReview

La version d'API bêta de LocalSubjectAccessReview, SelfSubjectAccessReview et SubjectAccessReview n'est plus diffusée à partir de la version 1.22.

• Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API authorization.k8s.io/v1.

• Reportez-vous au tableau suivant qui décrit les modifications notables apportées à la version de l'API en disponibilité générale :

  Champ	Modifier
  spec.group	Renommé en spec.groups.

CertificateSigningRequest

La version d'API bêta de CertificateSigningRequest n'est plus diffusée à partir de la version 1.22.

• Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API certificates.k8s.io/v1.

• Reportez-vous au tableau suivant qui décrit les modifications notables apportées à la version de l'API en disponibilité générale :

  Champ	Modifier
  spec.signerName	Pour les clients API exigeant des certificats, ce champ est obligatoire (voir signataires Kubernetes connus), et la création de requêtes pour kubernetes.io/legacy-unknown n'est pas autorisée via l'API certificates.k8s.io/v1.
  spec.usages	Pour les clients API exigeant des certificats, ce champ est obligatoire. Ce champ ne peut pas contenir de valeurs en double et ne doit contenir que des utilisations connues.
  status.conditions	Pour les clients API qui approuvent ou signent des certificats, ce champ ne peut pas contenir de types en double.
  status.conditions[*].status	Pour les clients API qui approuvent ou signent des certificats, ce champ est désormais obligatoire.
  status.certificate	Pour les clients API qui approuvent ou signent des certificats, ce champ doit être encodé au format PEM et ne contenir que des blocs CERTIFICATE.

Lease

La version d'API bêta de Lease n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API coordination.k8s.io/v1.

Ingress (disponible jusqu'à la version 1.23 pour les clusters créés dans la version 1.21 ou antérieure)

Les versions d'API bêta (extensions/v1beta1 et networking.k8s.io/v1beta1) de Ingress ne sont plus diffusées pour les clusters GKE exécutant la version 1.22 ou ultérieure si le cluster a été créé sur la version 1.22 ou ultérieure.

Toutefois, pour les clusters créés sur GKE 1.21 ou version antérieure et mis à niveau vers la version 1.22 sur la version de correctif 1.22.7-gke.300 ou ultérieure, vous pouvez toujours utiliser les versions d'API bêta jusqu'à ce que le cluster soit mis à niveau vers la version 1.23. Il s'agit d'une exception unique pour les anciens clusters afin de vous laisser plus de temps pour migrer vos clusters à l'aide de ces versions d'API qui sont supprimées de la version Open Source de Kubernetes 1.22.

Les clusters exécutant la version 1.23 de GKE ou une version ultérieure ne diffusent plus les API bêta Ingress obsolètes. Les fichiers manifestes utilisant ces versions d'API ne peuvent plus être appliqués. Les objets persistants précédemment restent fonctionnels et peuvent être consultés et mis à jour à l'aide des nouvelles versions de l'API, avant et après la mise à niveau vers la version 1.23.

• Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API networking.k8s.io/v1.

• Reportez-vous au tableau suivant qui décrit les modifications notables apportées à la version de l'API en disponibilité générale :

  Champ	Modifier
  spec.backend	Renommé en spec.defaultBackend.
  Backend serviceName	Renommé en service.name.
  servicePort	Les champs servicePort de backend de types numériques sont renommés en service.port.number. Les champs servicePort de backend de types chaînes sont renommés en service.port.name.
  pathType	Désormais requis pour chaque chemin d'accès spécifié. La valeur peut être Prefix, Exact ou ImplementationSpecific. Pour correspondre au comportement v1beta1 non défini, utilisez ImplementationSpecific.

Les fichiers manifestes suivants décrivent la même entrée dans v1 et v1beta1 :

Fichier manifeste v1beta1

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example
spec:
  backend:
    serviceName: default-backend
    servicePort: 80
  rules:
  - http:
      paths:
      - path: /testpath
        backend:
          serviceName: test
          servicePort: 80

Fichier manifeste v1

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
spec:
  defaultBackend:
    service:
      name: default-backend
      port:
        number: 80
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: ImplementationSpecific
        backend:
          service:
            name: test
            port:
              number: 80

Vous pouvez utiliser la requête suivante pour les clusters sur lesquels l'observabilité Google Cloud est activée afin d'identifier les clients qui accèdent aux API Ingress v1beta1 :

resource.type="k8s_cluster"
resource.labels.cluster_name="$CLUSTER_NAME"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.request.apiVersion=("extensions/v1beta1" OR "networking.k8s.io/v1beta1")
protoPayload.request.kind="Ingress"
NOT ("kube-system")

IngressClass

La version d'API bêta de IngressClass n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API networking.k8s.io/v1.

Ressources RBAC

La version d'API bêta de ClusterRole, ClusterRoleBinding, Role et RoleBinding n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API rbac.authorization.k8s.io/v1.

PriorityClass

La version d'API bêta de PriorityClass n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API scheduling.k8s.io/v1.

Ressources de stockage

La version d'API bêta de CSIDriver, CSINode, StorageClass et VolumeAttachment n'est plus diffusée à partir de la version 1.22. Migrez les fichiers manifestes et les clients API pour qu'ils utilisent la version d'API storage.k8s.io/v1.

Rechercher les clusters utilisant des API obsolètes

Vous pouvez identifier les clusters qui utilisent des API obsolètes à partir des insights d'obsolescence. Les insights d'obsolescence fournissent également des informations telles que l'identification des clients API qui appellent les API obsolètes dans votre cluster.

Vous pouvez également utiliser les journaux d'audit pour identifier les clients qui appellent des API obsolètes.

Localiser les clients API effectuant des appels en écriture auprès d'API obsolètes

Pour les clusters sur lesquels l'observabilité Google Cloud est activée, vous pouvez utiliser la requête suivante sur les journaux d'audit des activités d'administration pour afficher les cas d'utilisation d'API obsolètes par des user-agents non gérés par Google :

resource.type="k8s_cluster"
labels."k8s.io/removed-release"="DEPRECATED_API_MINOR_VERSION"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.authenticationInfo.principalEmail!~("system:serviceaccount:kube-system:")

Remplacez DEPRECATED_API_MINOR_VERSION par la version mineure dans laquelle l'API obsolète a été supprimée, par exemple 1.22.

Les journaux d'audit pour les activités d'administration sont automatiquement activés pour les clusters GKE. Avec cette requête, les journaux affichent les user-agents effectuant des appels en écriture vers les API obsolètes.

Localiser les clients API effectuant des appels en lecture auprès d'API obsolètes

Par défaut, les journaux d'audit n'affichent que les appels en écriture auprès d'API obsolètes. Pour afficher également les appels en lecture auprès d'API obsolètes, configurez les journaux d'audit pour l'accès aux données.

Attention : Si vous activez des journaux d'audit supplémentaires, cela peut entraîner des coûts de journalisation supplémentaires. Le volume des journaux d'audit pour l'accès aux données qui ont été ingérés est comptabilisé dans le quota d'ingestion de journaux de Cloud Logging.

Suivez les instructions pour configurer les journaux d'audit pour l'accès aux données avec la console Google Cloud . Dans la console Google Cloud , sélectionnez l'API Kubernetes Engine. Dans l'onglet "Types de journaux" du panneau d'informations, sélectionnez Admin Read et Data Read.

Lorsque ces journaux sont activés, vous pouvez utiliser la requête d'origine pour afficher à la fois les appels en lecture et les appels en écriture auprès d'API obsolètes.

Mettre à niveau des composants tiers

Les insights d'obsolescence peuvent afficher les résultats des agents tiers qui appellent des API obsolètes dans votre cluster.

Pour résoudre ces problèmes, procédez comme suit :

1. Contactez votre fournisseur de logiciels tiers pour obtenir une version mise à jour.
2. Mettez à niveau le logiciel tiers vers la dernière version. Si vous ne pouvez pas mettre à niveau le logiciel, vous devez vérifier si la mise à niveau de GKE vers la version avec les API supprimées entraîne l'interruption du service.

Nous vous recommandons de mettre à niveau cette version et la version de GKE sur un cluster de préproduction pour surveiller les interruptions avant de mettre à niveau vos clusters de production.

Préparer la mise à niveau vers la version 1.22

Vous n'avez pas besoin de supprimer, ni de recréer les objets API. Tous les objets API persistants existants peuvent déjà être lus et mis à jour à l'aide des nouvelles versions d'API. Toutefois, nous vous recommandons de migrer vos clients et vos fichiers manifestes avant de passer à Kubernetes 1.22. Pour en savoir plus, consultez la section "Comment procéder" du guide de migration des API obsolètes de Kubernetes.

Vous pouvez afficher les insights et les recommandations d'obsolescence pour déterminer si votre cluster utilise une fonctionnalité Kubernetes ou une API obsolète. Les insights d'obsolescence sont basés sur les appels d'API observés aux API obsolètes par les user agents, et non sur la configuration de vos objets Kubernetes.

Avertissement : Si vous ne mettez pas à jour un client ou un fichier manifeste avant la mise à jour vers la version 1.22, celui-ci ne pourra pas lire ou modifier les objets existants, ni en créer. Le client ou le fichier manifeste ne peut lire, modifier ou créer des objets qu'après sa mise à jour.

Mettre à jour les clusters affectés par les obsolescences

Pour mettre à niveau les clusters concernés par ces abandons, procédez comme suit :

1. Vérifiez quels user-agents utilisent les API obsolètes dans l'insight d'obsolescence ou les journaux.
2. Mettez à jour les user-agents qui utilisent les API obsolètes pour utiliser les versions d'API compatibles.
3. Mettez à jour tout logiciel tiers qui appelle les API obsolètes vers les dernières versions.
4. Mettez à niveau un cluster de test et testez votre application dans un environnement de test avant de mettre à niveau votre cluster de production afin de réduire le risque d'interruption lorsque les API obsolètes ne sont plus disponibles.
5. Après avoir mis à jour tous les user-agents, GKE attend qu'il n'ait plus observé d'utilisation d'API obsolètes pendant 30 jours, puis débloque les mises à niveau automatiques. Les mises à niveau automatiques se déroulent selon le calendrier des lancements.
6. Si vous ne pouvez pas mettre à jour un user-agent concerné, mettez à niveau un cluster de test distinct pour vérifier si la mise à niveau entraîne des perturbations. Si la mise à niveau n'entraîne pas de perturbations, vous pouvez mettre à niveau votre cluster manuellement.

Ressources

Pour plus d'informations, consultez la documentation Open Source de Kubernetes :

• Blog Kubernetes : suppressions d'API pour Kubernetes version 1.22
• Notes de version de Kubernetes 1.22
• Guide de migration des API obsolètes de Kubernetes