API Kubernetes 1.22 deprecate

Questa pagina spiega come preparare i cluster per gli upgrade a GKE versione 1.22. Puoi trovare i client API che effettuano chiamate alle API deprecate rimosse nella versione 1.22 e aggiornarli in modo che utilizzino le API GA. Per informazioni più dettagliate, consulta la guida alla migrazione delle API deprecate di Kubernetes.

API rimosse nella versione 1.22

La maggior parte delle API deprecate nella versione 1.22 di Kubernetes sono ex API beta che sono state promosse dalla versione beta (v1beta1) alla versione GA (v1). Le API GA offrono garanzie di compatibilità a lungo termine e devono essere utilizzate al posto delle API beta deprecate.

È possibile interagire con tutti gli oggetti esistenti utilizzando le API GA.

Risorse webhook

La versione beta dell'API di MutatingWebhookConfiguration e ValidatingWebhookConfiguration non viene più pubblicata a partire dalla versione 1.22.

  • Esegui la migrazione dei manifest e dei client API per utilizzare la versione API admissionregistration.k8s.io/v1.

  • Consulta la tabella seguente, che descrive le modifiche più importanti nella versione dell'API GA:

    Campo Cambia
    webhooks[*].failurePolicy Il valore predefinito è stato modificato da Ignore a Fail.
    webhooks[*].matchPolicy Il valore predefinito è stato modificato da Exact a Equivalent.
    webhooks[*].timeoutSeconds Il valore predefinito è stato modificato da 30s a 10s.
    webhooks[*].sideEffects Il valore predefinito viene rimosso e il campo ora è obbligatorio. Sono consentiti solo None e NoneOnDryRun.
    webhooks[*].admissionReviewVersions Il valore predefinito viene rimosso e il campo ora è obbligatorio (le versioni supportate per AdmissionReview sono v1 e v1beta1).
    webhooks[*].name Deve essere univoco nell'elenco per gli oggetti creati tramite admissionregistration.k8s.io/v1.

CustomResourceDefinition

La versione beta dell'API di CustomResourceDefinition non viene più pubblicata a partire dalla versione 1.22.

  • Esegui la migrazione dei manifest e dei client API per utilizzare la versione dell'API apiextensions.k8s.io/v1.

  • Consulta la tabella seguente, che descrive le modifiche più importanti nella versione dell'API GA:

    Campo Cambia
    spec.scope Non è più impostato come predefinito su Namespaced. Il valore deve essere specificato in modo esplicito.
    spec.version Rimosso. Utilizza invece spec.versions.
    spec.validation Rimosso. Utilizza invece spec.versions[*].schema.
    spec.subresources Rimosso. Utilizza invece spec.versions[*].subresources.
    spec.additionalPrinterColumns Rimosso. Utilizza invece spec.versions[*].additionalPrinterColumns.
    spec.conversion.webhookClientConfig Spostato in spec.conversion.webhook.clientConfig.
    spec.conversion.conversionReviewVersions Spostato in spec.conversion.webhook.conversionReviewVersions.
    spec.versions[*].schema.openAPIV3Schema Ora obbligatorio durante la creazione di oggetti v1 CustomResourceDefinition e deve essere uno schema strutturale.
    spec.preserveUnknownFields Il valore true non è consentito durante la creazione di oggetti CustomResourceDefinition v1. Il valore deve essere specificato all'interno delle definizioni dello schema come x-kubernetes-preserve-unknown-fields: true.
    additionalPrinterColumns In additionalPrinterColumns elementi, il campo JSONPath è stato rinominato in jsonPath.

APIService

La versione beta dell'API di APIService non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione dell'API apiregistration.k8s.io/v1.

TokenReview

La versione beta dell'API di TokenReview non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione dell'API authentication.k8s.io/v1.

Risorse per la revisione dell'accesso ai dati del soggetto

La versione beta dell'API di LocalSubjectAccessReview, SelfSubjectAccessReview e SubjectAccessReview non viene più pubblicata a partire dalla versione 1.22.

  • Esegui la migrazione dei manifest e dei client API per utilizzare la versione API authorization.k8s.io/v1.

  • Consulta la tabella seguente, che descrive le modifiche più importanti nella versione dell'API GA:

    Campo Cambia
    spec.group Rinominato in spec.groups.

CertificateSigningRequest

La versione beta dell'API di CertificateSigningRequest non viene più pubblicata a partire dalla versione 1.22.

  • Esegui la migrazione dei manifest e dei client API per utilizzare la versione API certificates.k8s.io/v1.

  • Consulta la tabella seguente, che descrive le modifiche più importanti nella versione dell'API GA:

    Campo Cambia
    spec.signerName Per i client API che richiedono certificati, questo campo è obbligatorio (vedi firmatari Kubernetes noti) e non è consentito creare richieste per kubernetes.io/legacy-unknown tramite l'API certificates.k8s.io/v1.
    spec.usages Questo campo è obbligatorio per i client API che richiedono certificati. Questo campo non può contenere valori duplicati e deve contenere solo utilizzi noti.
    status.conditions Per i client API che approvano o firmano certificati, questo campo non può contenere tipi duplicati.
    status.conditions[*].status Per i client API che approvano o firmano certificati, questo campo è ora obbligatorio.
    status.certificate Per i client API che approvano o firmano certificati, questo campo deve essere codificato in formato PEM e contenere solo blocchi CERTIFICATE.

Lease

La versione beta dell'API di Lease non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione dell'API coordination.k8s.io/v1.

Ingress (disponibile fino alla versione 1.23 per i cluster creati sulla versione 1.21 o precedenti)

Le versioni API beta (extensions/v1beta1 e networking.k8s.io/v1beta1) di Ingress non vengono più pubblicate per i cluster GKE che eseguono la versione 1.22 o successive se il cluster è stato creato sulla versione 1.22 o successive.

Tuttavia, per i cluster creati su GKE 1.21 o versioni precedenti ed eseguiti l'upgrade alla versione 1.22 nella versione patch 1.22.7-gke.300 o successive, puoi comunque utilizzare le versioni API beta finché il cluster non viene aggiornato alla versione 1.23. Si tratta di un'eccezione una tantum per i cluster meno recenti per darti più tempo per eseguire la migrazione dei cluster dall'utilizzo di queste versioni API che sono state rimosse da Kubernetes open source nella versione 1.22.

I cluster che eseguono GKE versione 1.23 e successive non gestiranno più le API beta Ingress deprecate. I manifest che utilizzano queste versioni dell'API non possono più essere applicati. Gli oggetti persistenti precedenti rimangono funzionali e possono essere visualizzati e aggiornati utilizzando le nuove versioni dell'API, prima e dopo l'upgrade alla versione 1.23.

  • Esegui la migrazione dei manifest e dei client API per utilizzare la versione API networking.k8s.io/v1.

  • Consulta la tabella seguente, che descrive le modifiche più importanti nella versione dell'API GA:

    Campo Cambia
    spec.backend Rinominato in spec.defaultBackend.
    backend serviceName Rinominato in service.name.
    servicePort I campi numerici di backend servicePort vengono rinominati in service.port.number. I campi del backend stringa servicePort sono stati rinominati in service.port.name.
    pathType Ora obbligatorio per ogni percorso specificato. Il valore può essere: Prefix, Exact o ImplementationSpecific. Per corrispondere al comportamento v1beta1 non definito, utilizza ImplementationSpecific.

I seguenti manifest descrivono lo stesso Ingress in v1 e v1beta1:

Manifest 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

Manifest 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

Puoi utilizzare la seguente query per i cluster con Google Cloud Observability abilitato per identificare i client che accedono alle 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 versione beta dell'API di IngressClass non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione dell'API networking.k8s.io/v1.

Risorse RBAC

La versione beta dell'API di ClusterRole, ClusterRoleBinding, Role e RoleBinding non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione API rbac.authorization.k8s.io/v1.

PriorityClass

La versione beta dell'API di PriorityClass non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione dell'API scheduling.k8s.io/v1.

Risorse di archiviazione

La versione beta dell'API di CSIDriver, CSINode, StorageClass e VolumeAttachment non viene più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API per utilizzare la versione API storage.k8s.io/v1.

Trovare cluster che utilizzano API ritirate

Puoi scoprire quali cluster utilizzano API obsolete dagli approfondimenti sul ritiro. Gli approfondimenti sull'obsolescenza forniscono anche informazioni quali i client API che chiamano le API obsolete nel tuo cluster.

Puoi anche utilizzare i log di controllo per scoprire quali client effettuano chiamate alle API ritirate.

Individuare i client API che effettuano chiamate di scrittura alle API deprecate

Per i cluster con Google Cloud Observability abilitato, puoi utilizzare la seguente query Log di controllo dell'attività di amministrazione per mostrare l'utilizzo delle API ritirate da user agent non gestiti da 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:")

Sostituisci DEPRECATED_API_MINOR_VERSION con la versione secondaria in cui viene rimossa l'API deprecata, ad esempio 1.22.

Gli audit log delle attività di amministrazione vengono attivati automaticamente per i cluster GKE. Con questa query, i log mostrano gli user agent che effettuano chiamate di scrittura alle API ritirate.

Individuare i client API che effettuano chiamate di lettura alle API deprecate

Per impostazione predefinita, i log di controllo mostrano solo le chiamate di scrittura alle API ritirate. Per visualizzare anche le chiamate di lettura alle API ritirate, configura gli audit log di accesso ai dati.

Segui le istruzioni per configurare gli audit log di accesso ai dati con la console Google Cloud . Nella console Google Cloud , seleziona l'API Kubernetes Engine. Nella scheda Tipi di log del riquadro delle informazioni, seleziona Admin Read e Data Read.

Con questi log abilitati, ora puoi utilizzare la query originale per visualizzare sia le chiamate di lettura sia le chiamate di scrittura alle API ritirate.

Aggiornamento dei componenti di terze parti

Approfondimenti sul ritiro potrebbero mostrare risultati per agenti di terze parti che effettuano chiamate ad API ritirate nel tuo cluster.

Per risolvere questi problemi, prova a seguire questi passaggi:

  1. Rivolgiti al fornitore del software di terze parti per una versione aggiornata.
  2. Esegui l'upgrade del software di terze parti all'ultima versione. Se non riesci ad eseguire l'upgrade del software, devi verificare se l'upgrade di GKE alla versione con le API ritirate rimosse interromperebbe il tuo servizio.

Ti consigliamo di eseguire questo upgrade e l'upgrade della versione GKE su un cluster di staging per monitorare eventuali interruzioni prima di eseguire l'upgrade dei cluster di produzione.

Preparazione dell'upgrade alla versione 1.22 in corso…

Non è necessario eliminare e ricreare nessuno degli oggetti API. Tutti gli oggetti API persistenti esistenti possono già essere letti e aggiornati utilizzando le nuove versioni dell'API. Tuttavia, ti consigliamo di eseguire la migrazione dei client e dei manifest prima di eseguire l'upgrade a Kubernetes 1.22. Scopri di più nella sezione "Cosa fare" della guida alla migrazione dell'API Kubernetes deprecata.

Puoi visualizzare approfondimenti e consigli sul ritiro per determinare se il tuo cluster utilizza una funzionalità o un'API Kubernetes ritirata. Gli approfondimenti sul ritiro si basano sulle chiamate API osservate alle API ritirate da user agent, non sulla configurazione degli oggetti Kubernetes.

Aggiorna i cluster interessati dai ritiri

Per eseguire l'upgrade dei cluster interessati dai ritiri, segui questi passaggi:

  1. Controlla quali user agent utilizzano le API ritirate nell'approfondimento sul ritiro o nei log.
  2. Aggiorna gli user agent che utilizzano le API ritirate in modo che utilizzino le versioni API supportate.
  3. Aggiorna all'ultima versione qualsiasi software di terze parti che chiama API ritirate.
  4. Esegui l'upgrade di un cluster di test e testa l'applicazione in un ambiente di test prima di eseguire l'upgrade del cluster di produzione per ridurre il rischio di interruzioni quando le API ritirate non sono più disponibili.
  5. Dopo aver aggiornato tutti gli user agent, GKE attende 30 giorni senza osservare l'utilizzo di API ritirate, quindi sblocca gli upgrade automatici. Gli upgrade automatici vengono eseguiti in base al programma delle pubblicazioni.
  6. Se non riesci ad aggiornare uno user agent interessato, esegui l'upgrade di un cluster di test separato per verificare se l'upgrade causa interruzioni. Se l'upgrade non causa interruzioni, puoi eseguire l'upgrade del cluster manualmente.

Risorse

Per saperne di più, consulta la documentazione OSS Kubernetes: