Instalação via ArgoCD (GitOps)

Esta seção descreve o processo de instalação dos componentes do TDP Kubernetes utilizando o ArgoCD como ferramenta de GitOps.

tip

Antes de iniciar a instalação via ArgoCD, certifique-se de que os pré-requisitos foram atendidos e que o ArgoCD já esteja instalado no cluster.
Caso ainda não tenha instalado o ArgoCD, consulte os passos 1 e 2 da instalação via Helm.

Visão Geral

O ArgoCD é uma ferramenta de entrega contínua (CD) baseada no modelo GitOps.
Nesse modelo, você descreve a infraestrutura que deseja ter — quais componentes, em qual versão, com quais configurações — em arquivos YAML chamados manifests, e os armazena em um repositório Git.
O ArgoCD monitora esse repositório e garante que o cluster Kubernetes sempre reflita o que está declarado nesses arquivos.

Diferença entre a instalação com o ArgoCD e Helm

Critério	Helm CLI	ArgoCD (GitOps)
Rastreabilidade	Comandos manuais, sem histórico automático	Cada mudança fica registrada no Git
Automação	Execução manual de cada chart	Sincronização automática contínua
Rollback	Requer reexecução de comandos	Um clique ou um comando
Visibilidade	Somente via terminal	Interface web com status em tempo real
Auditoria	Difícil	Completa, via histórico do Git

Conceitos essenciais para instalação com o ArgoCD

Antes de começar, é importante entender os conceitos centrais desta instalação:

Manifest : Um arquivo YAML que descreve um recurso Kubernetes ou ArgoCD.
Neste contexto, cada manifest define uma Application do ArgoCD — ou seja, instrui o ArgoCD a instalar um determinado chart Helm.
Os arquivos são criados com base nos modelos fornecidos nesta documentação e armazenados no repositório Git indicado.

Application : O objeto central do ArgoCD.
Uma Application orienta o ArgoCD no sentido de baixar um determinado chart Helm do Registry e instalá-lo em um determinado namespace do cluster.
Cada componente do TDP (Kafka, Airflow, Trino, etc.) é representado por uma Application separada.

Repository (no contexto do ArgoCD) : É a origem dos artefatos que o ArgoCD irá utilizar.
Pode ser um repositório Git (onde ficam seus manifests) ou um registry OCI¹ (onde ficam os Helm Charts da Tecnisys).
Ambos precisam ser cadastrados no ArgoCD antes de criar as Applications.

Sincronização : O processo pelo qual o ArgoCD compara o estado declarado nos manifests com o estado real do cluster.
Se houver diferença, o ArgoCD aplica as mudanças necessárias — automaticamente (se configurado) ou mediante comando manual.

App of Apps : Um padrão que permite gerenciar todos os componentes com uma única Application raiz.
Em vez de aplicar vários manifests um a um, permite a aplicação de um único arquivo que instrui o ArgoCD a descobrir e instalar todos os demais automaticamente.

Ordem de Instalação

A instalação dos componentes deve seguir uma ordem específica para garantir que as dependências sejam atendidas:

Ordem	Chart	Componente	Versão	Dependências
1	tdp-postgresql	PostgreSQL	17.5.0	Nenhuma
2	tdp-kafka	Kafka (Strimzi)	4.1.0	Nenhuma
3	tdp-hive-metastore	Hive Metastore	4.0.0	Nenhuma
4	tdp-deltalake	Delta Lake	4.0.0	Nenhuma
5	tdp-iceberg	Iceberg	1.10.0	Nenhuma
6	tdp-ozone	Apache Ozone	2.0.0	Nenhuma
7	tdp-ranger	Ranger	2.7.0	tdp-postgresql
8	tdp-nifi	NiFi	1.28.0	Nenhuma
9	tdp-spark	Spark	4.0.0	Nenhuma
10	tdp-trino	Trino	478	Nenhuma
11	tdp-airflow	Airflow	3.0.2	tdp-postgresql
12	tdp-jupyter	JupyterLab	5.3.0	Nenhuma
13	tdp-clickhouse	ClickHouse	25.8.11.66	Nenhuma
14	tdp-cloudbeaver	CloudBeaver	25.2.3	tdp-postgresql
15	tdp-openmetadata	OpenMetadata	1.9.11	tdp-postgresql
16	tdp-superset	Superset	5.0.0	tdp-postgresql

A coluna Versão refere-se à versão do componente (ex.: Kafka 4.1.0, Airflow 3.0.2). A versão do chart Helm é 3.0.0 para todos os charts TDP.

note

O ArgoCD (incluindo os CRDs necessários) é pré-requisito deste procedimento: o cluster já deve ter o ArgoCD operacional (veja a instalação via Helm).
Os charts tdp-argo-crds e tdp-argo não entram na sequência, pois não são instalados por este fluxo GitOps.

warning

O tdp-postgresql é uma dependência e deve estar operacional antes dos componentes que o utilizam, como: Airflow, OpenMetadata, Ranger, Superset e CloudBeaver.
Ao usar o padrão App of Apps, o ArgoCD tenta criar todos ao mesmo tempo; esses componentes podem apresentar falhas temporárias até que o PostgreSQL esteja pronto — o selfHeal² os reconciliará automaticamente.

---

Instalação

Passo 1 – Conexão do Registry OCI ao ArgoCD

O primeiro passo é informar ao ArgoCD onde estão os Helm Charts do TDP.
Os charts ficam no registry OCI privado da Tecnisys (registry.tecnisys.com.br).
Para que o ArgoCD consiga baixá-los, é necessário cadastrar esse endereço como um repositório Helm com suporte a OCI.
Esse cadastro não instala nada — ele apenas habilita o ArgoCD a acessar o registry como fonte de artefatos.
As credenciais de acesso devem ser obtidas junto à Tecnisys.

Interface Web

Comandos

1. Acesse a interface do ArgoCD no navegador.
O endereço depende da forma de exposição HTTP configurada no seu ambiente.
Se o ambiente usar Ingress, descubra o host com:

Terminal input

kubectl get ingress -n argocd

Exemplo de resultado:

NAME                CLASS   HOSTS                      PORTS
tdp-argocd-server   nginx   argocd.<cluster-domain>    80

Figura 1 - Descobrir o host exposto - get ingress

Abra https://argocd.<cluster-domain> no navegador.

Figura 2 - Acesso ao ArgoCD

Gateway API

Se o ambiente utilizar Gateway API em vez de Ingress, descubra o host exposto com:

Terminal input

kubectl get httproute -n argocd

Consulte Ingress vs Gateway API para mais detalhes sobre as duas abordagens suportadas.

2. No menu lateral, acesse Settings → Repositories.

3. Clique em Connect Repo e preencha os campos:

Campo	Valor
Repository Type	Helm
Repository URL	registry.tecnisys.com.br
Enable OCI	true (marcar o checkbox)
Username	<usuario>
Password	<senha>

4. Clique em Connect.
O repositório deve aparecer na lista com status de conexão bem-sucedida.

Figura 3 - Repo Connect

Vídeos

get ingress

Conexão do Repositório

CLI

Comandos

Instalar o Argo CD CLI

Para utilizar os comandos desta seção, instale o cliente Argo CD CLI na sua máquina a partir das releases oficiais do projeto (escolha o binário adequado ao seu sistema operacional):

github.com/argoproj/argo-cd/releases

1. Efetue o Login na CLI

Se utilizar a CLI do ArgoCD, faça login antes de executar comandos.
As credenciais são as do usuário configurado no ArgoCD.

Terminal input

argocd login argocd.seu-dominio.com.br

Figura 1 - Login no ArgoCD CLI

2. Registre o repositório Helm OCI no ArgoCD

Execute o comando abaixo no terminal, substituindo <usuario> e <senha> pelas credenciais fornecidas pela Tecnisys:

Terminal input

argocd repo add registry.tecnisys.com.br \
  --type helm \
  --name tdp-registry \
  --enable-oci \
  --username <usuario> \
  --password <senha>

Figura 2 - Conexão do Registry OCI ao ArgoCD

3. Verifique o registro

Terminal input

argocd repo list

Resultado esperado:

TYPE  NAME          REPO                       OCI
helm  tdp-registry  registry.tecnisys.com.br  true

Figura 3 - Verificação do repositório

Vídeos

argocd login

argocd repo add

argocd repo list

---

Passo 2 – Criação do Repositório GitOps

É necessária a criação de um repositório Git para armazenar os manifests das Applications.
Esse repositório é o ponto de verdade do seu ambiente: o ArgoCD o monitora continuamente e aplica qualquer mudança que for enviada para ele.

note

Você deve criar este repositório Git na sua plataforma de preferência (GitHub, GitLab, Gitea, etc.) e dar ao ArgoCD acesso de leitura a ele.
O repositório pode ser privado — nesse caso, cadastre-o também no ArgoCD via Settings → Repositories, da mesma forma que fez com o registry OCI, mas selecionando o tipo Git e fornecendo as credenciais de acesso.

Estrutura recomendada

Crie o repositório com a seguinte organização de pastas e arquivos:

tdp-gitops/
├── app-of-apps.yaml               # Application raiz — aplique este arquivo para iniciar tudo
├── apps/                          # Um manifest por componente TDP
│   ├── tdp-postgresql.yaml
│   ├── tdp-kafka.yaml
│   ├── tdp-hive-metastore.yaml
│   ├── tdp-deltalake.yaml
│   ├── tdp-iceberg.yaml
│   ├── tdp-ozone.yaml
│   ├── tdp-ranger.yaml
│   ├── tdp-nifi.yaml
│   ├── tdp-spark.yaml
│   ├── tdp-trino.yaml
│   ├── tdp-airflow.yaml
│   ├── tdp-jupyter.yaml
│   ├── tdp-clickhouse.yaml
│   ├── tdp-cloudbeaver.yaml
│   ├── tdp-openmetadata.yaml
│   └── tdp-superset.yaml
└── values/                        # Configurações personalizadas por componente (opcional)
    ├── tdp-postgresql-values.yaml
    ├── tdp-kafka-values.yaml
    └── ...

note

O que você cria: os arquivos YAML em apps/ (os manifests das Applications) e o app-of-apps.yaml.
Os modelos estão fornecidos no Passo 3.

Os arquivos values/ são opcionais e permitem personalizar a instalação de cada componente — por exemplo, definir senhas, limites de recursos ou parâmetros específicos.
Se não existirem, cada componente usará os valores padrão do chart.

Os Helm Charts em si são fornecidos pela Tecnisys no registry OCI.
Você não precisa criar nem modificar os charts.

Passo 3 – Criação dos Manifests das Applications

Cada componente do TDP Kubernetes é representado por um arquivo YAML que define uma Application do ArgoCD.
Copie os modelos abaixo para os arquivos correspondentes em apps/ do seu repositório, substituindo <namespace> pelo namespace que você escolheu para o seu ambiente (ex.: tdp-producao, tdp-dev, meu-namespace).

Comandos

Entender o Manifest

Antes de copiar os modelos, entenda o que cada campo significa:

Campo	O que define
metadata.name	Nome da Application no ArgoCD (deve ser único)
metadata.namespace	Namespace onde o ArgoCD está instalado — normalmente argocd
spec.source.repoURL	Endereço do registry OCI onde o chart está armazenado
spec.source.chart	Nome do chart Helm a ser instalado
spec.source.targetRevision	Versão do chart — use 3.0.0 para todos os charts TDP
spec.source.helm.valueFiles	Arquivos de customização (opcional; criados por você em values/)
spec.destination.server	Cluster de destino — use https://kubernetes.default.svc para o cluster local
spec.destination.namespace	Namespace onde o componente será instalado
syncPolicy.automated.prune	Se true, remove do cluster recursos que foram removidos do manifest
syncPolicy.automated.selfHeal	Se true, reverte alterações manuais feitas diretamente no cluster
syncOptions.CreateNamespace	Cria o namespace automaticamente se ainda não existir

Figura 4 - Criação do Manifest - exemplo para PostgreSQL

1. PostgreSQL

O PostgreSQL é o banco de dados relacional utilizado como dependência por vários componentes da plataforma: Airflow (metadados dos DAGs e histórico de execuções), OpenMetadata (catálogo de dados), Ranger (políticas de segurança), Superset (metadados dos dashboards) e CloudBeaver (configurações). Deve estar operacional antes desses componentes.

apps/tdp-postgresql.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-postgresql
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-postgresql
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

2. Kafka (Strimzi)

O Apache Kafka é a plataforma de mensageria e streaming de eventos da plataforma. Gerenciado pelo operador Strimzi, que automatiza a criação, o escalonamento e a recuperação dos brokers e tópicos Kafka no Kubernetes.

apps/tdp-kafka.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-kafka
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-kafka
    targetRevision: 3.0.0
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

3. Hive Metastore

O Hive Metastore é o serviço de catálogo de metadados de tabelas. Armazena o esquema (colunas, tipos, partições) das tabelas gerenciadas pela plataforma, sendo utilizado pelo Spark e pelo Trino para descobrir e acessar os dados.

apps/tdp-hive-metastore.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-hive-metastore
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-hive-metastore
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

4. Delta Lake

O Delta Lake é uma camada de armazenamento open source que adiciona transações ACID, versionamento e controle de esquema ao armazenamento de objetos. Permite operações confiáveis de leitura e escrita em grande escala.

apps/tdp-deltalake.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-deltalake
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-deltalake
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

5. Iceberg

O Apache Iceberg é um formato de tabela open source de alto desempenho para grandes volumes de dados analíticos. Oferece evolução de esquema, particionamento oculto e viagem no tempo (time travel), sendo amplamente compatível com motores de consulta como Trino e Spark.

apps/tdp-iceberg.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-iceberg
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-iceberg
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

6. Apache Ozone

O Apache Ozone é um sistema de armazenamento de objetos distribuído, compatível com a API S3. Em ambientes on-premise, atua como alternativa ao Amazon S3 ou MinIO, sendo o armazenamento primário de dados da plataforma.

apps/tdp-ozone.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-ozone
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-ozone
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

7. Ranger

O Apache Ranger é o componente de segurança e governança de acesso. Centraliza as políticas de autorização para todos os serviços da plataforma — quem pode acessar quais dados, em quais tabelas ou tópicos — e registra o histórico de acessos para auditoria. Depende do PostgreSQL.

apps/tdp-ranger.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-ranger
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-ranger
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

8. NiFi

O Apache NiFi é a ferramenta de ingestão e roteamento de dados. Por meio de uma interface visual, permite criar fluxos de dados (pipelines) que movem, transformam e integram dados entre fontes externas e a plataforma.

apps/tdp-nifi.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-nifi
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-nifi
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

9. Spark

O Apache Spark é o motor de processamento distribuído da plataforma. Utilizado para processamento em lote (batch), transformações de dados em larga escala e pipelines de machine learning.

apps/tdp-spark.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-spark
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-spark
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

10. Trino

O Trino é o motor de consulta SQL distribuída. Permite executar consultas SQL analíticas diretamente sobre os dados armazenados no Ozone/S3, Delta Lake ou Iceberg, sem a necessidade de mover os dados para outro sistema.

apps/tdp-trino.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-trino
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-trino
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

11. Airflow

O Apache Airflow é a ferramenta de orquestração de pipelines de dados. Permite criar, agendar e monitorar workflows (DAGs — Directed Acyclic Graphs) que coordenam a execução de tarefas de ingestão, transformação e carga de dados. Depende do PostgreSQL.

apps/tdp-airflow.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-airflow
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-airflow
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

12. JupyterHub

O JupyterHub é o servidor multi-usuário de notebooks. Permite que analistas e cientistas de dados executem notebooks Jupyter diretamente no cluster, com acesso aos dados e à capacidade computacional da plataforma.

apps/tdp-jupyter.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-jupyter
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-jupyter
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

13. ClickHouse

O ClickHouse é o banco de dados analítico OLAP (Online Analytical Processing) da plataforma. Otimizado para consultas analíticas de alta velocidade sobre grandes volumes de dados, é ideal para dashboards e relatórios em tempo real.

apps/tdp-clickhouse.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-clickhouse
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-clickhouse
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

14. CloudBeaver

O CloudBeaver é a interface web de administração de bancos de dados. Permite conectar-se a diferentes bancos de dados (PostgreSQL, ClickHouse, etc.) e executar queries diretamente no navegador. Depende do PostgreSQL.

apps/tdp-cloudbeaver.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-cloudbeaver
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-cloudbeaver
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

15. OpenMetadata

O OpenMetadata é o catálogo de dados e plataforma de governança da plataforma. Permite descobrir, documentar e gerenciar todos os ativos de dados — tabelas, pipelines, dashboards — com linhagem automática e controle de qualidade. Depende do PostgreSQL.

apps/tdp-openmetadata.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-openmetadata
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-openmetadata
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

16. Superset

O Apache Superset é a ferramenta de visualização e BI (Business Intelligence) da plataforma. Permite criar dashboards interativos e gráficos conectados ao ClickHouse, Trino e outros bancos de dados da plataforma. Depende do PostgreSQL.

apps/tdp-superset.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-superset
  namespace: argocd
spec:
  project: default
  source:
    repoURL: oci://registry.tecnisys.com.br/tdp
    chart: tdp-superset
    targetRevision: 3.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: <namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Vídeo

---

Passo 4 – Criação do Manifest App of Apps

O padrão App of Apps permite que você inicie toda a instalação com um único comando.
Em vez de aplicar os vários manifests um a um, é possível criar uma Application raiz (app-of-apps.yaml) que aponta para a pasta apps/ do seu repositório Git.
O ArgoCD lê essa pasta, descobre todos os manifests e cria automaticamente todas as Applications definidas ali.

Comandos

Crie o arquivo app-of-apps.yaml na raiz do seu repositório.
Substitua a URL de repoURL pela URL do seu repositório Git (onde você armazenou os arquivos do Passo 3):

app-of-apps.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-stack
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.seu-servidor.com.br/seu-usuario/tdp-gitops.git
    targetRevision: main
    path: apps
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

note

O campo spec.source.repoURL deve apontar para o repositório Git que você criou no Passo 2, onde estão os manifests das Applications. Se o repositório for privado, cadastre-o previamente no ArgoCD via Settings → Repositories.

Figura 5 - Criação do Manifest app-of-apps - exemplo

Vídeo

---

Passo 5 – Aplicação do App of Apps

Com o repositório GitOps criado e os manifests prontos, aplique a Application raiz para iniciar a instalação de todos os componentes.

Comandos

1. Faça o clone do repositório Git no seu terminal local

Terminal input

git clone https://git.seu-servidor.com.br/seu-usuario/tdp-gitops.git

Figura 6 - Git Clone - exemplo

2. Aplique o arquivo:

Terminal input

cd tdp-gitops
kubectl apply -f app-of-apps.yaml

Figura 7 - Aplicando o arquivo - exemplo

A partir desse momento, o ArgoCD descobrirá todos os manifests em apps/ e iniciará a instalação de todos os componentes do TDP Kubernetes.

Acompanhar o Progresso

Terminal input

argocd app list

Figura 8 - Applications do TDP e seus status

Políticas de sincronização

Os manifests nesta documentação utilizam syncPolicy.automated — o ArgoCD sincroniza automaticamente sempre que detecta diferenças.
Os dois parâmetros de controle são:

Parâmetro	Efeito quando true
prune	Remove do cluster recursos que foram removidos do manifest no Git
selfHeal	Reverte no cluster alterações feitas manualmente (fora do Git)

Para ambientes que exigem maior controle, remova o bloco automated do manifest.
Nesse caso, a sincronização deve ser iniciada manualmente:

Terminal input

argocd app sync tdp-postgresql

Figura 9 - app sync

Vídeos

git clone

kubectl apply

argocd app list

argocd app sync

Verificação da Instalação

Verificação da Instalação

Após aplicar o App of Apps, utilize os comandos abaixo para acompanhar o estado da instalação.

Comandos

Verificar o status das Applications

Terminal input

argocd app list

Figura 1 - app list

Cada Application pode apresentar os seguintes status:

Status 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 status

Status de Saúde	Descrição
Healthy	Todos os recursos da Application estão operacionais
Progressing	Os recursos estão sendo 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 1 - Verificar a application postgresql

Verificar os Pods no cluster

Terminal input

kubectl get pods -n <namespace>

Figura 2 - Verificar os pods

Todos os pods devem apresentar status Running com todas as réplicas prontas.

Verificar os Releases do Helm

Terminal input

helm list -n <namespace>

Figura 3 - Verificar os Releases do Helm

Todos os releases devem apresentar status deployed.

Verificar os Serviços

Terminal input

kubectl get svc -n <namespace>

Figura 4 - Verificar os Serviços

Verificar os Volumes Persistentes

Terminal input

kubectl get pvc -n <namespace>

Figura 5 - Verificar os Volumes Persistentes

Todos os Persistent Volume Claims devem apresentar status Bound.

Vídeos

argocd app get

kubectl get pods

helm list

kubectl get svc

kubectl get pvc

Resolução de Problemas

Resolução de Problemas

Application em OutOfSync ou Degraded

Se uma Application aparece com status OutOfSync ou Degraded:

1. Verifique os detalhes da Application:

   Terminal input

   argocd app get <nome-da-application>

2. Verifique os eventos e logs dos pods:

   Terminal input

   kubectl describe pod <pod-name> -n <namespace>
   kubectl logs <pod-name> -n <namespace>

3. Tente sincronizar manualmente:

   Terminal input

   argocd app sync <nome-da-application>

ArgoCD não consegue acessar o registry

Se o ArgoCD apresenta erro ao tentar baixar um chart do registry OCI:

1. Verifique se o repositório está cadastrado corretamente:

   Terminal input

   argocd repo list

2. Verifique as credenciais — elas podem ter expirado.
   Recadastre o repositório com as credenciais atualizadas:

   Terminal input

   argocd repo add registry.tecnisys.com.br \
     --type helm \
     --name tdp-registry \
     --enable-oci \
     --username <usuario> \
     --password <senha>

3. Verifique a conectividade do cluster com o registry:

   Terminal input

   kubectl run test-dns --rm -it --image=busybox -n <namespace> -- \
     sh -c "nslookup registry.tecnisys.com.br"

Componentes com dependência do PostgreSQL falhando

Se Airflow, Superset, Ranger, OpenMetadata ou CloudBeaver apresentam falhas logo após a aplicação do App of Apps:

1. Verifique se o PostgreSQL está operacional:

   Terminal input

   kubectl get pods -n <namespace> | grep tdp-postgresql

2. Se o PostgreSQL ainda não está Running, aguarde.
   O selfHeal do ArgoCD tentará reconciliar os componentes dependentes automaticamente assim que o PostgreSQL ficar disponível.

3. Para forçar a reconciliação manualmente:

   Terminal input

   argocd app sync tdp-airflow

Rollback de uma Application

O ArgoCD mantém histórico de sincronizações.
Para reverter um componente a uma versão anterior:

1. Via interface web: selecione a Application → History and Rollback → escolha a revisão → clique em Rollback.

2. Via CLI:

   Terminal input

   # Listar o histórico
   argocd app history tdp-kafka
   
   # Reverter para uma revisão específica
   argocd app rollback tdp-kafka <revision-id>

warning

Ao realizar rollback de um componente que depende do PostgreSQL, verifique se a versão do banco de dados é compatível com a versão do componente sendo revertido.

Forçar remoção de uma Application com problema

Para desinstalar e reinstalar uma Application específica:

Terminal input

argocd app delete <nome-da-application>
kubectl apply -f apps/<nome-da-application>.yaml

warning

A exclusão de uma Application não remove os Persistent Volume Claims (PVCs) associados.
Para uma reinstalação limpa, exclua os PVCs manualmente:

Terminal input

kubectl delete pvc <pvc-name> -n <namespace>

Footnotes

1. OCI (Open Container Initiative) é o padrão moderno para armazenar não apenas imagens de contêiner, mas também pacotes Helm. Por isso, ao cadastrar o registry, é necessário marcar a opção Enable OCI — sem ela, o ArgoCD tentará tratar o endereço como um repositório Helm convencional baseado em index.yaml e a conexão falhará. ↩

2. Reconciliação automatica com o Git ↩