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+
dica

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

Se o Argo CD ainda não estiver instalado, o Passo 4 abaixo (Opção A, deploy.sh --install) instala-o automaticamente — juntamente 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 ficheiros YAML chamados Applications. Cada componente do TDP — PostgreSQL, Kafka, Airflow, Trino, etc. — é representado por um ficheiro Application que instrui o Argo CD a transferir o chart correspondente do registry da Tecnisys e instalá-lo no cluster.

Esses ficheiros ficam num repositório Git. O Argo CD monitoriza esse repositório continuamente e sincroniza o estado do cluster com o que está declarado — sem precisar de executar 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 registada no Git
AutomaçãoExecução manual de cada chartSincronização automática contínua
RollbackRequer reexecução de comandosUm clique ou um comando
VisibilidadeApenas via terminalInterface web com estado 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 (com commit no git)
│   ├── common/
│   ├── tdp-postgresql/
│   └── ...
├── variables.env                    # Variáveis de ambiente (não fazer commit)
├── 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/ tem commit no git e é monitorizado pelo App of Apps do Argo CD.
  • common/ contém os recursos de bootstrap (AppProject, Secrets, App of Apps).

Conceitos essenciais​

Manifest: Um ficheiro 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 transferir um determinado chart Helm do Registry e instalá-lo num determinado namespace do cluster. Cada componente do TDP é representado por uma Application separada.

Repository (no contexto do Argo CD): A origem dos artefactos 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 gerir todos os componentes com uma única Application raiz, que descobre e instala automaticamente todas as restantes.

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 estabelecer conexão 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​

Faça clone (ou 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 ficheiro de referência e edite com os 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 monitorizar 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 predefinido 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.

aviso

variables.env.local está no .gitignore — nunca faça commit de tokens ou palavras-passe.

Passo 3 – Configurar o Argo CD para gerir 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 gerir esse namespace através 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 → preenche current/
  6. kubectl apply nos ficheiros 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 – Fazer commit e publicar current/ no Git​

O App of Apps lê current/ diretamente do repositório git. Os ficheiros têm de 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 estado​

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>

# Palavra-passe 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 estado das Applications
Figura 5 - Acompanhar o estado das Applications

Via interface web​

Aceda à 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.

Compreender 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 palavras-passe)

Personalização de componentes​

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

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

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

# Fazer commit 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 um ficheiro de variáveis personalizado (predefinido: 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)
-hMostrar ajuda

Exemplos:

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

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

# Reaplicar 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 palavras-passe.
  • 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 palavra-passe no db-create-job
  • tdp-trino: remoção de hooks elimináveis (PVC/Job)
  • tdp-hive-metastore: correção da rotação de palavra-passe + security context
  • tdp-superset: correção do randAlphaNum do PostgreSQL (Bitnami)
  • tdp-clickhouse: cleanup job desativado por omissão
  • tdp-airflow: remoção de lookup em secrets

Segurança​

  • variables.env.local está no .gitignore — nunca faça commit de tokens ou palavras-passe.
  • Use Kubernetes Secrets para dados sensíveis em runtime.
  • Rode 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 contentor, mas também pacotes Helm. Por isso, ao registar 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á. ↩