Instalação via Helm

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

Esta seção descreve o processo de instalação dos componentes do TDP Kubernetes utilizando o Helm CLI.

Nessa abordagem, os componentes são instalados por meio da execução direta de comandos helm install, que implantam no cluster Kubernetes os recursos definidos em cada Helm Chart disponível no registry OCI privado da Tecnisys.

Na instalação via Helm a aplicação dos charts é realizada manualmente ou por automação externa, comando a comando, com controle direto sobre a sequência de implantação de cada componente.

tip

Antes de iniciar a instalação, certifique-se de que todos os pré-requisitos foram atendidos, incluindo a autenticação no registry OCI da Tecnisys.

Ordem de Instalação

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

Ordem	Chart	Componente	Versão	Dependências
1	tdp-crds	CRDs da Plataforma	3.0.1	Nenhuma
2	tdp-argo	Argo CD	3.2.5	tdp-crds
3	tdp-postgresql	PostgreSQL	17.5.0	Nenhuma
4	tdp-kafka	Kafka (Strimzi)	4.1.0	tdp-crds (Strimzi CRDs)
5	tdp-hive-metastore	Hive Metastore	4.0.0	tdp-postgresql
6	tdp-deltalake	Delta Lake	4.0.1	Nenhuma
7	tdp-iceberg	Iceberg	1.10.0	Nenhuma
8	tdp-ozone	Apache Ozone	2.0.0	Nenhuma
9	tdp-ranger	Ranger	2.7.0	tdp-postgresql
10	tdp-nifi	NiFi	1.28.0	Nenhuma
11	tdp-spark	Spark	4.0.2	Nenhuma
12	tdp-trino	Trino	478	Nenhuma
13	tdp-airflow	Airflow	3.0.2	tdp-postgresql
14	tdp-jupyter	JupyterHub	5.3.0	tdp-postgresql
15	tdp-clickhouse	ClickHouse	25.8.11.66	tdp-crds (Altinity CRDs)
16	tdp-cloudbeaver	CloudBeaver	25.3.0	tdp-postgresql
17	tdp-openmetadata	OpenMetadata	1.12.4	tdp-postgresql
18	tdp-superset	Superset	5.0.0	tdp-postgresql

A coluna Versão refere-se à versão do componente (appVersion do chart, ex.: Kafka 4.1.0, Argo CD 3.2.5). A versão do chart Helm (version no Chart.yaml) é um número separado — para o tdp-kafka, por exemplo, a chart version é 3.0.1 enquanto a appVersion é 4.1.0. Ao omitir --version no helm install, o Helm instala a versão mais recente disponível no registry.

warning

• O tdp-postgresql é uma dependência para componentes configurados para usar o PostgreSQL da stack e deve estar operacional antes deles.

• Instalar um componente dependente sem o PostgreSQL ativo resultará em falha.

• Conforme recomendado para ambientes de produção, componentes que dependem de banco de dados devem utilizar uma base externa.

• No entanto, se nenhuma base externa for informada, o componente utilizará uma instância interna exclusiva quando essa opção existir no chart.

• Para entender melhor essa diferença, consulte PostgreSQL interno versus externo.

Instalação dos Componentes

Comandos

Instalação

O padrão de instalação é o mesmo para todos os componentes. Para cada chart, execute:

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  --create-namespace \
  -f <VALUES_FILE>

Figura 1 - Instalação via Helm

note

O parâmetro --create-namespace cria o namespace <NAMESPACE> automaticamente na primeira instalação. Nas instalações subsequentes, o namespace já existirá e o parâmetro será ignorado.

Se a flag --version for omitida, o Helm instalará a versão mais recente do chart disponível no registry. Para fixar uma versão específica do chart, utilize --version <CHART_VERSION>.
A versão do componente instalado (Kafka, Airflow, etc.) é definida pelo appVersion do chart e pode ser consultada no próprio chart antes da instalação ou verificada nos recursos implantados após a instalação.

Verificação após cada instalação

Após instalar cada componente, aguarde os pods ficarem prontos antes de prosseguir:

Terminal input

kubectl get pods -n <NAMESPACE> --watch

Figura 2 - Verifica os Pods

Pressione Ctrl+C quando todos os pods do componente estiverem com status Running e READY.

1. CRDs da Plataforma (tdp-crds)

O que são CRDs?

Custom Resource Definitions (CRDs) ensinam ao Kubernetes novos tipos de recurso que ele não conhece nativamente. Os operadores da plataforma (NiFiKop, Strimzi, ArgoCD, ClickHouse etc.) precisam que esses tipos estejam registrados no cluster antes de serem instalados — sem eles, o Kubernetes não consegue criar objetos como NifiCluster, Kafka ou Application.

Os CRDs são recursos de escopo global (não pertencem a um namespace) e são gerenciados num chart dedicado (tdp-crds) para evitar conflitos durante upgrades do Helm.

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-crds \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  --create-namespace \
  -f <VALUES_FILE>

Nome do release (<RELEASE_NAME>)

Nos comandos de instalação abaixo, <RELEASE_NAME> é o nome do release Helm do componente. Muitas equipes usam o prefixo tdp- alinhado ao nome do chart (ex.: chart tdp-kafka com release tdp-kafka). Ajuste à convenção do seu ambiente.

CRDs incluídos no tdp-crds

Este chart instala os CRDs necessários para:

• Argo CD — Application, ApplicationSet, AppProject
• Strimzi Kafka Operator — Kafka, KafkaConnect, KafkaTopic, KafkaUser, KafkaNodePool, entre outros
• NiFiKop Operator — NifiCluster, NifiDataflow, NifiUser, entre outros
• Altinity ClickHouse Operator — ClickHouseInstallation, ClickHouseKeeperInstallation, entre outros
• OpenMetadata OMJob Operator — OMJob, CronOMJob
• cert-manager — Certificate, ClusterIssuer, Issuer, entre outros

2. ArgoCD

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-argo \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  --create-namespace \
  -f <VALUES_FILE>

3. PostgreSQL

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-postgresql \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

important

Aguarde o PostgreSQL ficar totalmente operacional antes de prosseguir com a instalação dos componentes que dependem dele. Verifique o status:

Terminal input

kubectl get pods -n <NAMESPACE> | grep <RELEASE_NAME>

O pod deve apresentar o status Running e estar com todas as réplicas prontas (READY 1/1).

Exemplo

Se o release do PostgreSQL for tdp-postgresql, o filtro pode ser grep tdp-postgresql na saída de kubectl get pods.

4. Kafka (Strimzi)

Pré-requisito: CRDs do Strimzi

O tdp-kafka depende dos CRDs do Strimzi (ex.: Kafka, KafkaNodePool, KafkaConnect, KafkaConnector) que são instalados pelo tdp-crds (passo 1).
Certifique-se de que o tdp-crds foi aplicado antes de instalar o tdp-kafka.
Sem os CRDs, o Helm não conseguirá criar os recursos do Strimzi e a instalação falhará.

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-kafka \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  --create-namespace \
  -f <VALUES_FILE>

Validação pós-instalação do Kafka

Após a instalação, verifique se o cluster Kafka foi criado corretamente:

Terminal input

kubectl get kafka -n <NAMESPACE>
kubectl get kafkanodepools -n <NAMESPACE>
kubectl get pods -n <NAMESPACE> -l strimzi.io/cluster=<KAFKA_CLUSTER_NAME>
kubectl get svc -n <NAMESPACE> | grep kafka
kubectl get kafkaconnect -n <NAMESPACE>
kubectl get kafkaconnector -n <NAMESPACE>

Substitua <KAFKA_CLUSTER_NAME> pelo valor de name no values.yaml (padrão: tdp-kafka).

chart version vs. appVersion

Para o tdp-kafka, a chart version (ex.: 3.0.1) é diferente da appVersion (ex.: 4.1.0 — versão do Apache Kafka).
Use helm show chart oci://registry.tecnisys.com.br/tdp/charts/tdp-kafka para consultar ambas.

5. Hive Metastore

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-hive-metastore \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

6. Delta Lake

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-deltalake \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

7. Iceberg

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-iceberg \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

8. Apache Ozone

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-ozone \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

9. Ranger

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-ranger \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

10. NiFi

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-nifi \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

11. Spark

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-spark \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

12. Trino

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-trino \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

13. Airflow

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-airflow \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

note

O Airflow requer que o PostgreSQL esteja operacional. Além disso, caso utilize o executor CeleryExecutor ou KubernetesExecutor com compartilhamento de DAGs via volume, certifique-se de que uma Storage Class com suporte a ReadWriteMany (RWX) esteja disponível.

14. JupyterHub

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-jupyter \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

15. ClickHouse

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

16. CloudBeaver

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

17. OpenMetadata

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-openmetadata \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE> \
  --wait --wait-for-jobs --timeout 10m

OpenMetadata — jobs de inicialização

O OpenMetadata executa Jobs Kubernetes durante a instalação e atualização.
O flag --wait-for-jobs instrui o Helm a aguardar a conclusão desses jobs antes de considerar a instalação bem-sucedida.
Recomenda-se usar --wait --wait-for-jobs --timeout 10m para garantir que os jobs pós-instalação sejam concluídos.
No Argo CD, a Application só deve ser considerada saudável após os jobs pós-instalação/atualização serem concluídos.

18. Superset

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-superset \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

Vídeo

Verificação da Instalação

Comandos

Verificação da Instalação

Após instalar todos os componentes desejados, verifique o status geral da instalação.

Verificar os Pods

Terminal input

kubectl get pods -n <NAMESPACE>

Figura 1 - Get Pods

Todos os pods devem apresentar o status Running e estar com todas as replicas prontas.

Verificar os Releases do Helm

Terminal input

helm list -n <NAMESPACE>

Figura 2 - Helm Releases

Todos os releases devem apresentar o status deployed.

Verificar os Serviços

Terminal input

kubectl get svc -n <NAMESPACE>

Figura 3 - Get svc

Verificar os Volumes Persistentes

Terminal input

kubectl get pvc -n <NAMESPACE>

Figura 4 - Get pvc

Todos os Persistent Volume Claims devem apresentar o status Bound.

Vídeos

Verificar os Pods

Verificar os Releases do Helm

Verificar os Serviços

Verificar os Volumes Persistentes

Resolução de Problemas

Pods Não Iniciam

Se um pod permanece no status Pending ou CrashLoopBackOff:

1. Verifique os eventos do pod:

Terminal input

kubectl describe pod <pod-name> -n <NAMESPACE>

2. Verifique os logs do pod:

Terminal input

kubectl logs <pod-name> -n <NAMESPACE>

3. Causas comuns:

• Recursos insuficientes: o cluster não possui CPU ou memória suficiente para agendar o pod. Verifique com kubectl describe node
• PVC pendente: a Storage Class configurada não está disponível ou não suporta o modo de acesso solicitado
• Dependência não atendida: o componente depende do PostgreSQL ou de outro serviço que ainda não está operacional

Erro de Pull de Imagem (ImagePullBackOff)

Se um pod apresenta o status ImagePullBackOff ou ErrImagePull:

1. Verifique se a autenticação no registry foi realizada corretamente:

Terminal input

helm registry login registry.tecnisys.com.br

2. Verifique se o Secret de autenticação do registry está configurado no namespace:

Terminal input

kubectl get secrets -n <NAMESPACE> | grep registry

3. Caso necessário, crie o Secret manualmente:

Terminal input

kubectl delete secret <docker-registry-secret> -n <NAMESPACE> 2>/dev/null || true
kubectl create secret docker-registry <docker-registry-secret> \
  --docker-server=registry.tecnisys.com.br \
  --docker-username=<username> \
  --docker-password=<password> \
  -n <NAMESPACE>

Exemplo

Exemplo

kubectl delete secret tdp-registry-secret -n <NAMESPACE> 2>/dev/null || true
kubectl create secret docker-registry tdp-registry-secret \
  --docker-server=registry.tecnisys.com.br \
  --docker-username=<username> \
  --docker-password=<password> \
  -n <NAMESPACE>

Falha na Conexão com o Banco de Dados

Se componentes como Airflow, Superset, Ranger, OpenMetadata ou CloudBeaver apresentam erros de conexão com o banco de dados:

1. Verifique se o PostgreSQL está operacional:

Terminal input

kubectl get pods -n <NAMESPACE> | grep <RELEASE_NAME>

Exemplo

Com release tdp-postgresql: kubectl get pods -n <NAMESPACE> | grep tdp-postgresql

2. Verifique a conectividade interna do cluster:

Terminal input

kubectl run pg-test --rm -it --image=busybox -n <NAMESPACE> -- \
  sh -c "nc -zv <postgresql-service> 5432"

Exemplo

Quando o serviço padrão do chart expõe o host tdp-postgresql no namespace:

Exemplo

kubectl run pg-test --rm -it --image=busybox -n <NAMESPACE> -- \
  sh -c "nc -zv tdp-postgresql 5432"

3. Verifique as credenciais configuradas nos values do chart do componente

Desinstalar um Componente com Problema

Para desinstalar e reinstalar um componente especifico:

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>
helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/<chart> \
  --version <CHART_VERSION> \
  -n <NAMESPACE> \
  -f <VALUES_FILE>

warning

A desinstalação de um release Helm não remove os Persistent Volume Claims (PVCs) associados. Para uma reinstalação limpa, exclua os PVCs manualmente antes de reinstalar:

Terminal input

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