Configuração Geral

Para que serve a configuração

A configuração é a etapa em que adapta um componente TDP Kubernetes ao seu ambiente e ao seu modo de operação. 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 partilhadas — como base de dados, object storage e serviços de apoio. Com isso, o mesmo componente pode ser utilizado em contextos diferentes, como laboratório, homologação e produção, sem alterar a sua função principal.

Por exemplo:

• Ligar o Airflow à base de dados PostgreSQL do cluster em vez de utilizar a base interna
• Indicar ao Kafka quantas réplicas de broker e qual o fator de replicação mínimo a usar
• Informar ao NiFi onde está o servidor LDAP para autenticação
• Configurar o S3 Gateway do Ozone com as credenciais corretas para que o Spark possa gravar dados

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

Ao longo desta secção, encontrará os padrões de configuração mais comuns entre os componentes TDP:

Área	O que define	Exemplos
Execução no cluster	Onde e com que 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á acedido.	Service, porta, ingress, hostname e TLS.
Segurança e acesso	Como as credenciais e dados sensíveis serão fornecidos.	Secrets, utilizadores, palavras-passe, tokens e referências a secrets.
Integrações	Como o componente se liga a outros serviços.	PostgreSQL, S3/Ozone, endpoints e serviços partilhados.
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 respetivo 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 os seus valores predefinidos e comentários explicativos.

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

Exemplos genéricos

Os excertos YAML e de linha de comandos nesta página são ilustrativos.

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

Utilize 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 provêm da página de configuração do componente.

Via Helm

Comandos

Como funciona

O Helm utiliza ficheiros YAML chamados values para parametrizar os templates de cada chart. Você passa esses valores durante a instalação ou atualização do componente.

Existem três formas principais de fornecer valores:

Ficheiro 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 comandos:

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 ficheiros — múltiplos ficheiros 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 de configurar, exporte os valores aceites pelo chart para conhecer 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 aceites pelo chart

2. Crie um ficheiro (exemplo: meu-values.yaml) com os valores a alterar:

PowerShell

code .\meu-values.yaml

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

meu-values.yaml

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

nota

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

4. Aplique a configuração com o ficheiro 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 - Aplicação do ficheiro de configuração

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

nota

Para componentes stateful, como o 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 estado 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 ficheiros versionados no repositório Git — não em comandos executados diretamente no cluster. O ArgoCD monitoriza o repositório continuamente e reconcilia o estado do cluster com o que está declarado no Git.

Três conceitos centrais orientam este fluxo:

Application — recurso Kubernetes gerido pelo ArgoCD que aponta para um chart Helm e um ficheiro de valores no repositório. Cada componente TDP tem a 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á ativado 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, edite o ficheiro de valores no repositório e faça push. O ArgoCD deteta a alteração e aplica — sem necessidade de executar comandos de instalação.

Passo a passo

1. Aceda ao repositório GitOps:

Terminal input

cd ./tdp-GitOps

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

PowerShell

code .\caminho\do\ficheiro.yaml

Ou, se preferir:

PowerShell

notepad .\caminho\do\ficheiro.yaml

Figura 8 - Abrir o ficheiro de valores

3. Ajuste os parâmetros pretendidos no ficheiro:

de : ficheiro.yaml

primary:
  resources:
    requests:
      memory: 4Gi
      cpu: "1"
persistence:
  size: 25Gi

para : ficheiro.yaml

primary:
  resources:
    requests:
      memory: 4Gi
      cpu: "1"
persistence:
  size: 25Gi

Figura 9 - Alteração dos valores

4. Guarde e envie a alteração:

Terminal input

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

Figura 10 - Guardar e enviar a alteração

O ArgoCD detetará 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 - Inspecionar Application do componente

7. Se a sincronização automática não estiver ativada, ou para aplicar a alteração 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

nota

Para componentes stateful, como o 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 que você está instalando.

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 <namespace> --create-namespace

# Mesmo chart em namespace compartilhado com outros componentes
helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  -n <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 simultâneo ao mesmo volume, utilize ReadWriteMany (RWX) no accessMode.
Certifique-se de que o seu StorageClass suporta este modo.

Ingress

Alguns charts suportam exposição externa via Ingress.
Quando essa opção existir, os parâmetros normalmente ficam agrupados em um bloco específico do componente:

<prefixo-do-chart>:
  ingress:
    enabled: true
    ingressClassName: "nginx"
    hostname: "<host-do-componente>"
    path: /
    pathType: Prefix
    tls: true

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 ficheiro 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 pretende modificar:

Terminal input

cp values-padrao.yaml meu-values.yaml

3. Edite o ficheiro meu-values.yaml com as configurações pretendidas.

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

Configuração por ambiente

Ambiente de desenvolvimento

Para ambientes de desenvolvimento, utilize recursos reduzidos e desabilite opções de alta disponibilidade quando fizer sentido para o componente:

<prefixo-do-chart>:
  resources:
    requests:
      cpu: "250m"
      memory: "512Mi"
    limits:
      cpu: "500m"
      memory: "1Gi"
  replicaCount: 1

Ambiente de produção

Para ambientes de produção, configure recursos adequados, habilite persistência quando necessário e ajuste replicação, autenticação e integração externa conforme o componente:

<prefixo-do-chart>:
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "4"
      memory: "8Gi"
  replicaCount: 3

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 base 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 base 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 base 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), você centraliza:

• 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 você precisará disso?

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.