API obsoletas de Kubernetes 1.22

En esta página se explica cómo preparar los clústeres para actualizar a la versión 1.22 de GKE. Puede encontrar clientes de API que hagan llamadas a APIs obsoletas eliminadas en la versión 1.22 y actualizar esos clientes para que usen las APIs de GA. Para obtener información más detallada, consulta la guía de migración de APIs obsoletas de Kubernetes.

APIs retiradas en la versión 1.22

La mayoría de las APIs obsoletas de la versión 1.22 de Kubernetes son antiguas APIs beta que han pasado de la fase beta (v1beta1) a la de disponibilidad general (v1). Las APIs de disponibilidad general ofrecen garantías de compatibilidad a largo plazo y deben usarse en lugar de las APIs beta obsoletas.

Se puede interactuar con todos los objetos mediante las APIs de GA.

Recursos de webhook

La versión beta de la API de MutatingWebhookConfiguration y ValidatingWebhookConfiguration ya no se ofrece desde la versión 1.22.

  • Migra los manifiestos y los clientes de la API para que usen la versión admissionregistration.k8s.io/v1 de la API.

  • En la siguiente tabla se describen los cambios más importantes de la versión de la API de GA:

    Campo Cambiar
    webhooks[*].failurePolicy El valor predeterminado ha cambiado de Ignore a Fail.
    webhooks[*].matchPolicy El valor predeterminado ha cambiado de Exact a Equivalent.
    webhooks[*].timeoutSeconds El valor predeterminado ha cambiado de 30s a 10s.
    webhooks[*].sideEffects Se ha eliminado el valor predeterminado y ahora el campo es obligatorio. Solo se permiten None y NoneOnDryRun.
    webhooks[*].admissionReviewVersions Se ha quitado el valor predeterminado y ahora el campo es obligatorio (las versiones compatibles de AdmissionReview son v1 y v1beta1).
    webhooks[*].name Debe ser único en la lista de objetos creados mediante admissionregistration.k8s.io/v1.

CustomResourceDefinition

La versión beta de la API de CustomResourceDefinition ya no se ofrece desde la versión 1.22.

  • Migra los manifiestos y los clientes de la API para que usen la versión apiextensions.k8s.io/v1 de la API.

  • En la siguiente tabla se describen los cambios más importantes de la versión de la API de GA:

    Campo Cambiar
    spec.scope Ya no se utiliza Namespaced de forma predeterminada. El valor debe especificarse explícitamente.
    spec.version Eliminado. En su lugar, usa spec.versions.
    spec.validation Eliminado. En su lugar, usa spec.versions[*].schema.
    spec.subresources Eliminado. En su lugar, usa spec.versions[*].subresources.
    spec.additionalPrinterColumns Eliminado. En su lugar, usa spec.versions[*].additionalPrinterColumns.
    spec.conversion.webhookClientConfig Movido a spec.conversion.webhook.clientConfig.
    spec.conversion.conversionReviewVersions Movido a spec.conversion.webhook.conversionReviewVersions.
    spec.versions[*].schema.openAPIV3Schema Ahora es obligatorio al crear objetos CustomResourceDefinition de la versión 1 y debe ser un esquema estructural.
    spec.preserveUnknownFields El valor true no se permite al crear objetos CustomResourceDefinition de la versión 1. El valor debe especificarse en las definiciones de esquema como x-kubernetes-preserve-unknown-fields: true.
    additionalPrinterColumns En los elementos additionalPrinterColumns, se ha cambiado el nombre del campo JSONPath a jsonPath.

APIService

La versión beta de la API de APIService ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de API para que usen la versión apiregistration.k8s.io/v1 de la API.

TokenReview

La versión beta de la API de TokenReview ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de API para que usen la versión authentication.k8s.io/v1 de la API.

Recursos SubjectAccessReview

La versión beta de la API de LocalSubjectAccessReview, SelfSubjectAccessReview y SubjectAccessReview ya no se ofrece desde la versión 1.22.

  • Migra los manifiestos y los clientes de la API para que usen la versión authorization.k8s.io/v1 de la API.

  • En la siguiente tabla se describen los cambios más importantes de la versión de la API de GA:

    Campo Cambiar
    spec.group Se ha cambiado el nombre a spec.groups.

CertificateSigningRequest

La versión beta de la API de CertificateSigningRequest ya no se ofrece desde la versión 1.22.

  • Migra los manifiestos y los clientes de la API para que usen la versión certificates.k8s.io/v1 de la API.

  • En la siguiente tabla se describen los cambios más importantes de la versión de la API de GA:

    Campo Cambiar
    spec.signerName Este campo es obligatorio para los clientes de la API que soliciten certificados (consulta los signatarios de Kubernetes conocidos), y no se pueden crear solicitudes de kubernetes.io/legacy-unknown mediante la API certificates.k8s.io/v1.
    spec.usages Este campo es obligatorio para los clientes de la API que solicitan certificados. Este campo no puede contener valores duplicados y solo debe contener usos conocidos.
    status.conditions En el caso de los clientes de API que aprueban o firman certificados, este campo no puede contener tipos duplicados.
    status.conditions[*].status Este campo ahora es obligatorio para los clientes de la API que aprueban o firman certificados.
    status.certificate En el caso de los clientes de API que aprueban o firman certificados, este campo debe estar codificado en PEM y contener solo bloques CERTIFICATE.

Arrendamiento

La versión beta de la API de Lease ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de la API para que usen la versión coordination.k8s.io/v1 de la API.

Ingress (disponible hasta la versión 1.23 para los clústeres creados con la versión 1.21 o una anterior)

Las versiones beta de la API (extensions/v1beta1 y networking.k8s.io/v1beta1) de Ingress ya no se ofrecen para los clústeres de GKE que ejecutan la versión 1.22 o posterior si el clúster se creó con la versión 1.22 o una posterior.

Sin embargo, en los clústeres creados en GKE 1.21 o versiones anteriores y actualizados a 1.22 en la versión de parche 1.22.7-gke.300 o posterior, puedes seguir usando las versiones beta de la API hasta que el clúster se actualice a la versión 1.23. Se trata de una excepción única para los clústeres antiguos, que te da más tiempo para migrar tus clústeres de estas versiones de la API, que se han retirado de Kubernetes de código abierto en la versión 1.22.

Los clústeres que ejecuten la versión 1.23 de GKE o una posterior dejarán de servir las APIs beta Ingress obsoletas. Los manifiestos que usen esas versiones de la API ya no se podrán aplicar. Los objetos que se hayan conservado anteriormente seguirán funcionando y se podrán ver y actualizar con las nuevas versiones de la API, tanto antes como después de actualizar a la versión 1.23.

  • Migra los manifiestos y los clientes de API para que usen la versión networking.k8s.io/v1 de la API.

  • En la siguiente tabla se describen los cambios más importantes de la versión de la API de GA:

    Campo Cambiar
    spec.backend Se ha cambiado el nombre a spec.defaultBackend.
    backend serviceName Se ha cambiado el nombre a service.name.
    servicePort Los campos numéricos de backend servicePort se han renombrado como service.port.number. Se ha cambiado el nombre de los campos de backend de cadena servicePort a service.port.name.
    pathType Ahora es obligatorio para cada ruta especificada. El valor puede ser Prefix, Exact o ImplementationSpecific. Para que coincida con el comportamiento indefinido de v1beta1, usa ImplementationSpecific.

Los siguientes manifiestos describen el mismo Ingress en v1 y v1beta1:

Manifiesto de 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

Manifiesto de la versión 1

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

Puedes usar la siguiente consulta para identificar los clientes que acceden a las APIs de Ingress v1beta1 en los clústeres en los que Google Cloud Observability está habilitado:

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 versión beta de la API de IngressClass ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de la API para que usen la versión networking.k8s.io/v1 de la API.

Recursos de RBAC

La versión beta de la API de ClusterRole, ClusterRoleBinding, Role y RoleBinding ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de la API para que usen la versión rbac.authorization.k8s.io/v1 de la API.

PriorityClass

La versión beta de la API de PriorityClass ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de la API para que usen la versión scheduling.k8s.io/v1 de la API.

Recursos de almacenamiento

La versión beta de la API de CSIDriver, CSINode, StorageClass y VolumeAttachment ya no se ofrece desde la versión 1.22. Migra los manifiestos y los clientes de API para que usen la versión storage.k8s.io/v1 de la API.

Buscar clústeres que usen APIs obsoletas

Puedes consultar qué clústeres usan APIs obsoletas en Estadísticas de obsolescencia. Las estadísticas de las APIs obsoletas también proporcionan información, como qué clientes de API llaman a las APIs obsoletas de tu clúster.

También puedes usar los registros de auditoría para saber qué clientes están haciendo llamadas a APIs obsoletas.

Localizar clientes de API que hacen llamadas de escritura a APIs obsoletas

En los clústeres en los que Google Cloud Observability esté habilitado, puedes usar la siguiente consulta del registro de auditoría de actividad de administrador para mostrar el uso de APIs obsoletas por parte de agentes de usuario que no estén gestionados por 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:")

Sustituye DEPRECATED_API_MINOR_VERSION por la versión secundaria en la que se ha retirado la API obsoleta (por ejemplo, 1.22).

Los registros de auditoría de actividad de administración se habilitan automáticamente en los clústeres de GKE. Con esta consulta, los registros muestran agentes de usuario que hacen llamadas de escritura a las APIs obsoletas.

Localizar clientes de API que hagan llamadas de lectura a APIs obsoletas

De forma predeterminada, los registros de auditoría solo muestran las llamadas de escritura a las APIs obsoletas. Para mostrar también las llamadas de lectura a APIs obsoletas, configura los registros de auditoría de acceso a datos.

Sigue las instrucciones para configurar registros de auditoría de acceso a datos con la consola Google Cloud . En la Google Cloud consola, selecciona la API de Kubernetes Engine. En la pestaña Tipos de registro del panel de información, selecciona Admin Read y Data Read.

Con estos registros habilitados, ahora puede usar la consulta original para ver tanto las llamadas de lectura como las de escritura a las APIs obsoletas.

Actualizar componentes de terceros

Estadísticas de obsolescencia: puede que se muestren resultados de agentes de terceros que hagan llamadas a APIs obsoletas en tu clúster.

Para resolver estos problemas, sigue estos pasos:

  1. Ponte en contacto con el proveedor del software de terceros para obtener una versión actualizada.
  2. Actualiza el software de terceros a la versión más reciente. Si no puedes actualizar el software, debes probar si la actualización de GKE a la versión con las APIs obsoletas eliminadas afectaría a tu servicio.

Te recomendamos que realices esta actualización y la de la versión de GKE en un clúster de staging para monitorizar las interrupciones antes de actualizar tus clústeres de producción.

Prepararse para actualizar a la versión 1.22

No es necesario que elimines ni vuelvas a crear ninguno de tus objetos de API. Todos los objetos de API persistentes se pueden leer y actualizar con las nuevas versiones de la API. Sin embargo, te recomendamos que migres tus clientes y manifiestos antes de actualizar a Kubernetes 1.22. Consulta más información en la sección "Qué hacer" de la guía de migración de APIs obsoletas de Kubernetes.

Puedes consultar estadísticas y recomendaciones sobre las obsolescencias para determinar si tu clúster está usando una función o una API de Kubernetes obsoleta. Las estadísticas de obsolescencia se basan en las llamadas a APIs obsoletas que se han observado en los user-agents, no en la configuración de tus objetos de Kubernetes.

Actualizar clústeres afectados por las obsolescencias

Para actualizar los clústeres afectados por las obsolescencias, sigue estos pasos:

  1. Consulta qué user-agents usan las APIs obsoletas en la estadística de obsolescencia o en los registros.
  2. Actualiza los user-agents que usan las APIs obsoletas para que usen versiones de la API compatibles.
  3. Actualiza a las versiones más recientes el software de terceros que llame a APIs obsoletas.
  4. Actualiza un clúster de prueba y prueba tu aplicación en un entorno de pruebas antes de actualizar tu clúster de producción para reducir el riesgo de interrupciones cuando las APIs obsoletas ya no estén disponibles.
  5. Una vez que hayas actualizado todos los user-agents, GKE esperará hasta que no se haya observado el uso de APIs obsoletas durante 30 días y, a continuación, desbloqueará las actualizaciones automáticas. Las actualizaciones automáticas se realizan según la programación de lanzamientos.
  6. Si no puedes actualizar un user-agent afectado, actualiza un clúster de prueba independiente para comprobar si la actualización provoca interrupciones. Si la actualización no provoca interrupciones, puedes actualizar tu clúster manualmente.

Recursos

Puede consultar más información en la documentación de Kubernetes de software libre: