Integrações
Esta página apresenta os principais padrões de integração usados pelos componentes TDP Kubernetes.
Ela não substitui as páginas específicas de integração de cada componente. Use esta página para entender os conceitos gerais e consulte a página do componente para aplicar os parâmetros corretos, nomes de Secrets, endpoints, arquivos de valores e exemplos completos.
Como usar esta página
As integrações no TDP Kubernetes conectam um componente a outro serviço da plataforma ou a um serviço externo.
Essas integrações podem envolver banco de dados, object storage, catálogos de metadados, serviços de governança, ferramentas de catálogo de dados, sistemas de mensageria, APIs externas ou outros serviços necessários ao funcionamento do componente.
Nem todo componente usa todos esses padrões. A disponibilidade de cada integração depende do chart, dos valores expostos, da versão instalada e da configuração do ambiente.
| Tema | O que define | Onde detalhar |
|---|---|---|
| Banco de dados externo | Uso de um banco fora do chart do componente | Página de integração do componente |
| Object storage | Conexão com armazenamento compatível com S3 | Página de integração do componente |
| Catálogo de metadados | Uso de catálogo para bancos, tabelas, schemas e formatos de dados | Página de integração do componente |
| Governança e autorização | Integração com serviços de políticas e controle de acesso | Página de integração ou segurança do componente |
| Catálogo de dados e lineage | Registro de metadados, ativos de dados e rastreabilidade | Página de integração do componente |
| Mensageria, eventos e conectores | Integração com brokers, tópicos, conectores ou pipelines | Página de integração do componente |
Princípios gerais
Antes de configurar uma integração, valide:
- se o chart do componente documenta aquela integração;
- quais blocos de configuração devem ser usados;
- quais Secrets precisam existir;
- se o endpoint usado é interno ao cluster ou externo;
- se há dependência de TLS, autenticação ou autorização;
- se a configuração pertence ao componente, ao serviço integrado ou a ambos;
- se há jobs, hooks ou inicializações automáticas associados à integração.
Endpoints internos e externos
As integrações podem usar endereços internos do Kubernetes ou endereços externos ao cluster.
Endpoints internos do Kubernetes
Quando dois componentes rodam no mesmo cluster, a comunicação normalmente usa Services Kubernetes.
O formato comum é:
<SERVICE_NAME>.<NAMESPACE>.svc.cluster.local
Esse endereço é interno ao cluster e deve ser usado por Pods, jobs e serviços que precisam se comunicar entre si.
Exemplo genérico:
<POSTGRESQL_SERVICE>.<NAMESPACE>.svc.cluster.local
Substitua <SERVICE_NAME> e <NAMESPACE> pelos nomes reais do ambiente.
Endpoints externos
Quando o serviço integrado está fora do cluster, use o hostname ou endpoint externo correspondente.
Exemplos:
postgresql.empresa.com.br
s3.empresa.com.br
A escolha entre endpoint interno e externo depende de onde o serviço está instalado e de como ele é exposto na infraestrutura.
Credenciais e Secrets
Integrações normalmente exigem credenciais, como:
- usuário e senha de banco de dados;
- access key e secret key de object storage;
- credenciais de conectores;
- senhas de bind LDAP;
- tokens de API;
- certificados, keystores ou truststores.
Essas credenciais devem ser armazenadas em Kubernetes Secrets sempre que o chart permitir.
Exemplo genérico:
kubectl -n <NAMESPACE> create secret generic <APPLICATION_NAME>-credentials --from-literal=username='...' --from-literal=password='...'
O modo de referenciar o Secret varia por componente. Consulte a página específica de Integração e Segurança antes de aplicar a configuração.
Não inclua senhas em texto plano em arquivos de valores commitados no Git. Use Secrets ou ferramentas próprias de gestão de credenciais.
Banco de dados externo
Alguns componentes podem usar um banco de dados externo em vez de um banco interno, embutido ou provisionado junto ao chart.
Esse tipo de integração costuma exigir:
- hostname do banco;
- porta;
- nome do banco;
- usuário;
- senha;
- Secret com credenciais;
- parâmetros de criação ou reaproveitamento da base;
- validação de conectividade entre o componente e o banco.
O padrão exato de configuração varia por chart.
Exemplo conceitual:
externalDatabase:
enabled: true
host: "<DATABASE_HOST>"
port: 5432
database: "<DATABASE_NAME>"
existingSecret: "<DATABASE_SECRET>"
O exemplo acima é apenas conceitual. Use o bloco documentado na página específica do componente.
Object storage compatível com S3
Alguns componentes podem ler ou gravar dados em armazenamento compatível com S3, como serviços de object storage internos ou externos ao cluster.
Esse tipo de integração pode envolver:
- endpoint S3;
- bucket;
- access key;
- secret key;
- região;
- modo path-style;
- certificados;
- configuração Hadoop/Spark S3A;
- Secret com credenciais.
Exemplo conceitual:
s3:
endpoint: "https://<S3_ENDPOINT>"
bucket: "<S3_BUCKET>"
existingSecret: "<S3_SECRET_NAME>"
Em alguns charts, a integração S3 pode ser uma conexão gerenciada pela aplicação. Em outros, pode aparecer como propriedades Hadoop, Spark, catálogo, storage policy ou configuração de warehouse.
Consulte a página específica do componente para confirmar o padrão usado.
Catálogo de metadados
Alguns componentes podem depender de um catálogo de metadados para localizar bancos, tabelas, schemas, formatos de dados e localizações físicas dos dados.
Esse tipo de integração normalmente envolve:
- URI do serviço de catálogo;
- protocolo de comunicação;
- namespace e Service Kubernetes;
- configurações de warehouse;
- integração com object storage, quando os dados ficam em S3 ou equivalente;
- propriedades específicas do engine ou framework usado pelo componente.
Exemplo conceitual de URI interna:
thrift://<SERVICE_NAME>.<NAMESPACE>.svc.cluster.local:<SERVICE_PORT>
O modo de declarar essa integração varia conforme o componente.
Governança, autorização e políticas
Alguns componentes podem ser integrados a mecanismos de governança ou autorização.
Nesses casos, é importante separar dois lados da configuração:
| Lado | O que significa |
|---|---|
| Serviço de governança | Cadastro de serviços, políticas, usuários, grupos ou permissões |
| Componente integrado | Configuração necessária para consultar ou aplicar políticas em tempo de execução |
Cadastrar um serviço em uma ferramenta de governança não garante, por si só, que o componente já esteja aplicando políticas.
Quando esse tipo de integração existir, valide:
- se o serviço foi cadastrado corretamente;
- se as políticas foram criadas ou declaradas;
- se usuários e grupos existem;
- se o componente integrado está configurado para usar o mecanismo de autorização;
- se certificados, endpoints e credenciais estão corretos.
Os detalhes devem ser consultados na página específica do componente e, quando aplicável, na página de integração ou segurança do serviço de governança.
Catálogo de dados e lineage
Algumas integrações têm como objetivo catalogar metadados, registrar ativos de dados ou rastrear lineage.
Esse tipo de integração pode envolver:
- conectores configurados na ferramenta de catálogo;
- credenciais para acessar os serviços de origem;
- permissões de leitura;
- DAGs, jobs ou pipelines de ingestão;
- endpoints internos ou externos dos serviços integrados.
A configuração pode ser feita pelo chart, pela interface da ferramenta, por workflows próprios de ingestão ou por automações específicas do componente.
Consulte a página de integração do componente responsável pelo catálogo para entender o fluxo recomendado.
Mensageria, eventos e conectores
Integrações com mensageria ou conectores normalmente envolvem brokers, tópicos, conectores, credenciais e endpoints de bootstrap.
Esse tipo de configuração pode servir para:
- ingestão de dados;
- publicação de eventos;
- captura de mudanças;
- integração entre sistemas;
- pipelines de streaming.
Valide sempre:
- endpoint de bootstrap;
- protocolo de segurança;
- credenciais;
- certificados, quando houver TLS;
- permissões de leitura e escrita;
- configura ções específicas do conector.
Os parâmetros concretos devem ser aplicados conforme a página de integração do componente.
Fluxo de integração
Algumas integrações exigem configuração em mais de um lugar.
| Situação | Atenção |
|---|---|
| Serviço cadastrado em uma ferramenta externa | O componente ainda pode precisar ser configurado para usar esse serviço |
| Secret criado no Kubernetes | O chart ainda precisa referenciar esse Secret corretamente |
| Endpoint informado na configuração | O serviço precisa estar acessível a partir do Pod ou job que usará a integração |
| Política criada em um serviço de governança | O componente precisa estar preparado para consultar ou aplicar essa política |
| Catálogo configurado | O engine ou aplicação precisa usar esse catálogo em tempo de execução |
Por isso, valide sempre o fluxo completo da integração, não apenas a criação de um recurso isolado.
Validação de uma integração
Depois de configurar uma integração, valide em três níveis.
| Nível | O que validar |
|---|---|
| Configuração | Os valores do chart apontam para endpoints, Secrets e parâmetros corretos |
| Conectividade | O componente consegue alcançar o serviço integrado |
| Funcionalidade | A integração executa a operação esperada, como autenticar, consultar, gravar, catalogar ou aplicar política |
Comandos úteis dependem do componente, mas normalmente incluem:
kubectl get pods -n <NAMESPACE>
kubectl logs -n <NAMESPACE> <POD_NAME>
kubectl get secret -n <NAMESPACE>
kubectl exec -n <NAMESPACE> <POD_NAME> -- sh -c '...'
Use a página específica do componente para os comandos de validação completos.
Resolução de problemas
| Sintoma | Possível causa |
|---|---|
| Componente não conecta ao serviço integrado | Endpoint, porta, namespace ou DNS incorreto |
| Erro de autenticação | Secret ausente, credencial incorreta ou usuário sem permissão |
| Erro de certificado | Certificado ausente, truststore incorreta ou hostname fora do certificado |
| Integração criada, mas sem efeito em tempo de execução | Apenas um lado da integração foi configurado |
| Job de integração falha | Serviço integrado indisponível, credenciais incorretas ou parâmetros incompletos |
| Recurso não aparece na ferramenta de catálogo | Conector não executado, credencial sem permissão ou origem inacessível |
| Configuração aparentemente correta, mas sem efeito | O componente pode exigir configuração complementar em outro bloco ou página |
Próximos passos
Para configurar uma integração concreta, acesse a página de integração do componente correspondente.
Use esta página como referência geral para entender os padrões de integração do TDP Kubernetes. Os parâmetros, exemplos e validações devem sempre ser confirmados na documentação específica do componente.