Saltar para o conteúdo principal
Versão 3.0

Instalação via Argo CD

CompatibilidadeKubernetes1.32+OpenShift4.19+Rancher2.10.x+Helm3.2.0+
tip

Antes de começar, confirme que os pré-requisitos foram atendidos.

Se o Argo CD ainda não estiver instalado, o Passo 4 abaixo (Opção A, deploy.sh --install) o instala automaticamente — junto com o bootstrap do GitOps. Se já estiver instalado, use a Opção B (deploy.sh -c).

Para instalar os componentes manualmente, sem GitOps, consulte a instalação via Helm.

Visão geral​

O Argo CD instala componentes a partir de arquivos YAML chamados Applications. Cada componente do TDP — PostgreSQL, Kafka, Airflow, Trino, etc. — é representado por um arquivo Application que instrui o Argo CD a baixar o chart correspondente do registry da Tecnisys e instalá-lo no cluster.

Esses arquivos ficam em um repositório Git. O Argo CD monitora esse repositório continuamente e sincroniza o estado do cluster com o que está declarado — sem precisar rodar comandos a cada mudança.

Diferença entre instalação com Argo CD e Helm​

CritérioHelm CLIArgo CD (GitOps)
RastreabilidadeComandos manuais, sem histórico automáticoCada mudança fica registrada no Git
AutomaçãoExecução manual de cada chartSincronização automática contínua
RollbackRequer reexecução de comandosUm clique ou um comando
VisibilidadeSomente via terminalInterface web com status em tempo real
AuditoriaDifícilCompleta, via histórico do Git

Estrutura do repositório GitOps​

A implementação atual utiliza uma estrutura de diretórios otimizada para GitOps:

tdp-gitops/
├── common/                          # Recursos de bootstrap (AppProject, Secrets, App of Apps)
│   ├── argo-gitops-appproject.yaml
│   ├── argo-gitops-app-of-apps.yaml
│   ├── tdp-devops-repo-secret.yaml
│   └── tdp-registry-secret.yaml
├── available/                       # Templates das Applications (com variáveis)
│   ├── tdp-postgresql/
│   │   ├── tdp-postgresql.yaml
│   │   └── values.yaml
│   ├── tdp-kafka/
│   └── ...
├── current/                         # Manifests renderizados (commitados no git)
│   ├── common/
│   ├── tdp-postgresql/
│   └── ...
├── variables.env                    # Variáveis de ambiente (não commitar)
├── deploy.sh                        # Script de automação
└── README.md

Como funciona:

  • available/ contém templates com variáveis (${VAR}) — nunca aplicados diretamente.
  • deploy.sh renderiza available/ + common/ → current/ substituindo as variáveis.
  • current/ é commitado no git e monitorado pelo App of Apps do Argo CD.
  • common/ contém os recursos de bootstrap (AppProject, Secrets, App of Apps).

Conceitos essenciais​

Manifest: Um arquivo YAML que descreve um recurso Kubernetes ou Argo CD. Neste contexto, cada manifest define uma Application do Argo CD — ou seja, instrui o Argo CD a instalar um determinado chart Helm.

Application: O objeto central do Argo CD. Orienta o Argo CD a baixar um determinado chart Helm do Registry e instalá-lo em um determinado namespace do cluster. Cada componente do TDP é representado por uma Application separada.

Repository (no contexto do Argo CD): A origem dos artefatos que o Argo CD irá utilizar. Pode ser um repositório Git (onde ficam os manifests) ou um registry OCI1 (onde ficam os Helm Charts da Tecnisys).

Sincronização: O processo pelo qual o Argo CD compara o estado declarado nos manifests com o estado real do cluster e aplica as mudanças necessárias.

App of Apps: Um padrão que permite gerenciar todos os componentes com uma única Application raiz, que descobre e instala automaticamente todas as demais.

Ordem de instalação​

Quando o App of Apps é aplicado, o Argo CD tenta sincronizar todos os componentes ao mesmo tempo.
Por isso, é importante que os componentes sem dependências estejam estáveis antes que os dependentes tentem se conectar a eles.
A tabela abaixo indica essa ordem e as dependências de cada chart:

OrdemChartComponenteVersãoDependências
1tdp-postgresqlPostgreSQL17.5.0Nenhuma
2tdp-kafkaKafka (Strimzi)4.1.0tdp-crds (Strimzi CRDs)
3tdp-hive-metastoreHive Metastore4.0.0tdp-postgresql
4tdp-deltalakeDelta Lake4.0.1Nenhuma
5tdp-icebergIceberg1.10.0Nenhuma
6tdp-ozoneApache Ozone2.0.0Nenhuma
7tdp-rangerRanger2.7.0tdp-postgresql
8tdp-nifiNiFi1.28.0Nenhuma
9tdp-sparkSpark4.0.2Nenhuma
10tdp-trinoTrino478Nenhuma
11tdp-airflowAirflow3.0.2tdp-postgresql
12tdp-jupyterJupyterHub5.3.0tdp-postgresql
13tdp-clickhouseClickHouse25.8.11.66tdp-crds (Altinity CRDs)
14tdp-cloudbeaverCloudBeaver25.3.0tdp-postgresql
15tdp-openmetadataOpenMetadata1.12.4tdp-postgresql
16tdp-supersetSuperset5.0.0tdp-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.1 para todos os charts TDP.

Pré-requisitos​

FerramentaObrigatório para
kubectl (configurado para o cluster)deploy, bootstrap
envsubst (pacote gettext)renderização de templates
gitmodo GitOps (push de current/)
helmbootstrap do Argo CD (--install)

Passo 1 – Obter o repositório GitOps​

Clone (ou faça fork) do repositório GitOps e entre na pasta:

Terminal input
git clone <GITOPS_REPO_URL>
cd tdp-gitops
Figura 1 - Clone do repositório GitOps
Figura 1 - Clone do repositório GitOps

Passo 2 – Configurar variáveis de ambiente​

Copie o arquivo de referência e edite com seus valores:

Terminal input
cp variables.env variables.env.local
vim variables.env.local

Variáveis obrigatórias em variables.env.local:

variables.env.local
# Namespace onde o Argo CD está instalado
ARGOCD_NAMESPACE=argocd

# Namespace alvo dos pods TDP
TDP_NAMESPACE=<NAMESPACE>

# Namespace onde as Applications Argo CD são criadas
TDP_PROJECT_NAMESPACE=<NAMESPACE>

# Nome da Application "App of Apps"
TDP_APPLICATIONS=argo-gitops-tdp-project

# URL deste repositório git (usado pelo Argo CD para monitorar current/)
GIT_REPO_URL=<GITOPS_REPO_URL>
GIT_REPO_USER=<GIT_USERNAME>
GIT_REPO_TOKEN_OR_PASS=<GIT_TOKEN>

# Helm OCI registry com os charts TDP
HELM_CHART_REPO_URL=registry.tecnisys.com.br/tdp/charts
HELM_CHART_VERSION=<TDP_K8S_RELEASE>

# Servidor Kubernetes (usar padrão para in-cluster)
KUBERNETES_SERVER=https://kubernetes.default.svc

# Credenciais do Helm OCI registry
TECNISYS_HELM_REGISTRY_USER=<REGISTRY_USERNAME>
TECNISYS_HELM_REGISTRY_TOKEN=<REGISTRY_CLI_SECRET>

Use em HELM_CHART_VERSION a versão da release atual: 3.0.1.

warning

variables.env.local está no .gitignore — nunca commite tokens ou senhas.

Passo 3 – Configurar o Argo CD para gerenciar Applications em namespace separado​

As Applications ficam no namespace <NAMESPACE> (definido em TDP_PROJECT_NAMESPACE), não no namespace argocd. Configure o Argo CD para gerenciar esse namespace por meio do parâmetro application.namespaces — consulte Configuração do Argo CD → Application namespaces.

