Configuração Geral

Para que serve a configuração

A configuração é a etapa em que um componente TDP Kubernetes é adaptado ao ambiente e ao modo de operação adotado. Ela define como o componente será implantado, quais recursos utilizará, como será exposto, de quais dependências precisa e como se integrará aos demais serviços da plataforma.

Na prática, a configuração permite ajustar parâmetros como namespace, CPU, memória, armazenamento, secrets, acesso externo, persistência e integrações compartilhadas — como banco de dados, object storage e serviços de apoio. Com isso, o mesmo componente pode ser usado em contextos diferentes, como laboratório, homologação e produção, sem mudar sua função principal.

Por exemplo:

• Conectar o Airflow ao PostgreSQL do cluster em vez de usar o banco interno
• Dizer ao Kafka quantas réplicas de broker e qual fator de replicação mínimo usar
• Informar ao NiFi onde está o servidor LDAP para autenticação
• Configurar o S3 Gateway do Ozone com as credenciais certas para que o Spark possa gravar dados

Os parâmetros de configuração se aplicam independentemente do método de instalação utilizado. O objetivo desta página é explicar o que normalmente pode ser configurado em um componente TDP e como esses ajustes funcionam na prática.

Ao longo desta seção, são apresentados os padrões de configuração mais comuns entre os componentes TDP:

Área	O que define	Exemplos
Execução no cluster	Onde e com quais recursos o componente será executado.	Namespace, CPU, memória, réplicas e limites.
Persistência	Como os dados serão armazenados.	Volumes, disco, storage class e retenção.
Exposição do serviço	Como o componente será acessado.	Service, porta, ingress, hostname e TLS.
Segurança e acesso	Como credenciais e dados sensíveis serão fornecidos.	Secrets, usuários, senhas, tokens e referências a secrets.
Integrações	Como o componente se conecta a outros serviços.	PostgreSQL, S3/Ozone, endpoints e serviços compartilhados.
Forma de aplicação	Como a configuração chega ao cluster.	Helm, ArgoCD/GitOps e futuramente tdpctl.

Para detalhes exatos de cada componente e versão, consulte também a página específica do componente e os valores suportados pelo respectivo chart.

Como saber quais valores um chart aceita

Execute helm show values oci://registry.tecnisys.com.br/tdp/charts/<chart> para exportar todos os parâmetros disponíveis com seus valores padrão e comentários explicativos.

Figura 1 — Descobrir parâmetros disponíveis

Este comando exporta os valores padrão do chart para um arquivo local values-padrao.yaml.
Esse arquivo pode ser usado como base para criação de um arquivo de valores customizado, com os ajustes necessários para o ambiente.

Os componentes são distribuídos como charts Helm e, em geral, aceitam customização por meio de arquivos de valores (YAML) passados na instalação ou na atualização (por exemplo com a opção -f).

Exemplos genéricos

Os trechos YAML e de linha de comando nesta página são ilustrativos.

O prefixo raiz (tdp-airflow, tdp-trino, etc.) e a estrutura exata das chaves variam conforme o componente.

Use a página de configuração do componente neste guia e, para a sua versão exata do pacote, exporte os valores predefinidos com helm show values oci://registry.tecnisys.com.br/tdp/charts/<chart>.

Como aplicar a configuração

Os passos abaixo são os mesmos independentemente do componente. O que muda é o contexto do ambiente — os parâmetros em si vêm da página de configuração do componente.

Via Helm

Comandos

Como funciona

O Helm utiliza arquivos YAML chamados values para parametrizar os templates de cada chart. Estes valores são passados durante a instalação ou atualização do componente.

Existem três formas principais de fornecer valores:

Arquivo de valores — a forma recomendada. Crie um YAML com apenas as chaves que deseja alterar e passe com -f:

Terminal input

helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <namespace> --create-namespace \
  -f meu-values.yaml

Flag --set — para alterações pontuais diretamente na linha de comando:

Terminal input

helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <namespace> --create-namespace \
  --set parametro.chave=valor

Combinação de arquivos — múltiplos arquivos mesclados em ordem, com os últimos tendo precedência:

Terminal input

helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <namespace> --create-namespace \
  -f values-base.yaml \
  -f values-producao.yaml

Passo a passo

1. Antes da configuração, exporte os valores aceitos pelo chart para identificar os parâmetros disponíveis:

Terminal input

helm show values oci://registry.tecnisys.com.br/tdp/charts/<chart> > values-padrao.yaml

