Introdução
As APIs do Kubernetes evoluem. Um manifesto que funcionava em um cluster antigo pode falhar em um cluster mais recente porque uma versão da API foi removida ou porque os campos foram alterados para uma estrutura diferente. No trabalho para o CKAD, isso geralmente aparece como uma tarefa prática de manutenção: ler o erro, identificar a API atual, atualizar o manifesto e provar que a nova versão é aceita.
Neste laboratório, você migrará um manifesto de Ingress antigo de networking.k8s.io/v1beta1 para networking.k8s.io/v1. Primeiro, você criará um Service para o Ingress referenciar, depois observará o manifesto antigo falhando, usará comandos de descoberta do kubectl para inspecionar a API atual, reescreverá o manifesto e aplicará o Ingress corrigido.
Preparar uma Referência de Service
Nesta etapa, você preparará um namespace limpo e um Service simples. Tanto o manifesto de Ingress antigo quanto o novo apontarão para este Service, para que a migração permaneça focada na estrutura da API em vez da prontidão dos Pods ou do roteamento de tráfego.
Comece em /home/labex/project:
mkdir -p /home/labex/project
cd /home/labex/project
Verifique se o servidor da API do Kubernetes está acessível. Se a VM acabou de iniciar e o nó ainda não está pronto, aguarde alguns segundos e execute o comando novamente.
kubectl get nodes --request-timeout=5s
A saída esperada inclui:
NAME STATUS ROLES AGE VERSION
labex-v135 Ready control-plane ... v1.35...
Crie um namespace chamado ckad-prep-api-migration e defina-o como o namespace atual:
kubectl create namespace ckad-prep-api-migration
kubectl config set-context --current --namespace=ckad-prep-api-migration
Crie um Service do tipo ClusterIP chamado app-web. A opção --tcp=80:80 significa que o Service escuta na porta 80 e encaminharia para a porta de destino 80 se houvesse Pods correspondentes. Para este laboratório de migração, o objeto Service em si é suficiente, pois você está validando os campos da API de Ingress, não o tráfego HTTP.
kubectl create service clusterip app-web --tcp=80:80
Confirme se o Service existe:
kubectl get service app-web
A saída esperada inclui:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
app-web ClusterIP ... <none> 80/TCP ...
Observar a Falha de um Manifesto Descontinuado
Nesta etapa, você criará um manifesto de Ingress antigo e deixará o cluster atual rejeitá-lo. Esta é uma prática útil, pois a primeira pista em uma tarefa de migração geralmente é a mensagem de erro do servidor da API.
Crie o arquivo old-ingress.yaml:
cat > old-ingress.yaml <<'EOF'
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: app-web
spec:
rules:
- host: app.example.local
http:
paths:
- path: /
backend:
serviceName: app-web
servicePort: 80
EOF
Leia o início do arquivo. O campo apiVersion informa ao Kubernetes qual grupo e versão da API devem processar este objeto.
sed -n '1,20p' old-ingress.yaml
A saída esperada inclui:
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
...
serviceName: app-web
servicePort: 80
Peça ao servidor da API para validar o manifesto sem criá-lo. O parâmetro --dry-run=server envia o objeto ao servidor da API para validação, enquanto || true mantém o tutorial em execução, já que essa falha é esperada.
kubectl apply --dry-run=server -f old-ingress.yaml || true
A saída esperada inclui um erro semelhante a:
error: resource mapping not found for name: "app-web" namespace: "" from "old-ingress.yaml": no matches for kind "Ingress" in version "networking.k8s.io/v1beta1"
A evidência importante é no matches for kind "Ingress" in version "networking.k8s.io/v1beta1". Isso significa que o cluster atual não oferece mais suporte a essa versão da API.
Descobrir a Estrutura Atual da API de Ingress
Nesta etapa, você inspecionará a API de Ingress atual antes de reescrever o arquivo. Esta é a parte que mantém o trabalho de migração disciplinado: não tente adivinhar os novos campos quando o cluster pode mostrar a estrutura aceita.
Liste o recurso Ingress disponível:
kubectl api-resources | grep -i '^ingresses'
A saída esperada inclui:
ingresses ing networking.k8s.io/v1 true Ingress
Use o kubectl explain para inspecionar o campo do serviço de backend atual. O caminho é longo porque o backend do Service está aninhado em spec.rules[].http.paths[].backend.service.
kubectl explain ingress.spec.rules.http.paths.backend.service --recursive | sed -n '1,80p'
A saída esperada inclui:
GROUP: networking.k8s.io
KIND: Ingress
VERSION: v1
FIELD: service <IngressServiceBackend>
...
name <string> -required-
port <ServiceBackendPort> -required-
Agora, crie o arquivo current-ingress.yaml migrado. O novo manifesto usa networking.k8s.io/v1, adiciona pathType e substitui serviceName e servicePort pelos campos aninhados service.name e service.port.number.
cat > current-ingress.yaml <<'EOF'
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app-web
spec:
rules:
- host: app.example.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-web
port:
number: 80
EOF
Valide o manifesto migrado com um dry run no lado do servidor:
kubectl apply --dry-run=server -f current-ingress.yaml
Saída esperada:
ingress.networking.k8s.io/app-web created (server dry run)
Aplicar e Inspecionar o Ingress Migrado
Nesta etapa, você criará o Ingress migrado e inspecionará os campos armazenados pelo Kubernetes. Aplicar o recurso é a prova final de que o manifesto agora corresponde ao servidor da API atual.
Aplique o manifesto migrado:
kubectl apply -f current-ingress.yaml
Saída esperada:
ingress.networking.k8s.io/app-web created
Liste o Ingress:
kubectl get ingress app-web
A saída esperada inclui:
NAME CLASS HOSTS ADDRESS PORTS AGE
app-web ... app.example.local ... 80 ...
Inspecione os campos do backend migrado diretamente do objeto armazenado:
kubectl get ingress app-web -o jsonpath='{.apiVersion}{" "}{.spec.rules[0].http.paths[0].pathType}{" "}{.spec.rules[0].http.paths[0].backend.service.name}{":"}{.spec.rules[0].http.paths[0].backend.service.port.number}{"\n"}'
Saída esperada:
networking.k8s.io/v1 Prefix app-web:80
Esta saída prova três coisas ao mesmo tempo: o objeto usa a versão atual da API, o caminho possui um pathType explícito e o backend usa a referência de Service aninhada exigida pelo networking.k8s.io/v1.
Resumo
Você praticou um fluxo de trabalho prático de migração de API. Você criou um manifesto de Ingress antigo networking.k8s.io/v1beta1, usou o dry run no lado do servidor para confirmar que o cluster atual o rejeita, inspecionou a API networking.k8s.io/v1 disponível, reescreveu os campos de backend com pathType e a referência de Service aninhada, e então aplicou e inspecionou o Ingress migrado.
