Instalação via Helm
Esta secção descreve o processo de instalação dos componentes do TDP Kubernetes utilizando o Helm CLI.
Nesta abordagem, os componentes são instalados através 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, permitindo controlo direto sobre a sequência de implantação de cada componente.
Antes de iniciar a instalação, certifique-se de que todos os pré-requisitos foram cumpridos, 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 cumpridas. A tabela abaixo apresenta a ordem recomendada:
| Ordem | Chart | Componente | Versão | Dependências |
|---|---|---|---|---|
| 1 | tdp-argo-crds | ArgoCD CRDs | 3.2.5 | Nenhuma |
| 2 | tdp-argo | ArgoCD | 3.2.5 | tdp-argo-crds |
| 3 | tdp-postgresql | PostgreSQL | 17.5.0 | Nenhuma |
| 4 | tdp-kafka | Kafka (Strimzi) | 4.1.0 | Nenhuma |
| 5 | tdp-hive-metastore | Hive Metastore | 4.0.0 | Nenhuma |
| 6 | tdp-deltalake | Delta Lake | 4.0.0 | 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.0 | Nenhuma |
| 12 | tdp-trino | Trino | 478 | Nenhuma |
| 13 | tdp-airflow | Airflow | 3.0.2 | tdp-postgresql |
| 14 | tdp-jupyter | JupyterHub | 5.3.0 | Nenhuma |
| 15 | tdp-clickhouse | ClickHouse | 25.8.11.66 | Nenhuma |
| 16 | tdp-cloudbeaver | CloudBeaver | 25.2.3 | tdp-postgresql |
| 17 | tdp-openmetadata | OpenMetadata | 1.9.11 | tdp-postgresql |
| 18 | tdp-superset | Superset | 5.0.0 | tdp-postgresql |
A coluna Versão refere-se à versão do componente (ex.: Kafka 4.1.0, ArgoCD 3.2.5). A versão do chart Helm é 3.0.0 para todos os charts TDP; ao omitir --version no helm install, o Helm utiliza a mais recente disponível no registry.
O tdp-postgresql é uma dependência e deve ser instalado antes dos componentes que o utilizam: Airflow, OpenMetadata, Ranger, Superset e CloudBeaver. Instalar estes componentes sem o PostgreSQL ativo resultará em falha.
Conforme recomendado para ambientes de produção, estes componentes devem utilizar uma base de dados externa. No entanto, se nenhuma base externa for informada, cada componente utilizará uma instância interna exclusiva.
- Instalação dos Componentes
- Verificação da Instalação
- Resolução de Problemas
- Comandos
- Vídeo
Instalação
O padrão de instalação é o mesmo para todos os componentes. Para cada chart, execute:
helm install <chart-name> oci://registry.tecnisys.com.br/tdp/charts/<chart-name> \
-n <namespace> \
--create-namespace
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 opção --version for omitida, o Helm instalará automaticamente a versão mais recente disponível no registry. Para fixar uma versão específica, utilize --version <versao-do-chart>. As versões de cada componente (Kafka, Airflow, etc.) só é possível saber abrindo o Helm Chart ou após a instalação.
Após instalar cada componente, aguarde que os pods fiquem prontos antes de prosseguir:
kubectl get pods -n <namespace> --watch
Pressione Ctrl+C quando todos os pods do componente estiverem com estado Running e READY.
1. ArgoCD CRDs
helm install tdp-argo-crds oci://registry.tecnisys.com.br/tdp/charts/tdp-argo-crds \
-n <namespace> \
--create-namespace
2. ArgoCD
helm install tdp-argo oci://registry.tecnisys.com.br/tdp/charts/tdp-argo \
-n <namespace> \
--create-namespace
3. PostgreSQL
helm install tdp-postgresql oci://registry.tecnisys.com.br/tdp/charts/tdp-postgresql \
-n <namespace>
Aguarde que o PostgreSQL fique totalmente operacional antes de prosseguir com a instalação dos componentes que dependem dele. Verifique o estado:
kubectl get pods -n <namespace> | grep tdp-postgresql
O pod deve apresentar o estado Running e estar com todas as réplicas prontas (READY 1/1).
4. Kafka (Strimzi)
helm install tdp-kafka oci://registry.tecnisys.com.br/tdp/charts/tdp-kafka \
-n <namespace>
O Kafka utiliza o operador Strimzi para gestão dos brokers e topics no Kubernetes.
5. Hive Metastore
helm install tdp-hive-metastore oci://registry.tecnisys.com.br/tdp/charts/tdp-hive-metastore \
-n <namespace>
6. Delta Lake
helm install tdp-deltalake oci://registry.tecnisys.com.br/tdp/charts/tdp-deltalake \
-n <namespace>
7. Iceberg
helm install tdp-iceberg oci://registry.tecnisys.com.br/tdp/charts/tdp-iceberg \
-n <namespace>
8. Apache Ozone
helm install tdp-ozone oci://registry.tecnisys.com.br/tdp/charts/tdp-ozone \
-n <namespace>
9. Ranger
helm install tdp-ranger oci://registry.tecnisys.com.br/tdp/charts/tdp-ranger \
-n <namespace>
10. NiFi
helm install tdp-nifi oci://registry.tecnisys.com.br/tdp/charts/tdp-nifi \
-n <namespace>
11. Spark
helm install tdp-spark oci://registry.tecnisys.com.br/tdp/charts/tdp-spark \
-n <namespace>
12. Trino
helm install tdp-trino oci://registry.tecnisys.com.br/tdp/charts/tdp-trino \
-n <namespace>
13. Airflow
helm install tdp-airflow oci://registry.tecnisys.com.br/tdp/charts/tdp-airflow \
-n <namespace>
O Airflow requer que o PostgreSQL esteja operacional. Além disso, caso utilize o executor CeleryExecutor ou KubernetesExecutor com partilha de DAGs via volume, certifique-se de que uma Storage Class com suporte a ReadWriteMany (RWX) esteja disponível.
14. JupyterHub
helm install tdp-jupyter oci://registry.tecnisys.com.br/tdp/charts/tdp-jupyter \
-n <namespace>
15. ClickHouse
helm install tdp-clickhouse oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
-n <namespace>
16. CloudBeaver
helm install tdp-cloudbeaver oci://registry.tecnisys.com.br/tdp/charts/tdp-cloudbeaver \
-n <namespace>
17. OpenMetadata
helm install tdp-openmetadata oci://registry.tecnisys.com.br/tdp/charts/tdp-openmetadata \
-n <namespace>
18. Superset
helm install tdp-superset oci://registry.tecnisys.com.br/tdp/charts/tdp-superset \
-n <namespace>
- Comandos
- Vídeos
Verificação da Instalação
Após instalar todos os componentes desejados, verifique o estado geral da instalação.
Verificar os Pods
kubectl get pods -n <namespace>
Todos os pods devem apresentar o estado Running e estar com todas as réplicas prontas.
Verificar os Releases do Helm
helm list -n <namespace>
Todos os releases devem apresentar o estado deployed.
Verificar os Serviços
kubectl get svc -n <namespace>
Verificar os Volumes Persistentes
kubectl get pvc -n <namespace>
Todos os Persistent Volume Claims devem apresentar o estado Bound.
- Verificar os Pods
- Verificar os Releases do Helm
- Verificar os Serviços
- Verificar os Volumes Persistentes
Pods Não Arrancam
Se um pod permanece no estado Pending ou CrashLoopBackOff:
- Verifique os eventos do pod:
kubectl describe pod <pod-name> -n <namespace>
- Verifique os logs do pod:
kubectl logs <pod-name> -n <namespace>
- 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 cumprida: 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 estado ImagePullBackOff ou ErrImagePull:
- Verifique se a autenticação no registry foi realizada correctamente:
helm registry login registry.tecnisys.com.br
- Verifique se o Secret de autenticação do registry está configurado no namespace:
kubectl get secrets -n <namespace> | grep registry
- Caso seja necessário, crie o Secret manualmente:
kubectl create secret docker-registry tdp-registry-secret \
--docker-server=registry.tecnisys.com.br \
--docker-username=<utilizador> \
--docker-password=<palavra-passe> \
-n <namespace>
Falha na Ligação à Base de Dados
Se componentes como Airflow, Superset, Ranger, OpenMetadata ou CloudBeaver apresentam erros de ligação à base de dados:
- Verifique se o PostgreSQL está operacional:
kubectl get pods -n <namespace> | grep tdp-postgresql
- Verifique a conectividade interna do cluster:
kubectl run pg-test --rm -it --image=busybox -n <namespace> -- \
sh -c "nc -zv tdp-postgresql 5432"
- Verifique as credenciais configuradas nos values do chart do componente
Desinstalar um Componente com Problema
Para desinstalar e reinstalar um componente específico:
helm uninstall <chart-name> -n <namespace>
helm install <chart-name> oci://registry.tecnisys.com.br/tdp/charts/<chart-name> \
-n <namespace>
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:
kubectl delete pvc <pvc-name> -n <namespace>