Passo 4 – Bootstrap do Argo CD​

O script deploy.sh automatiza a instalação do Argo CD e o bootstrap do GitOps.

Opção A: Bootstrap completo — instala o Argo CD (recomendado)​

Instala o Argo CD (tdp-crds + tdp-argo) via Helm OCI, aguarda os pods prontos, renderiza os templates e aplica os recursos comuns:

Terminal input
./deploy.sh --install -v variables.env.local

O que é executado:

  1. helm registry login → autentica no OCI registry
  2. helm upgrade --install tdp-crds → instala os CRDs do Argo CD
  3. helm upgrade --install tdp-argo → instala o Argo CD
  4. kubectl rollout status → aguarda argocd-server e application-controller
  5. envsubst em todos os templates → popula current/
  6. kubectl apply nos arquivos de current/common/:
    • argo-gitops-appproject.yaml — AppProject TDP
    • tdp-devops-repo-secret.yaml — credencial git para o Argo CD
    • tdp-registry-secret.yaml — credencial do Helm OCI registry
    • argo-gitops-app-of-apps.yaml — Application "App of Apps"
Figura 2 - Bootstrap completo com deploy.sh --install
Figura 2 - Bootstrap completo com deploy.sh --install

Opção B: Apenas o GitOps — Argo CD já instalado​

Se o Argo CD já estiver instalado, apenas renderize e aplique os recursos comuns:

Terminal input
./deploy.sh -c -v variables.env.local
Figura 3 - Bootstrap manual com deploy.sh -c
Figura 3 - Bootstrap manual com deploy.sh -c

Passo 5 – Commitar e publicar current/ no Git​

O App of Apps lê current/ diretamente do repositório git. Os arquivos precisam estar publicados:

Terminal input
git add current/
git commit -m "chore: render gitops manifests"
git push origin main

O App of Apps criará automaticamente todas as Applications presentes em current/ com selfHeal: true.

Figura 4 - Publicar current/ no repositório Git
Figura 4 - Publicar current/ no repositório Git

Passo 6 – Acompanhar a sincronização​

Verificar o status​

Terminal input
# Application App-of-Apps (namespace argocd)
kubectl get application -n argocd

# Applications criadas (namespace dos componentes TDP)
kubectl get application -n <NAMESPACE>

# Pods no namespace dos componentes
kubectl get pods -n <NAMESPACE>

# Senha inicial do admin Argo CD
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d && echo
Figura 5 - Acompanhar o status das Applications
Figura 5 - Acompanhar o status das Applications

Via interface web​

Acesse a interface do Argo CD:

Terminal input
kubectl get ingress -n argocd
# ou
kubectl get httproute -n argocd
Figura 6 - Descobrir o host exposto
Figura 6 - Descobrir o host exposto

Navegue para a Application configurada em TDP_APPLICATIONS e acompanhe o progresso.

Entender o manifest de Application​

Cada componente usa um template parametrizado. Exemplo (renderizado):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tdp-postgresql
  namespace: <NAMESPACE>
  labels:
    tecnisys.io/cluster: tdp
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: <NAMESPACE>
  source:
    repoURL: registry.tecnisys.com.br/tdp/charts
    targetRevision: <TDP_K8S_RELEASE>
    chart: tdp-postgresql
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: <NAMESPACE>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - RespectIgnoreDifferences=true
  ignoreDifferences:
    - group: ""
      kind: Secret
      jqPathExpressions:
        - ".data"

Campos importantes:

  • metadata.namespace — namespace onde a Application é criada (TDP_PROJECT_NAMESPACE)
  • spec.project — AppProject que define as permissões (TDP_NAMESPACE)
  • spec.source.repoURL — registry OCI dos charts TDP
  • spec.source.chart — nome do chart
  • spec.destination.namespace — namespace onde os pods são criados (TDP_NAMESPACE)
  • syncPolicy.automated — sincronização automática
  • ignoreDifferences — ignora mudanças em Secrets (evita flapping de senhas)

Customização de componentes​

Cada componente tem um values.yaml em available/<componente>/:

Terminal input
# Editar valores do componente
vim available/tdp-postgresql/values.yaml

# Rerenderizar
./deploy.sh -v variables.env.local -p

# Commitar e publicar
git add current/tdp-postgresql/
git commit -m "chore: update postgresql values"
git push origin main

deploy.sh: referência completa​

Terminal input
./deploy.sh [OPÇÕES] [COMPONENTES...]
FlagDescrição
--installPrimeira instalação: helm login → tdp-crds → tdp-argo → aguarda ready → renderiza → aplica common
-v FILEUsar arquivo de variáveis customizado (padrão: variables.env)
-pRenderizar available/ → current/ apenas (sem aplicar)
-cAplicar apenas os recursos comuns (current/common/) via kubectl
-aRenderizar + aplicar componentes via kubectl (não aplica common)
-hExibir ajuda

Exemplos:

Terminal input
# Primeira instalação completa (instala Argo CD + bootstrap)
./deploy.sh --install -v variables.env.local

# Re-renderizar templates e publicar (modo GitOps)
./deploy.sh -p -v variables.env.local
git add current/ && git commit -m "chore: render" && git push

# Re-aplicar apenas os recursos comuns (AppProject, Secrets, App of Apps)
./deploy.sh -c -v variables.env.local

# Deploy direto de um componente (sem git push)
./deploy.sh -a tdp-postgresql -v variables.env.local

# Deploy direto de múltiplos componentes
./deploy.sh -a tdp-postgresql tdp-trino -v variables.env.local

Compatibilidade ArgoCD​

Todos os charts TDP foram ajustados para compatibilidade total com o Argo CD:

  • Single-source: as Applications usam apenas a fonte OCI (sem multi-source).
  • ignoreDifferences: Secrets ignorados para evitar flapping de senhas.
  • Check-or-reuse: credenciais reutilizadas quando já existem (sem rotação em sync).
  • Namespace separado: Applications em TDP_PROJECT_NAMESPACE.
  • Sync waves: ordenação correta de recursos dependentes.

Componentes com ajustes específicos para Argo CD:

  • tdp-jupyter: correção da rotação de senha no db-create-job
  • tdp-trino: remoção de hooks deletáveis (PVC/Job)
  • tdp-hive-metastore: correção da rotação de senha + security context
  • tdp-superset: correção do randAlphaNum do PostgreSQL (Bitnami)
  • tdp-clickhouse: cleanup job desabilitado por padrão
  • tdp-airflow: remoção de lookup em secrets

Segurança​

  • variables.env.local está no .gitignore — nunca commite tokens ou senhas.
  • Use Kubernetes Secrets para dados sensíveis em runtime.
  • Rotacione os tokens do git e do registry regularmente.
  • O TDP_PROJECT_NAMESPACE deve ter RBAC restrito.
  • Os Secrets do registry e do git são versionados como templates em common/ (preenchidos a partir de variables.env.local).

Componentes disponíveis​

ComponenteDescriçãoDependências
tdp-postgresqlPostgreSQL—
tdp-trinoTrino SQL engine—
tdp-airflowApache AirflowPostgreSQL
tdp-clickhouseClickHouse—
tdp-cloudbeaverCloudBeaver UIPostgreSQL
tdp-deltalakeDelta Lake—
tdp-hive-metastoreHive MetastorePostgreSQL
tdp-icebergApache Iceberg—
tdp-jupyterJupyterHub—
tdp-kafkaApache Kafka (Strimzi)—
tdp-nifiApache NiFi—
tdp-openmetadataOpenMetadataPostgreSQL
tdp-ozoneApache Ozone S3—
tdp-rangerApache Ranger—
tdp-sparkApache Spark—
tdp-supersetApache SupersetPostgreSQL

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 Argo CD tentará tratar o endereço como um repositório Helm convencional baseado em index.yaml e a conexão falhará. ↩