API obsoletas de Kubernetes 1.22

En esta página, se explica cómo preparar clústeres para las actualizaciones a la versión 1.22 de GKE. Puedes encontrar clientes de API que realizan llamadas a APIs obsoletas eliminadas en la versión 1.22 y actualizar esos clientes para usar las APIs de DG. Para obtener información más detallada, consulta la Guía de migración de la API obsoleta de Kubernetes.

APIs eliminadas en la versión 1.22

La mayoría de las API obsoletas de la versión 1.22 de Kubernetes son antiguas API beta que pasaron de beta (v1beta1) a DG (v1). Las API DG proporcionan garantías de compatibilidad a largo plazo y deben usarse en lugar de las API beta obsoletas.

Se puede interactuar con todos los objetos existentes mediante las API DG.

Recursos de webhook

La versión beta de la API de MutatingWebhookConfiguration y ValidatingWebhookConfiguration ya no se entrega a partir de la versión 1.22.

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

  • Consulta la siguiente tabla que describe los cambios notables en la versión de la API DG:

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

CustomResourceDefinition

La versión beta de la API de CustomResourceDefinition ya no se entrega a partir de la versión 1.22.

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

  • Consulta la siguiente tabla que describe los cambios notables en la versión de la API DG:

    Campo Cambiar
    spec.scope Ya no está predeterminado en Namespaced. El valor se debe especificar de forma explícita.
    spec.version Se quitó. Utiliza spec.versions en lugar de esta función.
    spec.validation Se quitó. Utiliza spec.versions[*].schema en lugar de esta función.
    spec.subresources Se quitó. Utiliza spec.versions[*].subresources en lugar de esta función.
    spec.additionalPrinterColumns Se quitó. Utiliza spec.versions[*].additionalPrinterColumns en lugar de esta función.
    spec.conversion.webhookClientConfig Se movió a spec.conversion.webhook.clientConfig.
    spec.conversion.conversionReviewVersions Se movió a spec.conversion.webhook.conversionReviewVersions.
    spec.versions[*].schema.openAPIV3Schema Ahora es necesario cuando se crean objetos CustomResourceDefinition v1 y debe ser un esquema estructural.
    spec.preserveUnknownFields El valor true no está permitido cuando se crean objetos CustomResourceDefinition v1. El valor debe especificarse dentro de las definiciones de esquema como x-kubernetes-preserve-unknown-fields: true.
    additionalPrinterColumns En los elementos additionalPrinterColumns, se cambió el nombre del campo JSONPath a jsonPath.

APIService

La versión beta de la API de APIService ya no se entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API apiregistration.k8s.io/v1.

TokenReview

La versión beta de la API de TokenReview ya no se entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API authentication.k8s.io/v1.

Recursos de SubjectAccessReview

La versión beta de la API de LocalSubjectAccessReview, SelfSubjectAccessReview y SubjectAccessReview ya no se entrega a partir de la versión 1.22.

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

  • Consulta la siguiente tabla que describe los cambios notables en la versión de la API DG:

    Campo Cambiar
    spec.group Se cambió el nombre a spec.groups.

CertificateSigningRequest

La versión beta de la API de CertificateSigningRequest ya no se entrega a partir de la versión 1.22.

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

  • Consulta la siguiente tabla que describe los cambios notables en la versión de la API DG:

    Campo Cambiar
    spec.signerName Para los clientes de API que soliciten certificados, este campo es obligatorio (consulta Firmantes conocidos de Kubernetes), y las solicitudes para kubernetes.io/legacy-unknown no pueden crearse a través de la API de certificates.k8s.io/v1.
    spec.usages Para los clientes de API que soliciten certificados, este campo es obligatorio. Este campo no puede contener valores duplicados y solo debe contener usos conocidos.
    status.conditions Para los clientes de API que aprueban o firman certificados, este campo no puede contener tipos duplicados.
    status.conditions[*].status Para los clientes de API que aprueban o firman certificados, este campo ahora es obligatorio.
    status.certificate Para los clientes de API que aprueban o firman certificados, este campo debe estar codificado con PEM y contener solo bloques CERTIFICATE.

Lease

La versión beta de la API de Lease ya no se entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API coordination.k8s.io/v1.

Ingress (disponible hasta la versión 1.23 para clústeres creados en la versión 1.21 o anteriores)

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

Sin embargo, para los clústeres creados en la versión 1.21 de GKE o una versión anterior, y actualizados a la versión 1.22 en la versión del parche 1.22.7-gke.300 o posterior, aún puedes usar las versiones beta de la API hasta que el clúster se actualice a la versión 1.23. Esta es una excepción única para los clústeres más antiguos a fin de que tengas más tiempo para migrar tus clústeres desde estas versiones de API, que se quitan de Kubernetes de código abierto en la versión 1.22.

Los clústeres que ejecuten la versión 1.23 de GKE y versiones posteriores ya no entregarán las API beta Ingress obsoletas. Los manifiestos que usan esas versiones de la API ya no se pueden aplicar. Los objetos persistentes anteriores permanecen funcionales y se pueden ver y actualizar mediante las nuevas versiones de la API, antes y después de actualizar a la versión 1.23.

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

  • Consulta la siguiente tabla que describe los cambios notables en la versión de la API DG:

    Campo Cambiar
    spec.backend Se cambió el nombre a spec.defaultBackend.
    backend serviceName Se cambió el nombre a service.name.
    servicePort A los nombres de los campos servicePort de backend numéricos se les cambia el nombre a service.port.number. A los nombres de los campos servicePort de backend de string se les cambia el nombre a service.port.name.
    pathType Ahora es necesario para cada ruta de acceso especificada. El valor puede ser Prefix, Exact o ImplementationSpecific. Para hacer coincidir el comportamiento v1beta1 no definido, usa ImplementationSpecific.

En los siguientes manifiestos, se describe el mismo Ingress en v1 y v1beta1:

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

Puedes usar la siguiente consulta para clústeres con la observabilidad de Google Cloud habilitada a fin de identificar a los clientes que acceden a las APIs v1beta1 de Ingress:

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 entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API networking.k8s.io/v1.

Recursos de RBAC

La versión beta de la API de ClusterRole, ClusterRoleBinding, Role y RoleBinding ya no se entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API rbac.authorization.k8s.io/v1.

PriorityClass

La versión beta de la API de PriorityClass ya no se entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API scheduling.k8s.io/v1.

Recursos de almacenamiento

La versión beta de la API de CSIDriver, CSINode, StorageClass y VolumeAttachment ya no se entrega a partir de la versión 1.22. Migra los manifiestos y los clientes de la API para usar la versión de la API storage.k8s.io/v1.

Busca clústeres con APIs obsoletas

Puedes encontrar los clústeres que usan las APIs obsoletas en las estadísticas de baja. Las estadísticas de baja también proporcionan información como qué clientes de API llaman a las API obsoletas en tu clúster.

También puedes usar los registros de auditoría para encontrar qué clientes realizan llamadas a las APIs obsoletas.

Ubica los clientes de API que realizan llamadas de escritura a las APIs obsoletas

Para los clústeres con Google Cloud Observability habilitada, puedes usar la siguiente consulta del Registro de actividad del administrador a fin de mostrar el uso de APIs obsoletas por parte de los usuarios-agentes que no son administrados 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:")

Reemplaza DEPRECATED_API_MINOR_VERSION por la versión secundaria en la que se quita la API obsoleta, por ejemplo, 1.22.

Los registros de auditoría de actividad del administrador se habilitan de forma automática para los clústeres de GKE. Con esta consulta, los registros muestran a los usuarios-agentes que realizan llamadas de escritura a las APIs obsoletas.

Ubica los clientes de API que realizan llamadas de lectura a las APIs obsoletas

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

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

Con estos registros habilitados, ahora puedes usar la consulta original para ver las llamadas de lectura y de escritura en las APIs obsoletas.

Actualiza componentes de terceros

Es posible que las estadísticas de baja muestren resultados para agentes de terceros que realizan llamadas a las APIs obsoletas en el clúster.

Para resolver estas estadísticas, prueba los siguientes pasos:

  1. Comunícate con tu proveedor de 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 actualizar GKE a la versión con las APIs obsoletas eliminadas interrumpiría tu servicio.

Recomendamos que realices esta actualización y la actualización de la versión de GKE en un clúster de etapa de pruebas para supervisar las interrupciones antes de actualizar los clústeres de producción.

Prepárate para actualizar a la versión 1.22

No es necesario que borres ni vuelvas a crear ningún objeto de API. Todos los objetos de la API persistentes existentes ya se pueden leer y actualizar mediante las nuevas versiones de API. Sin embargo, te recomendamos que migres a tus clientes y manifiestos antes de actualizar a Kubernetes 1.22. Obtén más información en la sección “Qué hacer” de la Guía de migración de las API obsoletas de Kubernetes.

Puedes ver estadísticas y recomendaciones de baja para determinar si tu clúster usa una función o una API de Kubernetes que está obsoleta. Las estadísticas de baja se basan en las llamadas observadas a las APIs obsoletas por parte de los usuarios-agentes, no la configuración de tus objetos de Kubernetes.

Actualiza los clústeres afectados por las bajas

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

  1. Verifica qué usuarios-agentes usan las APIs obsoletas en los registros o en la estadística de bajas.
  2. Actualiza los usuarios-agentes que usan las APIs obsoletas para que usen versiones compatibles de las APIs.
  3. Actualiza cualquier software de terceros que llame a las APIs obsoletas a las versiones más recientes.
  4. Actualiza un clúster de prueba y prueba tu aplicación en un entorno de pruebas antes de actualizar el clúster de producción para reducir el riesgo de interrupciones cuando las APIs obsoletas ya no estén disponibles.
  5. Después de actualizar todos los usuarios-agentes, GKE espera hasta que ya no haya observado el uso de las APIs obsoletas durante 30 días y, luego, desbloquea las actualizaciones automáticas. Las actualizaciones automáticas continúan según el programa de lanzamientos.
  6. Si no puedes actualizar un usuario-agente afectado, actualiza un clúster de prueba separado para verificar si la actualización causa interrupciones. Si la actualización no produce interrupciones, puedes actualizar el clúster de forma manual.

Recursos

Puedes encontrar más información en la documentación de Kubernetes de OSS: