APIs obsoletas do Kubernetes 1.22

Nesta página, explicamos como preparar clusters para upgrades para a versão 1.22 do GKE. É possível encontrar clientes de API fazendo chamadas para APIs descontinuadas removidas na versão 1.22 e atualizá-los para usar as APIs do GA. Para informações mais detalhadas, consulte o Guia de migração da API descontinuada do Kubernetes.

APIs removidas na versão 1.22

A maioria das APIs obsoletas na versão 1.22 do Kubernetes são APIs Beta anteriores que passaram da versão Beta (v1beta1) para disponibilidade geral (v1). As APIs do GA fornecem garantias de compatibilidade de longo prazo e precisam ser usadas no lugar das APIs Beta obsoletas.

Todos os objetos existentes podem interagir com as APIs do GA.

Recursos de webhook

A versão Beta da API de MutatingWebhookConfiguration e ValidatingWebhookConfiguration não é mais veiculada a partir da versão 1.22.

  • Migre manifestos e clientes de API para usar a versão da API admissionregistration.k8s.io/v1.

  • Consulte a tabela a seguir que descreve as principais mudanças na versão da API GA:

    Campo Mudar
    webhooks[*].failurePolicy O padrão foi alterado de Ignore para Fail.
    webhooks[*].matchPolicy O padrão foi alterado de Exact para Equivalent.
    webhooks[*].timeoutSeconds O padrão foi alterado de 30s para 10s.
    webhooks[*].sideEffects O valor padrão é removido e o campo agora é obrigatório. Somente None e NoneOnDryRun são permitidos.
    webhooks[*].admissionReviewVersions O valor padrão foi removido e o campo agora é obrigatório. As versões compatíveis para AdmissionReview são v1 e v1beta1.
    webhooks[*].name Precisa ser exclusivo na lista para objetos criados com admissionregistration.k8s.io/v1.

CustomResourceDefinition

A versão Beta da API do CustomResourceDefinition não é mais veiculada a partir da versão 1.22.

  • Migrar manifestos e clientes de API para usar a versão da API apiextensions.k8s.io/v1

  • Consulte a tabela a seguir que descreve as principais mudanças na versão da API GA:

    Campo Mudar
    spec.scope O padrão não é mais Namespaced. O valor precisa ser explicitamente especificado.
    spec.version Removida. Use spec.versions.
    spec.validation Removida. Use spec.versions[*].schema.
    spec.subresources Removida. Use spec.versions[*].subresources.
    spec.additionalPrinterColumns Removida. Use spec.versions[*].additionalPrinterColumns.
    spec.conversion.webhookClientConfig Movida para spec.conversion.webhook.clientConfig.
    spec.conversion.conversionReviewVersions Movida para spec.conversion.webhook.conversionReviewVersions.
    spec.versions[*].schema.openAPIV3Schema Agora, é necessário ao criar objetos CustomResourceDefinition v1 e precisa ser um esquema estrutural.
    spec.preserveUnknownFields O valor true não é permitido ao criar objetos de v1 CustomResourceDefinition. O valor precisa ser especificado nas definições do esquema como x-kubernetes-preserve-unknown-fields: true.
    additionalPrinterColumns Em additionalPrinterColumns itens, o campo JSONPath foi renomeado para jsonPath.

APIService

A versão Beta da API APIService não é mais exibida a partir da versão 1.22. Migre manifestos e clientes de API para usar a versão da API apiregistration.k8s.io/v1.

TokenReview

A versão Beta da API TokenReview não é mais exibida a partir da versão 1.22. Migre manifestos e clientes de API para usar a versão da API authentication.k8s.io/v1.

Recursos SubjectAccessReview

A versão Beta da API de LocalSubjectAccessReview, SelfSubjectAccessReview e SubjectAccessReview não é mais veiculada a partir da versão 1.22.

  • Migre manifestos e clientes da API para usar a versão da API authorization.k8s.io/v1.

  • Consulte a tabela a seguir que descreve as principais mudanças na versão da API GA:

    Campo Mudar
    spec.group Renomeada como spec.groups.

CertificateSigningRequest

A versão Beta da API do CertificateSigningRequest não é mais veiculada a partir da versão 1.22.

  • Migre manifestos e clientes de API para usar a versão da API certificates.k8s.io/v1.

  • Consulte a tabela a seguir que descreve as principais mudanças na versão da API GA:

    Campo Mudar
    spec.signerName Para clientes de API que solicitam certificados, este campo é obrigatório (consulte signatários do Kubernetes conhecidos), e as solicitações para kubernetes.io/legacy-unknown não podem ser criadas por meio da API certificates.k8s.io/v1. de dados.
    spec.usages Para clientes de API que solicitam certificados, esse campo é obrigatório. Este campo não pode conter valores duplicados e só pode conter usos conhecidos.
    status.conditions Para clientes de API que aprovam ou assinam certificados, esse campo não pode conter tipos duplicados.
    status.conditions[*].status Para clientes de API que aprovam ou assinam certificados, esse campo agora é obrigatório.
    status.certificate Para clientes de API que aprovam ou assinam certificados, esse campo precisa ser codificado em PEM e conter apenas blocos CERTIFICATE.

Lease

A versão Beta da API do Lease não é mais veiculada a partir da versão 1.22. Migre manifestos e clientes de API para usar a versão da API coordination.k8s.io/v1.

Ingress (disponível até 1.23 para clusters criados na versão 1.21 ou anterior)

As versões Beta da API (extensions/v1beta1 e networking.k8s.io/v1beta1) de Ingress não serão mais veiculadas para clusters do GKE que executam a versão 1.22 ou posterior se o cluster tiver sido criado na versão 1.22 ou posterior.

No entanto, para clusters criados no GKE versão 1.21 ou anterior e atualizado para 1.22 na versão de patch 1.22.7-gke.300 ou posterior, ainda é possível usar as versões Beta da API até que o cluster seja atualizado para a versão 1,23. Essa é uma exceção única para clusters mais antigos. Com ela, você tem mais tempo de migrar os clusters para que não usem essas versões de API, que foram removidas do Kubernetes de código aberto, na versão 1.22.

Todos os clusters que executam o GKE versão 1.23 e posterior não veicularão mais as APIs Beta obsoletas Ingress. Os manifestos que usam essas versões de API não podem mais ser aplicados. Os objetos persistidos anteriormente permanecem funcionais e podem ser visualizados e atualizados usando as novas versões da API, antes e depois de fazer upgrade para a versão 1.23.

  • Migre manifestos e clientes de API para usar a versão da API networking.k8s.io/v1.

  • Consulte a tabela a seguir que descreve as principais mudanças na versão da API GA:

    Campo Mudar
    spec.backend Renomeada como spec.defaultBackend.
    back-end serviceName Renomeada como service.name.
    servicePort Os campos numéricos de back-end servicePort foram renomeados para service.port.number. Os campos servicePort de back-end de string foram renomeados como service.port.name.
    pathType Agora, é necessário para cada caminho especificado. O valor pode ser: Prefix, Exact ou ImplementationSpecific. Para corresponder ao comportamento v1beta1 indefinido, use ImplementationSpecific.

Os manifestos a seguir descrevem a mesma Entrada em v1 e v1beta1:

Manifesto 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

Manifesto 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

É possível usar a consulta a seguir para clusters com a observabilidade do Google Cloud ativada para identificar clientes que acessam as APIs v1beta1 do 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

A versão Beta da API IngressClass não é mais exibida a partir da versão 1.22. Migre manifestos e clientes de API para usar a versão da API networking.k8s.io/v1

Recursos do RBAC

A versão Beta da API de ClusterRole, ClusterRoleBinding, Role e RoleBinding não é mais veiculada a partir da versão 1.22. Migre manifestos e clientes de API para usar a versão rbac.authorization.k8s.io/v1 da API.

PriorityClass

A versão Beta da API do PriorityClass não é mais veiculada a partir da versão 1.22. Migre manifestos e clientes da API para usar a versão da API scheduling.k8s.io/v1.

Recursos de armazenamento

A versão Beta da API CSIDriver, CSINode, StorageClass e VolumeAttachment não é mais veiculada a partir da versão 1.22. Migre manifestos e clientes de API para usar a versão da API storage.k8s.io/v1.

Encontrar clssters usando APIs descontinuadas

Para saber quais clusters estão usando APIs descontinuadas, acesse os insights de descontinuação. Os insights de descontinuação também fornecem informações como quais clientes de API estão chamando as APIs descontinuadas no cluster.

Também é possível usar registros de auditoria para descobrir quais clientes estão fazendo chamadas para APIs descontinuadas.

Localizar clientes de API que fazem chamadas de gravação para APIs descontinuadas

Para clusters com a observabilidade do Google Cloud ativada, é possível usar a consulta do registro de auditoria da atividade do administrador a seguir para mostrar o uso de APIs descontinuadas por user agents que não são gerenciados pelo 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:")

Substitua DEPRECATED_API_MINOR_VERSION pela versão secundária em que a API descontinuada foi removida, por exemplo, 1.22.

Os registros de auditoria de atividades do administrador são ativados automaticamente para clusters do GKE. Com essa consulta, os registros mostram os user agents que fazem chamadas de gravação para as APIs descontinuadas.

Localizar clientes de API que fazem chamadas de leitura para APIs descontinuadas

Por padrão, os registros de auditoria mostram apenas chamadas de gravação para as APIs descontinuadas. Para mostrar também chamadas de leitura para APIs descontinuadas, configure os registros de auditoria de acesso a dados.

Siga as instruções para configurar os registros de auditoria de acesso a dados com o console do Google Cloud. No console do Google Cloud, selecione a API Kubernetes Engine. Na guia "Tipos de registro" no painel de informações, selecione Admin Read e Data Read.

Com esses registros ativados, agora é possível usar a consulta original para ver chamadas de leitura e de gravação para as APIs descontinuadas.

Como fazer upgrade de componentes de terceiros

Os insights de descontinuação podem exibir resultados para agentes de terceiros que fazem chamadas para APIs descontinuadas no cluster.

Para resolver esses insights, siga estas etapas:

  1. Verifique com seu provedor de software de terceiros se há uma versão atualizada.
  2. Atualize o software de terceiros para a versão mais recente. Se não for possível fazer upgrade do software, teste se o upgrade do GKE para a versão em que as APIs descontinuadas foram removidas interrompe o serviço.

Recomendamos que você realize esse upgrade e o upgrade da versão do GKE em um cluster de preparo para monitorar interrupções antes de fazer upgrade dos clusters de produção.

Como preparar o upgrade para a versão 1.22

Não é necessário excluir nem recriar qualquer um dos objetos da API. Todos os objetos permanentes atuais da API já podem ser lidos e atualizados usando as novas versões da API. No entanto, recomendamos que você migre seus clientes e manifestos antes de fazer o upgrade para o Kubernetes 1.22. Saiba mais na seção "O que fazer" do Guia de migração da API obsoleta do Kubernetes.

É possível ver insights e recomendações de descontinuação de uso para determinar se o cluster está usando um recurso ou uma API do Kubernetes descontinuado. Os insights de descontinuação de uso se baseiam em chamadas de API observadas para APIs descontinuadas por user agents, e não na configuração dos objetos do Kubernetes.

Atualizar clusters afetados por descontinuação

Para fazer upgrade dos clusters afetados pelas descontinuações de uso, siga estas etapas:

  1. Verifique quais user agents usam as APIs descontinuadas nos registros de descontinuação ou nos registros.
  2. Atualize os user agents que usam as APIs descontinuadas para usar as versões compatíveis.
  3. Atualize qualquer software de terceiros que chame APIs descontinuadas para as versões mais recentes.
  4. Faça upgrade de um cluster de teste e teste o aplicativo em um ambiente de teste antes de fazer upgrade do cluster de produção. Isso reduz o risco de interrupções quando as APIs descontinuadas não estão mais disponíveis.
  5. Depois que você atualizar todos os user agents, o GKE aguardará até que ele não observe mais o uso de APIs descontinuadas por 30 dias e, em seguida, desbloqueará os upgrades automáticos. Os upgrades automáticos prosseguem de acordo com a programação de lançamentos.
  6. Se não for possível atualizar um user agent afetado, faça upgrade de um cluster de teste separado para verificar se isso causa interrupções. Se o upgrade não causar interrupções, faça upgrade do cluster manualmente.

Recursos

Há mais informações disponíveis na documentação do OSS Kubernetes: