API Kubernetes 1.22 deprecate

Questa pagina spiega come preparare i cluster per gli upgrade alla versione 1.22 di GKE. 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 ritirate di Kubernetes.

API rimosse in 1.22

La maggior parte delle API deprecate nella versione 1.22 di Kubernetes sono ex API beta che sono state successivamente promosse da beta (v1beta1) a GA (v1). Le API GA forniscono garanzie di compatibilità più 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 è più disponibile a partire dalla versione 1.22.

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

  • Consulta la seguente tabella che descrive le modifiche significative nella versione dell'API GA:

    Campo Cambia
    webhooks[*].failurePolicy Valore predefinito modificato da Ignore a Fail.
    webhooks[*].matchPolicy Valore predefinito modificato da Exact a Equivalent.
    webhooks[*].timeoutSeconds Valore predefinito modificato da 30s a 10s.
    webhooks[*].sideEffects Il valore predefinito viene rimosso e il campo diventa 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 CustomResourceDefinition non è più pubblicata a partire dalla versione 1.22.

  • Esegui la migrazione dei manifest e dei client API in modo che utilizzino la versione dell'API apiextensions.k8s.io/v1.

  • Consulta la seguente tabella che descrive le modifiche significative nella versione dell'API GA:

    Campo Cambia
    spec.scope Non è più impostato come predefinito Namespaced. Il valore deve essere specificato esplicitamente.
    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 Spostamento in spec.conversion.webhook.clientConfig eseguito.
    spec.conversion.conversionReviewVersions Spostamento in spec.conversion.webhook.conversionReviewVersions eseguito.
    spec.versions[*].schema.openAPIV3Schema Ora obbligatorio quando si creano oggetti CustomResourceDefinition v1 e deve essere un 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 Negli elementi additionalPrinterColumns, il campo JSONPath è stato rinominato in jsonPath.

APIService

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

TokenReview

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

Risorse di SubjectAccessReview

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

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

  • Consulta la seguente tabella che descrive le modifiche significative nella versione dell'API GA:

    Campo Cambia
    spec.group Rinominato in spec.groups.

CertificateSigningRequest

La versione beta dell'API CertificateSigningRequest 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 certificates.k8s.io/v1.

  • Consulta la seguente tabella che descrive le modifiche significative 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 Per i client API che richiedono certificati, questo campo è obbligatorio. Questo campo non può contenere valori duplicati e deve contenere solo utilizzi noti.
    status.conditions Per i client API che approvano o firmano i certificati, questo campo non può contenere tipi duplicati.
    status.conditions[*].status Per i client API che approvano o firmano i certificati, questo campo è ora obbligatorio.
    status.certificate Per i client API che approvano o firmano i certificati, questo campo deve essere con codifica PEM e contenere solo blocchi CERTIFICATE.

Affitto

La versione beta dell'API Lease non è più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API in modo che utilizzino la versione dell'API coordination.k8s.io/v1.

Ingress (disponibile fino alla versione 1.23 per i cluster creati con la versione 1.21 o precedente)

Le versioni beta dell'API (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 con la versione 1.22 o successive.

Tuttavia, per i cluster creati su GKE 1.21 o versioni precedenti e sottoposti a upgrade a 1.22 con la versione della patch 1.22.7-gke.300 o successive, puoi comunque utilizzare le versioni beta dell'API fino a quando non viene eseguito l'upgrade del cluster alla versione 1.23. Si tratta di un'eccezione una tantum per i cluster meno recenti che ti offre più tempo per eseguire la migrazione dei cluster dall'utilizzo di queste versioni dell'API che verranno rimosse da Kubernetes open source nella versione 1.22.

Tutti i cluster che eseguono GKE versione 1.23 e successive non supporteranno più le API beta Ingress deprecate. I manifest che utilizzano queste versioni dell'API non possono più essere applicati. Gli oggetti precedentemente mantenuti in memoria 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 in modo che utilizzino la versione dell'API networking.k8s.io/v1.

  • Consulta la seguente tabella che descrive le modifiche significative nella versione dell'API GA:

    Campo Cambia
    spec.backend Rinominato in spec.defaultBackend.
    backend serviceName Rinominato in service.name.
    servicePort I campi servicePort di backend numerici vengono rinominati in service.port.number. I campi servicePort di backend di stringa 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 non definito di v1beta1, 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 l'osservabilità di Google Cloud abilitata 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 IngressClass non è 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 è più disponibile a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API in modo che utilizzino la versione dell'API rbac.authorization.k8s.io/v1.

PriorityClass

La versione beta dell'API PriorityClass non è più pubblicata a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API in modo che utilizzino la versione dell'API scheduling.k8s.io/v1.

Risorse di archiviazione

La versione beta dell'API di CSIDriver, CSINode, StorageClass e VolumeAttachment non è più disponibile a partire dalla versione 1.22. Esegui la migrazione dei manifest e dei client API in modo che utilizzino la versione dell'API storage.k8s.io/v1.

Trovare i cluster che utilizzano API obsolete

Puoi scoprire quali cluster utilizzano API ritirate dagli approfondimenti sul ritiro. Gli approfondimenti sulla ritiro forniscono anche informazioni, ad esempio su quali client API chiamano le API ritirate nel tuo cluster.

Puoi anche utilizzare gli audit log per trovare i client che effettuano chiamate alle API ritirate.

Individuare i client API che eseguono chiamate di scrittura ad API ritirate

Per i cluster in cui è attivata l'osservabilità di Google Cloud, puoi utilizzare la seguente query del log di controllo delle attività amministrative per mostrare l'utilizzo di API ritirate da agenti utente 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 minore in cui l'API obsoleta è stata rimossa, 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 agenti utente che eseguono chiamate di scrittura alle API ritirate.

Individuare i client API che effettuano chiamate di lettura ad API ritirate

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 i log di controllo dell'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.

Eseguire l'upgrade dei componenti di terze parti

Gli approfondimenti sul ritiro potrebbero mostrare risultati per gli agenti di terze parti che effettuano chiamate alle API ritirate nel tuo cluster.

Per risolvere questi problemi, prova i seguenti passaggi:

  1. Rivolgiti al fornitore di software di terze parti per una versione aggiornata.
  2. Esegui l'upgrade del software di terze parti alla versione più recente. Se non puoi eseguire l'upgrade del software, devi verificare se l'upgrade di GKE alla versione con le API ritirate potrebbe interrompere il 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 all'upgrade alla versione 1.22

Non è necessario eliminare e ricreare gli oggetti API. Tutti gli oggetti API esistenti memorizzati 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 delle API deprecate di Kubernetes.

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

Aggiorna i cluster interessati dal ritiro

Per eseguire l'upgrade dei cluster interessati dal ritiro, svolgi i seguenti passaggi:

  1. Controlla quali user agent utilizzano le API ritirate nella spiegazione del ritiro o nei log.
  2. Aggiorna gli user agent che utilizzano le API ritirate in modo che utilizzino le versioni supportate.
  3. Aggiorna il software di terze parti che chiama le API ritirate alle versioni più recenti.
  4. Esegui l'upgrade di un cluster di test e testa la tua 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 agenti utente, GKE attende 30 giorni senza rilevare l'utilizzo di API ritirate, quindi sblocca gli upgrade automatici. Gli upgrade automatici vengono eseguiti in base alla pianificazione dei rilasci.
  6. Se non riesci ad aggiornare uno user agent interessato, esegui l'upgrade di un cluster di test distinto per verificare se l'upgrade causa interruzioni. Se l'upgrade non causa interruzione del servizio, puoi eseguire manualmente l'upgrade del cluster.

Risorse

Puoi trovare ulteriori informazioni nella documentazione di Kubernetes OSS: