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 correctos, nomes de Secrets, endpoints, ficheiros 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 bases 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 |
|---|---|---|
| Base de dados externa | Uso de uma base de dados 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 bases de dados, 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 controlo de acesso | Página de integração ou segurança do componente |
| Catálogo de dados e lineage | Registo de metadados, activos 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 essa integração;
- quais blocos de configuração devem ser usados;
- quais Secrets precisam de 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 executam 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 de 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 é exposto na infraestrutura.
Credenciais e Secrets
Integrações normalmente exigem credenciais, como:
- usuário e palavra-passe de base de dados;
- access key e secret key de object storage;
- credenciais de conectores;
- palavras-passe 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 palavras-passe em texto simples em ficheiros de valores commitados no Git. Use Secrets ou ferramentas próprias de gestão de credenciais.
Base de dados externa
Alguns componentes podem usar uma base de dados externa em vez de uma base interna, embutida ou provisionada junto ao chart.
Esse tipo de integração costuma exigir:
- hostname da base de dados;
- porta;
- nome da base de dados;
- usuário;
- palavra-passe;
- Secret com credenciais;
- parâmetros de criação ou reaproveitamento da base;
- validação de conectividade entre o componente e a base de dados.
O padrão exacto de configuração varia por chart.
Exemplo conceptual:
externalDatabase:
enabled: true
host: "<DATABASE_HOST>"
port: 5432
database: "<DATABASE_NAME>"
existingSecret: "<DATABASE_SECRET>"
O exemplo acima é apenas conceptual. 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 conceptual:
s3:
endpoint: "https://<S3_ENDPOINT>"
bucket: "<S3_BUCKET>"
existingSecret: "<S3_SECRET_NAME>"
Em alguns charts, a integração S3 pode ser uma conexão gerida 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 bases de dados, 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 conceptual 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 numa ferramenta de governança não garante, por si só, que o componente já esteja a aplicar políticas.
Quando esse tipo de integração existir, valide:
- se o serviço foi cadastrado correctamente;
- 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 correctos.
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 objectivo catalogar metadados, registar activos de dados ou rastrear lineage.
Esse tipo de integração pode envolver:
- conectores configurados na ferramenta de catálogo;
- credenciais para aceder aos 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 numa ferramenta externa | O componente ainda pode precisar de ser configurado para usar esse serviço |
| Secret criado no Kubernetes | O chart ainda precisa de referenciar esse Secret correctamente |
| Endpoint informado na configuração | O serviço precisa de estar acessível a partir do Pod ou job que usará a integração |
| Política criada num serviço de governança | O componente precisa de estar preparado para consultar ou aplicar essa política |
| Catálogo configurado | O engine ou aplicação precisa de 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 correctos |
| 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 incorrecto |
| Erro de autenticação | Secret ausente, credencial incorrecta ou usuário sem permissão |
| Erro de certificado | Certificado ausente, truststore incorrecta 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 incorrectas 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 correcta, 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, aceda à 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.