Skip to content

Upgrade do OKE (Kubernetes)

Guia para atualizar a versão do Kubernetes nos clusters OKE.

Arquitetura dos Clusters

Cada ambiente tem sua configuração em config/{env}/oke/:

Arquivo Conteúdo
cluster.hcl Versão K8s do control plane, networking, CNI
node-pools.hcl Node pools: shape, tamanho, autoscaling, versão K8s

Configuração Atual

Parâmetro HML NOX
Kubernetes v1.34.1 v1.34.1
CNI Flannel Flannel
Tipo cluster Enhanced Enhanced
Workers OCPUs 4 8
Workers Memória 32 GB 48 GB
Pool Size 3 (min 3, max 5) 4 (min 4, max 8)
Autoscaler Pool 1 node, 2 OCPU, 32 GB 1 node, 2 OCPU, 32 GB

Processo de Upgrade

O upgrade é declarativo — basta alterar a versão nos arquivos de configuração e aplicar.

Ordem obrigatória: control plane ANTES dos node pools

A Kubernetes version-skew policy proíbe que o kubelet (workers) seja mais novo que o kube-apiserver (control plane). No OKE:

  • Control plane = kube-apiserver gerenciado pela OCI
  • Node pools = kubelet gerenciado pelo usuário

Atualizar ambos no mesmo PR é arriscado: se o Terraform aplicar os node pools antes do control plane concluir, os workers ficarão com versão mais nova que o apiserver, violando a policy.

O kubelet pode ficar até 3 minor versions abaixo do apiserver — não é necessário atualizar tudo de uma vez (ex: apiserver v1.35, kubelet v1.32 é válido).

PR 1: Atualizar Control Plane

Editar somente cluster.hcl em config/{env}/oke/:

cluster.hcl — Control plane: hcl kubernetes_version = "v1.35.0" # Nova versão

bash git checkout -b upgrade/oke-{env}-cp-v1.35.0 git add config/{env}/oke/cluster.hcl git commit -m "chore: upgrade OKE {env} control plane to v1.35.0" git push

O workflow preview.yml gera um plan no PR. Após aprovação e merge, a OCI atualiza os master nodes automaticamente.

Aguardar Conclusão do Control Plane

Antes de abrir o PR 2, confirme que o control plane está na nova versão:

```bash

Verificar versão do kube-apiserver (deve mostrar v1.35.x)

kubectl version --short ```

Ou no OCI Console: Clusters > selecionar cluster > aba Cluster Details — aguardar status Active e versão atualizada (~10–20 min).

Os workers continuam funcionando

Durante o upgrade do control plane, os node pools permanecem na versão anterior e os pods continuam rodando normalmente.

PR 2: Atualizar Node Pools

Após confirmar que o control plane está na nova versão, editar somente node-pools.hcl em config/{env}/oke/:

node-pools.hcl — Node pools: hcl kubernetes_version = "v1.35.0" # Igual ao control plane

bash git checkout -b upgrade/oke-{env}-nodes-v1.35.0 git add config/{env}/oke/node-pools.hcl git commit -m "chore: upgrade OKE {env} node pools to v1.35.0" git push

Após aprovação e merge, o deploy.yml inicia o node cycling automático.

Node Cycling

O node cycling está configurado em todos os pools:

hcl node_cycling_enabled = true node_cycling_max_surge = 1 # Adiciona 1 novo nó antes de remover node_cycling_max_unavailable = 1 # Máximo 1 nó indisponível

Fluxo do cycling:

  1. OKE cria um novo nó com a nova versão K8s
  2. Aguarda o nó ficar Ready
  3. Faz drain do nó antigo (eviction grace: 300s)
  4. Remove o nó antigo
  5. Repete para o próximo nó

Zero downtime

Com max_surge=1 e pod disruption budgets configurados, o upgrade é feito sem downtime para as aplicações.

Ordem de Upgrade

Recomendação para upgrades de versão:

  1. TOOLS — Cluster de ferramentas (ArgoCD, Vault, SonarQube)
  2. HML — Validar em homologação
  3. NOX — Produção por último
flowchart LR
    T[TOOLS] -->|Validar| H[HML]
    H -->|Validar apps| N[NOX]

Verificação Pós-Upgrade

```bash

Verificar versão do cluster

kubectl version

Verificar nós

kubectl get nodes -o wide

Verificar se todos os pods estão running

kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

Verificar componentes do cluster

kubectl get componentstatuses ```

Componentes Complementares (OKE Extras)

Após upgrade do K8s, verifique compatibilidade dos add-ons em config/{env}/oke-extras/config.hcl:

Componente Config Verificar
Cert-Manager version Compatibilidade com nova versão K8s
Ingress NGINX version Compatibilidade com API changes
Kyverno version Policies podem quebrar com novas APIs
External DNS version —
Gateway API version CRDs podem precisar de update
Cluster Autoscaler version Compatibilidade com API do node pool (HML/NOX)

Atualização separada

Os extras são atualizados independentemente do K8s. Altere as versões nos config.hcl respectivos e faça um PR separado.