Manutenção e Atualizações

Esta página explica como manter uma implantação existente do AI Cockpit: Smart Engineering on-premise depois da instalação inicial.

As tarefas operacionais mais comuns são:

• aplicar uma nova versão do chart
• atualizar a versão das imagens da aplicação
• rotacionar certificados e configurações de ingress
• validar a saúde do storage, banco de dados e fila
• preparar backups antes de mudanças
• executar rollback quando um upgrade falha

Antes de aplicar mudanças

Antes de atualizar a implantação, confirme:

• o cluster está saudável
• PostgreSQL e Valkey estão operando normalmente
• o nome da release e o namespace atuais são conhecidos
• o arquivo values.yaml atual está disponível
• existe um backup recente do banco de dados

Comandos úteis:

kubectl get pods -n aic-modernization
kubectl get jobs -n aic-modernization
helm list -n aic-modernization
helm get values aic-modernization -n aic-modernization

Mantenha o arquivo de valores sob controle de versão

Não dependa apenas do comando original de instalação do AWS Marketplace.

Mantenha os valores efetivos da implantação em controle de versão para:

• revisar o que mudou entre releases
• reproduzir o ambiente
• comparar a configuração atual com a configuração alvo
• fazer rollback com mais segurança

Se necessário, exporte os valores atuais antes de um upgrade:

helm get values aic-modernization -n aic-modernization -o yaml > current-values.yaml

Atualizando a implantação

Quando uma nova versão do chart ou do produto estiver disponível, atualize a implantação com helm upgrade.

Exemplo:

helm upgrade aic-modernization \
  oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/compass-uol/ai-cockpit/smart-engineering-chart/aic-modernization \
  --version <new-chart-version> \
  --namespace aic-modernization \
  -f values.yaml

Para upgrades, a decisão mais importante é como o Helm deve tratar os valores armazenados na release atual.

Reutilizar os valores atuais

Use --reuse-values quando quiser manter os valores já armazenados na release atual e aplicar apenas as mudanças explícitas passadas no comando de upgrade.

Exemplo:

helm upgrade aic-modernization \
  oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/compass-uol/ai-cockpit/smart-engineering-chart/aic-modernization \
  --version <new-chart-version> \
  --namespace aic-modernization \
  --reuse-values

Isso é útil quando:

• a release já tem a configuração correta de runtime
• você quer alterar apenas a versão do chart
• você quer minimizar drift acidental de configuração durante o upgrade

Resetar para os valores padrão do chart

Use --reset-values quando quiser que o Helm ignore os valores armazenados na release e comece novamente a partir dos valores padrão do chart alvo, somados aos valores que você passar no comando.

Exemplo:

helm upgrade aic-modernization \
  oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/compass-uol/ai-cockpit/smart-engineering-chart/aic-modernization \
  --version <new-chart-version> \
  --namespace aic-modernization \
  --reset-values \
  -f values.yaml

Isso é útil quando:

• você quer que a release corresponda exatamente a um values.yaml revisado
• valores antigos armazenados podem não ser mais válidos
• você está padronizando o ambiente depois de várias mudanças manuais

Qual abordagem escolher

Como regra prática:

• use --reuse-values para upgrades pequenos e de baixo risco
• use --reset-values junto com um values.yaml revisado para mudanças controladas de configuração ou transições maiores de versão

O que acontece durante um upgrade

Durante helm upgrade, o chart pode atualizar:

• deployments da aplicação
• tags de imagem
• configuração de runtime
• configuração de ingress
• configuração do gateway
• configurações do PostgreSQL ou do Valkey

O chart também executa um job de migração após instalação e upgrade.

Depois do upgrade, valide:

kubectl get pods -n aic-modernization
kubectl get jobs -n aic-modernization
kubectl logs job/aic-modernization-migrate -n aic-modernization

Validar a aplicação após um upgrade

Depois de aplicar uma atualização, valide:

• health da API
• health do gateway, se habilitado
• acesso ao frontend
• fluxo de upload para S3
• acesso ao Bedrock
• execução de tarefas em background

Verificações recomendadas:

kubectl port-forward svc/aic-modernization-api -n aic-modernization 3000:3000
curl http://localhost:3000/health
curl http://localhost:3000/config/runtime

Se o gateway estiver habilitado:

kubectl port-forward svc/aic-modernization-gateway -n aic-modernization 8080:8080
curl http://localhost:8080/health

Backups e proteção de dados

Antes de alterar versões de chart, versões de imagem, configurações de banco de dados ou configurações de storage, faça backup do banco PostgreSQL.

No mínimo, mantenha:

• backups regulares do PostgreSQL
• procedimentos de snapshot de volume persistente, se sua plataforma de storage suportar
• uma cópia do values.yaml atual

Se você estiver usando PostgreSQL externo ou Valkey externo, siga a política de backup desses serviços gerenciados.

atenção

Não trate o Helm sozinho como estratégia de backup. O Helm armazena o estado da release, mas não substitui backups de banco de dados.

Rollback

Se um upgrade falhar e a nova versão não puder permanecer em produção, consulte o histórico da release:

helm history aic-modernization -n aic-modernization

Depois faça rollback para a revisão anterior conhecida como estável:

helm rollback aic-modernization <revision> -n aic-modernization

Depois do rollback, valide novamente os mesmos endpoints de health e runtime.

Se a falha incluiu uma migração parcial de banco, revise os logs da migração antes de tentar outro upgrade.

Tarefas comuns de manutenção

Rotação de certificados de ingress

Se o certificado TLS mudar:

• atualize o secret TLS Kubernetes usado pelo ingress
• confirme que o ingress ainda referencia o secret correto
• valide os hosts do frontend, da API e do gateway após a mudança

Atualizar origens permitidas

Se a origem do navegador mudar, atualize:

• runtime.commonEnv.ALLOWED_ORIGINS
• gateway.env.CORS_ALLOW_ORIGINS, se o gateway for exposto diretamente

Aplique a mudança com helm upgrade.

Alterar configurações de criptografia do S3

Se a política do bucket S3 alvo mudar:

• mantenha S3_UPLOAD_SERVER_SIDE_ENCRYPTION=AES256 para o caminho padrão com criptografia gerenciada pelo S3
• troque para aws:kms apenas se o bucket exigir KMS e a role IAM de runtime puder usar a chave KMS

Atualizar modelos do Bedrock

Se você mudar os modelos, atualize:

• bedrock.modelId
• bedrock.modelIdSmall

Depois valide que:

• os model IDs de destino estão disponíveis na conta do cliente
• a role IAM de runtime pode invocar esses modelos

Checklist operacional de troubleshooting

Se o sistema ficar indisponível após um update, verifique:

• loops de restart dos pods
• jobs de migração com falha
• configurações incorretas de ingress
• mudanças de service account ou IRSA
• mudanças de permissão no S3
• mudanças de acesso aos modelos do Bedrock
• mudanças no secret de conexão com o banco
• problemas de conectividade com o Valkey

Comandos úteis:

kubectl describe pod <pod-name> -n aic-modernization
kubectl logs deployment/aic-modernization-api -n aic-modernization --tail=200
kubectl logs deployment/aic-modernization-worker -n aic-modernization --tail=200
kubectl logs deployment/aic-modernization-gateway -n aic-modernization --tail=200

Rotina recomendada de manutenção

Uma rotina prática de manutenção é:

1. Exportar os valores atuais do Helm
2. Confirmar que os backups estão atualizados
3. Revisar a versão alvo do chart e as mudanças de configuração
4. Executar helm upgrade
5. Verificar o job de migração
6. Validar /health e /config/runtime
7. Executar uma pequena task fim a fim de documentação

Isso torna os upgrades mais previsíveis e simplifica o rollback quando algo muda de forma inesperada.