Figura 2 - Exportação dos valores aceitos pelo chart

2. Crie um arquivo (exemplo: meu-values.yaml) com os valores a serem alterados:

PowerShell

code .\meu-values.yaml

3. Ajuste os parâmetros desejados, como namespace, recursos ou integrações:

meu-values.yaml

resources:
  requests:
    cpu: "500m"
    memory: "1Gi"
  limits:
    cpu: "1"
    memory: "2Gi"

note

Não é necessário copiar todo o arquivo padrão do chart. Inclua apenas os valores que deseja sobrescrever.

4. Aplique a configuração com o arquivo criado:

Terminal input

helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <namespace> --create-namespace \
  -f meu-values.yaml

Figura 3 - Configuração do arquivo criado

5. Verifique se os valores configurados foram aplicados:

Terminal input

helm get values <release> -n <namespace>

Figura 4 - Verificação dos valores configurados

6. Verifique os pods:

Terminal input

kubectl get pods -n <namespace>

Figura 5 - Verificação dos pods

note

Para componentes stateful, como PostgreSQL, valide também:

kubectl get statefulset -n <namespace>

Figura 6 - Validação de componentes stateful

Para componentes que utilizam Deployment, valide também:

kubectl get deploy -n <namespace>

7. Confirme que o release está com status deployed e com a revisão atualizada:

Terminal input

helm list -n <namespace>

Figura 7 - Helm list

Vídeos

helm show values

helm upgrade --install

helm get values

kubectl get pods

kubectl get statefulset

helm list

Via ArgoCD

Comandos

Como funciona

No fluxo GitOps com ArgoCD, a configuração é declarada em arquivos versionados no repositório Git — não em comandos executados diretamente no cluster. O ArgoCD monitora o repositório continuamente e reconcilia o estado do cluster com o que está declarado no Git.

Três conceitos centrais orientam esse fluxo:

Application — recurso Kubernetes gerenciado pelo ArgoCD que aponta para um chart Helm e um arquivo de valores no repositório. Cada componente TDP tem sua própria Application.

Sincronização (Sync) — processo pelo qual o ArgoCD compara o estado declarado no Git com o estado atual do cluster e aplica as diferenças. Pode ser automática (quando automated está habilitado na Application) ou manual (argocd app sync).

Reconciliação contínua — quando selfHeal: true está configurado, o ArgoCD corrige automaticamente qualquer desvio entre o cluster e o Git, mesmo que alguém tenha alterado algo diretamente no cluster.

Para alterar a configuração de um componente, o arquivo de valores é editado no repositório e a alteração é enviada ao Git. O ArgoCD detecta a mudança e aplica — sem necessidade de rodar comandos de instalação.

Passo a passo

1. Acesse o repositório GitOps:

Terminal input

cd ./tdp-GitOps

2. Abra o arquivo de valores do componente indicado na página específica do componente:

PowerShell

code .\caminho\do\arquivo.yaml

Ou, se preferir:

PowerShell

notepad .\caminho\do\arquivo.yaml

Figura 8 - Abre o arquivo de valores

3. Ajuste os parâmetros desejados no arquivo:

de : arquivo.yaml

primary:
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
persistence:
  size: 10Gi

para : arquivo.yaml

primary:
  resources:
    requests:
      cpu: "1200m"
      memory: "1Gi"
    limits:
      cpu: "1"
      memory: "2Gi"
persistence:
  size: 25Gi

Figura 9 - Alteração dos valores - exemplo

Figura 9a - Alteração dos valores - exemplo

4. Salve e envie a alteração:

Terminal input

git add .
git commit -m "config: ajustar parâmetros do componente"
git push origin main

Figura 10 - Salva e envia alteração

O ArgoCD detectará automaticamente a alteração e iniciará a sincronização.

5. Verifique se a Application evolui para Synced e Healthy:

Terminal input

argocd app list

Figura 11 - Verifica Application

6. Para inspecionar a Application do componente em detalhe:

Terminal input

argocd app get <componente>

Figura 12 - Inspeciona Application do componente

7. Se a sincronização automática não estiver habilitada, ou se quiser aplicar a mudança imediatamente:

Terminal input

argocd app sync <componente>

Figura 13 - Sincronização manual

8. Verifique os pods:

Terminal input

kubectl get pods -n <namespace>

Figura 14 - Verifica os pods

note

Para componentes stateful, como PostgreSQL, valide também:

kubectl get statefulset -n <namespace>

Figura 15 - Verifica componentes stateful

Para componentes que utilizam Deployment, valide também:

kubectl get deploy -n <namespace>

Confirme que os pods estão em Running e que os workloads mostram todas as réplicas prontas.

Vídeos

Ajustar parâmetros

git push

argocd app list

argocd app get

argocd app sync

kubectl get pods

kubectl get statefulset

Padrões comuns entre os charts TDP

Os charts do TDP Kubernetes compartilham alguns padrões de uso, mas a estrutura exata das chaves pode variar de componente para componente.
Confirme os parâmetros suportados na documentação do componente aqui e, se necessário, na saída de helm show values para a versão em uso.

Padrão do componente e revisão da configuração

Em geral, a primeira instalação de um componente parte do comportamento padrão definido pelo chart. Esse padrão existe para permitir que o serviço seja implantado com o conjunto mínimo de dependências externas, facilitando validação inicial, testes controlados e primeiros acessos.

Na passagem para ambientes mais estáveis ou compartilhados, a configuração costuma ser revista em pontos como banco de dados, persistência, autenticação, exposição externa, observabilidade e integração com serviços comuns da plataforma. Essa revisão não altera a função principal do componente, mas ajusta a forma como ele se encaixa nas exigências operacionais do ambiente.

Por esse motivo, as páginas específicas dos componentes descrevem primeiro o comportamento inicial e depois os blocos de configuração que normalmente exigem atenção em laboratório, homologação ou produção.

Namespace

Cada componente pode ser instalado em um namespace dedicado ou compartilhar um namespace com outros componentes, de acordo com a estratégia do ambiente:

Terminal input

# Namespace dedicado (exemplo ilustrativo)
helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <dedicated-namespace> --create-namespace

# Mesmo chart em namespace compartilhado com outros componentes
helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <shared-namespace> --create-namespace

Recursos (CPU e memória)

Muitos charts permitem configurar requests e limits de CPU e memória para os principais pods. A posição dessas chaves pode variar no arquivo de valores do componente:

<prefixo-do-chart>:
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "2"
      memory: "4Gi"

Recomendação

Sempre defina requests e limits para garantir que o Kubernetes faça agendamento adequado dos pods e evite problemas de falta de recursos.

Persistência de dados

Os charts que requerem armazenamento persistente costumam expor opções de PVC (Persistent Volume Claim).
O caminho pode variar conforme o componente:

<prefixo-do-chart>:
  persistence:
    enabled: true
    size: 10Gi
    storageClassName: "<storage-class>"
    accessMode: ReadWriteOnce

Atenção

Para componentes que executam em múltiplos nós e precisam de acesso concorrente ao mesmo volume, utilize ReadWriteMany (RWX) no accessMode.
Certifique-se de que seu StorageClass suporta este modo.

Ingress

Alguns charts suportam exposição externa via Ingress.
Para ativá-lo, dois blocos devem ser configurados: o controle do gateway (TDPConfiguration) e os parâmetros do Ingress no chart do componente.

Ingress vs Gateway API

TDPConfiguration.gateway.ingress.enabled e TDPConfiguration.gateway.gatewayApi.enabled são mutuamente exclusivos.
Ative apenas um deles. Consulte Gateway API se o cluster usa HTTPRoute em vez de Ingress.

TDPConfiguration:
  gateway:
    ingress:
      enabled: true   # habilita o Ingress; desative se usar Gateway API
    gatewayApi:
      enabled: false

<prefixo-do-chart>:
  ingress:
    enabled: true
    ingressClassName: "<ingress-class>"   # use: kubectl get ingressclass
    hostname: "<host-do-componente>"
    path: /
    pathType: Prefix
    tls: true

Como descobrir o ingressClassName disponível no cluster

kubectl get ingressclass

O valor da coluna NAME é o que deve ser informado em ingressClassName.

Para detalhes de cada componente — incluindo o caminho exato das chaves e o endereço de acesso — consulte a página de Ingress do respectivo componente no índice de configuração.

Serviços (NodePort vs ClusterIP)

Quando o chart expõe opções de Service, os tipos mais comuns são ClusterIP, NodePort e LoadBalancer:

<prefixo-do-chart>:
  service:
    type: ClusterIP

Arquivo de values customizado

A abordagem recomendada é criar um arquivo de values específico para o seu ambiente:

1. Exporte os values padrão do chart:

Terminal input

helm show values oci://registry.tecnisys.com.br/tdp/charts/<chart> > values-padrao.yaml

2. Crie uma cópia com apenas os valores que deseja modificar:

Terminal input

cp values-padrao.yaml meu-values.yaml

3. Edite o arquivo meu-values.yaml com as configurações desejadas.

4. Aplique durante a instalação ou atualização:

Terminal input

helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <namespace> --create-namespace \
  -f meu-values.yaml

Gerenciamento de secrets

Os charts do TDP seguem boas práticas de segurança para credenciais e dados sensíveis.

Kubernetes Secrets

Credenciais devem ser armazenadas em Kubernetes Secrets, nunca em texto plano nos arquivos de values:

Terminal input

kubectl -n <namespace> create secret generic meu-secret \
  --from-literal=password='<senha>'

Referência a Secrets no arquivo de valores

No arquivo de valores, referencie Secrets existentes em vez de colocar senhas em texto plano:

passwordSecret:
  name: "meu-secret"
  key: "password"

Importante

Nunca armazene credenciais em arquivos de valores que serão versionados no Git.
Utilize Kubernetes Secrets, Sealed Secrets ou ferramentas como HashiCorp Vault.

TDPConfigurations

Diversos charts do TDP utilizam a seção TDPConfigurations para configuração de serviços compartilhados, como banco de dados externo e conexões S3:

TDPConfigurations:
  externalDatabase:
    enabled: true
    recreate: false
    externalSecret:
      releaseName: "<tdp-postgresql-release>"
      area: "<area>"

  s3Connection:
    enabled: true
    secretName: "<nome-do-secret-ou-conexao>"
    uri: "https://<s3-endpoint>"

Campo recreate

O campo recreate controla se o banco de dados do componente deve ser recriado durante uma reinstalação:

• false (padrão): mantém os dados existentes. Use em ambientes produtivos.
• true: apaga e recria o banco. Use quando houver certeza de que o banco de dados pode ser removido.

Registry de Helm Charts

Os charts TDP são distribuídos via registry OCI da Tecnisys:

Registry	Uso
oci://registry.tecnisys.com.br/tdp/	Versões estáveis e homologadas

Autenticação no registry

Para acessar o registry, é necessário efetuar login com as credenciais fornecidas pela Tecnisys antes de instalar ou atualizar qualquer chart:

Terminal input

helm registry login registry.tecnisys.com.br \
  --username <usuario> \
  --password <senha>

PostgreSQL interno versus externo

Vários componentes TDP precisam de um banco relacional para armazenar seus próprios metadados.

O chart de cada componente suporta dois modos:

Modo	Descrição	Quando usar
PostgreSQL embutido (postgres.enabled: true)	Subchart instalado junto com o componente, autocontido	Desenvolvimento, testes isolados, ambientes temporários
PostgreSQL externo (postgres.enabled: false)	Usa o tdp-postgresql já instalado no cluster	Produção, ambientes compartilhados

Por que usar PostgreSQL externo em produção?

Com PostgreSQL externo e compartilhado (tdp-postgresql), centralizam-se:

• Backups: um único ponto de backup para todos os bancos de metadados da plataforma
• Monitoramento: métricas e alertas em um único lugar
• Dimensionamento: ajusta max_connections e recursos uma única vez para toda a plataforma

O PostgreSQL embutido é conveniente mas isolado — cada componente gerencia seu próprio banco, o que aumenta o custo operacional em produção.

Armazenamento S3-compatível (Ozone)

Alguns componentes TDP precisam acessar armazenamento de objetos S3-compatível para ler ou gravar arquivos (dados de entrada, outputs de pipelines, logs, DAGs).

No TDP Kubernetes, o serviço S3 é o Apache Ozone (tdp-ozone).

Quando um componente tem TDPConfigurations.s3Connection.enabled: true, o chart cria automaticamente um Kubernetes Secret com os parâmetros de conexão (endpoint, chave de acesso, chave secreta).

Esse Secret é então referenciado pelos operadores e conectores do componente para acessar o Ozone como se fosse o S3 da Amazon.

Quando essa configuração é necessária?

Configure a conexão S3 quando o componente precisar:

• Ler dados de entrada armazenados no Ozone (ex.: Spark lendo Parquet)
• Gravar outputs no Ozone (ex.: resultados de pipelines Airflow)
• Manter arquivos entre execuções (ex.: DAGs do Airflow armazenados no Ozone)

Se o componente for usado apenas com dados em memória ou em PVCs locais, a conexão S3 não é necessária.

Próximo passo

Para acessar a configuração de um componente específico, volte ao índice de configuração.