Atualização via ArgoCD

Este guia descreve o processo de atualização dos componentes do TDP Kubernetes utilizando o ArgoCD como ferramenta de GitOps.
Com o ArgoCD, as atualizações são geridas de forma declarativa através dos manifests de Application armazenados no repositório Git.

dica

Com o padrão GitOps, a atualização consiste em editar os manifests no repositório Git — o ArgoCD deteta a alteração e aplica-a automaticamente ao cluster.

---

Preparo

Preparo da Atualização

Antes de alterar os manifests, verifique o estado atual do cluster.

Comandos

Verificar o Estado das Applications

Liste todas as Applications do TDP e os seus estados:

Terminal input

argocd app list

Figura 1 - Applications do TDP e os seus estados

O que validar:

• Todas as Applications devem estar com STATUS Synced
• Todas devem estar com HEALTH Healthy

Por que validar antes da atualização:

• Confirmar que o estado atual no cluster corresponde ao estado desejado no Git
• Garantir que não há erro de reconciliação pendente
• Evitar iniciar a atualização sobre uma Application já inconsistente ou degradada

Verificar os pods e a prontidão dos workloads

Terminal input

kubectl get pods -n <namespace>

Figura 2 - Verificar os Pods

Terminal input

kubectl get statefulset -n <namespace>

Figura 3 - Verificar os StatefulSets

Se a aplicação utilizar Deployment, valide também:

Terminal input

kubectl get deploy -n <namespace>

O que validar:

• Os pods estão com STATUS Running
• A coluna READY dos pods está completa, por exemplo 1/1
• Os StatefulSets ou Deployments da aplicação mostram todas as réplicas prontas, por exemplo 1/1, 2/2 ou 3/3

Por que validar antes da atualização:

• Garantir que a aplicação já está estável antes da mudança
• Evitar confundir falha anterior com falha causada pela atualização
• Reduzir o risco de indisponibilidade durante o processo

Verificar os Releases do Helm

Terminal input

helm list -n <namespace>

Figura 4 - Verificar os Releases do Helm

Confirme as versões instaladas e o estado deployed de cada release.

Vídeos

argocd app list

kubectl get pods

kubectl get statefulset

helm list

Atualização

Atualização dos Manifests de Application

A atualização via ArgoCD consiste em modificar os manifests de Application no repositório Git, alterando a versão do chart (targetRevision) para a nova versão desejada.

Comandos

Alterar a Versão do Chart

Edite o manifest da Application do componente que pretende atualizar. O campo targetRevision define a versão do Helm Chart utilizada. Exemplo para o PostgreSQL (componente base que costuma ser instalado primeiro):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-postgresql
  namespace: argocd
spec:
  project: default
  source:
    chart: tdp-postgresql
    repoURL: oci://registry.tecnisys.com.br/tdp
    targetRevision: "0.1.0"  # Altere para a nova versão desejada
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Figura 1 - Edição do Manifest

Alterar Valores de Configuração

Para atualizar valores de configuração juntamente com a versão, modifique o campo helm.values ou o ficheiro values.yaml referenciado. Exemplo para o PostgreSQL (recursos, armazenamento, etc.):

spec:
  source:
    chart: tdp-postgresql
    repoURL: oci://registry.tecnisys.com.br/tdp
    targetRevision: "0.1.0"
    helm:
      values: |
        primary:
          resources:
            requests:
              memory: 2Gi
              cpu: "1"
        persistence:
          size: 20Gi

Figura 2 - Edição do Manifest - configuração

Confirmar as Alterações no Git

Após editar os manifests, faça commit e push das alterações para o repositório Git:

Terminal input

git add apps/
git commit -m "chore: atualizar tdp-postgresql para nova versão"
git push origin main

Figura 3 - Confirmar alteração no Git

O ArgoCD detetará automaticamente as alterações no repositório e iniciará o processo de sincronização, de acordo com a estratégia de sync configurada.

Estratégias de Sincronização

Sincronização Automática

Com a sincronização automática ativada, o ArgoCD aplica as alterações detetadas no Git sem intervenção manual:

syncPolicy:
  automated:
    prune: true      # Remove recursos que já não existem no Git
    selfHeal: true   # Corrige desvios entre o estado real e o desejado

informação

A sincronização automática é recomendada para ambientes de desenvolvimento e staging. Em produção, considere a sincronização manual para maior controlo.

Sincronização Manual

Para atualizações em produção, desative a sincronização automática e realize o sync manualmente:

syncPolicy: {}  # Sem política automática

Terminal input

argocd app sync tdp-postgresql

Figura 4 - Sincronização manual

Ou clique no botão Sync da Application na interface web do ArgoCD.

Sync Waves

Para controlar a ordem de atualização dos componentes, utilize sync waves. Recursos com valores de wave menores são sincronizados primeiro:

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

Wave	Componentes
0	CRDs (tdp-argo-crds)
1	Infraestrutura (tdp-argo, tdp-postgresql)
2	Mensageria (tdp-kafka)
3	Armazenamento (tdp-hive-metastore, tdp-iceberg, tdp-ozone, tdp-deltalake)
4	Segurança (tdp-ranger)
5	Processamento (tdp-nifi, tdp-spark, tdp-trino, tdp-clickhouse)
6	Ferramentas (tdp-airflow, tdp-jupyter, tdp-superset, tdp-openmetadata, tdp-cloudbeaver)

Rollouts Progressivos

Dry Run

Simule a sincronização antes de aplicar para verificar o que será alterado:

Terminal input

argocd app sync tdp-postgresql --dry-run

Preview das Diferenças

Visualize as diferenças entre o estado atual do cluster e o estado desejado no Git:

Terminal input

argocd app diff tdp-postgresql

Sincronização Seletiva

Sincronize apenas recursos específicos de uma Application, em vez de todos de uma vez:

Terminal input

argocd app sync tdp-postgresql --resource apps:StatefulSet:tdp-postgresql

Vídeos

Editar manifest

git push

argocd app sync

Validação

Validação Pós-Atualização

Após aplicar as alterações no repositório Git, utilize os comandos abaixo para acompanhar o estado da sincronização.

Comandos

Verificar o Estado das Applications

Terminal input

argocd app list

Figura 1 - Applications do TDP e os seus estados

Estado de Sincronização	Descrição
Synced	O estado do cluster corresponde ao declarado no manifest
OutOfSync	Existem diferenças entre o manifest e o cluster
Unknown	O ArgoCD não conseguiu determinar o estado

Estado de Saúde	Descrição
Healthy	Todos os recursos da Application estão operacionais
Progressing	Os recursos estão a ser criados ou atualizados
Degraded	Um ou mais recursos apresentam problemas
Suspended	A sincronização está pausada

Verificar uma Application Específica

Terminal input

argocd app get tdp-postgresql

Figura 2 - Verificar a application postgresql

Para acompanhar o progresso em tempo real:

Terminal input

argocd app wait tdp-postgresql --sync

Figura 3 - Acompanhar o progresso em tempo real

Verificar a Saúde dos Recursos

Terminal input

argocd app wait tdp-postgresql --health

Figura 4 - Verificar a saúde dos recursos

Verificar os pods e a prontidão dos workloads

Terminal input

kubectl get pods -n <namespace>

Figura 5 - Verificar os Pods

Terminal input

kubectl get statefulset -n <namespace>

Figura 6 - Verificar os StatefulSets

Se a aplicação utilizar Deployment, valide também:

Terminal input

kubectl get deploy -n <namespace>

O que confirmar:

• Os pods estão com STATUS Running
• A coluna READY dos pods está completa, por exemplo 1/1
• Os StatefulSets ou Deployments da aplicação mostram todas as réplicas prontas, por exemplo 1/1, 2/2 ou 3/3

Verificar a Revisão do Helm

Confirme que a revisão do release foi incrementada com sucesso:

Terminal input

helm history <release> -n <namespace>

Figura 7 - Verificar a Revisão do Helm

Vídeos

argocd app list

argocd app get

argocd app wait --sync

argocd app wait --health

helm history

kubectl get pods

kubectl get statefulset

Resolução de Problemas

Resolução de Problemas

Comandos

Application em OutOfSync ou Degraded

Se uma Application apresenta estado OutOfSync ou Degraded:

1. Verifique os detalhes e erros da operação:

   Terminal input

   argocd app get tdp-postgresql --show-operation

2. Analise os logs do controller do ArgoCD:

   Terminal input

   kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller --tail=200

3. Tente sincronizar manualmente:

   Terminal input

   argocd app sync tdp-postgresql

Conflitos de Sincronização

Se existirem recursos modificados manualmente no cluster que conflituam com o Git:

Opção 1 — Forçar sincronização (sobrescreve o cluster com o Git):

Terminal input

argocd app sync tdp-postgresql --force

Opção 2 — Self-heal (deixa o ArgoCD corrigir automaticamente os desvios):

syncPolicy:
  automated:
    selfHeal: true

Retry Automático

Configure o retry automático para que o ArgoCD tente novamente em caso de falhas temporárias:

syncPolicy:
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

Reverter a Atualização

Se a atualização falhar e for necessário reverter, altere o targetRevision no manifest Git para a versão anterior e faça commit:

Terminal input

git revert HEAD
git push origin main

O ArgoCD detetará a reversão e sincronizará o cluster para o estado anterior.

dica

Para mais detalhes sobre rollback, consulte a página de Rollback.

Vídeo

Vídeo brevemente disponível.