Configuração do Airflow

Para saber mais

Consulte Apache Airflow — Conceitos para uma visão completa da ferramenta, da sua arquitetura e do seu funcionamento.

No ficheiro de configuração do componente, as opções do Airflow ficam agrupadas sob a chave tdp-airflow.

O projeto empacota o Apache Airflow 3.0.2 para Kubernetes, com KubernetesExecutor como executor predefinido.

Configuração predefinida

Esta secção descreve o ponto de partida da instalação do Airflow no TDP Kubernetes. O objetivo é registar o comportamento inicial do componente antes de detalhar ajustes de base de dados, autenticação, persistência e integrações.

Comportamento por omissão do chart tdp-airflow:

Por predefinição, o chart privilegia uma instalação funcional com o mínimo de dependências externas: executor em Kubernetes, metadados em PostgreSQL local e DAGs em volume persistente. A revisão destes padrões depende da política operacional adotada para base de dados, armazenamento, autenticação e observabilidade, conforme descrito em Configuração Geral.

• Executor: KubernetesExecutor
• Base de dados: PostgreSQL incorporado (subchart), com tdp-airflow.postgresql.enabled: true por predefinição
• DAGs: persistência em PVC ativada por predefinição (tdp-airflow.dags.persistence.enabled: true, tamanho típico 5Gi)
• Logs: persistência em PVC desativada por predefinição (tdp-airflow.logs.persistence.enabled: false); ative apenas se o StorageClass cumprir o padrão de acesso necessário (em geral RWX)

O comando abaixo representa a forma habitual de instalar ou atualizar o Airflow. O ficheiro meu-values.yaml é onde ficam apenas os ajustes necessários para o ambiente, sem alterar o procedimento básico.

Terminal input

helm upgrade --install <release> oci://registry.tecnisys.com.br/tdp/charts/tdp-airflow \
  -n <namespace> --create-namespace \
  -f meu-values.yaml

Dica

A primeira instalação pode demorar alguns minutos (imagens, migrations, hooks). Utilize --wait com um timeout adequado (por exemplo --timeout 15m) para evitar falha prematura do Helm.

Acesso

O acesso à interface web do Airflow é feito através de um Service Kubernetes, normalmente do tipo ClusterIP.

Para acesso local durante validação ou testes:

Terminal input

kubectl -n <namespace> port-forward svc/<release>-api-server 8080:8080

Configuração da base de dados

O Airflow precisa de uma base de dados relacional para armazenar os seus metadados: DAGs registados, histórico de execuções, ligações, variáveis e utilizadores.

Sem uma base de dados estável, o Airflow não consegue manter o histórico e os metadados que tornam o serviço utilizável no dia a dia.

Por isso, a escolha entre PostgreSQL incorporado e externo é uma das primeiras decisões de configuração:

• o PostgreSQL incorporado simplifica a instalação inicial;
• o PostgreSQL externo costuma ser preferido quando o ambiente já possui padrões próprios de cópia de segurança, disponibilidade e administração de base de dados.

Para perceber quando utilizar cada opção, consulte PostgreSQL interno versus externo na página de Configuração Geral.

PostgreSQL incorporado (predefinição)

Indicado apenas para desenvolvimento e testes:

tdp-airflow:
  postgresql:
    enabled: true

Atenção

Para produção, prefira PostgreSQL externo.

PostgreSQL externo

Desative a base de dados incorporada e indique os dados de ligação do PostgreSQL externo. Na prática, trata-se do cenário mais comum quando o cliente já utiliza um PostgreSQL da própria plataforma ou um serviço de base de dados administrado separadamente.

Para os helpers de integração TDP:

tdp-airflow:
  postgresql:
    enabled: false

  data:
    metadataSecretName: "<release>-airflow-database"
    metadataConnection:
      user: airflow
      pass: ""
      protocol: postgresql
      host: "<postgres-service>.<namespace>.svc.cluster.local"
      port: 5432
      db: airflow
      sslmode: disable

TDPConfigurations:
  externalDatabase:
    enabled: true
    recreate: false
    externalSecret:
      releaseName: "<tdp-postgresql-release>"
      area: "<area>"

Com TDPConfigurations.externalDatabase.enabled: true, o chart utiliza o release e a área indicados para alinhar base de dados, utilizador e Secret de metadados à stack TDP.

Dica

Prefira definir metadataSecretName e deixar pass vazio quando os jobs TDP forem responsáveis por gerar o Secret de ligação.

Autenticação LDAP

O LDAP é opcional e vem desativado por predefinição.

Enquanto estiver desativado, não há dependência de diretório corporativo nem necessidade de Secrets adicionais para esse fim. Ao ativar o LDAP, a autenticação do Airflow passa a depender das definições do diretório da organização, como servidor, base de pesquisa, utilizadores e variáveis sensíveis armazenadas em Secret.

A configuração utiliza tdp-airflow.ldap e variáveis injetadas via tdp-airflow.extraEnv.

Documentação detalhada

Consulte Segurança — Airflow para Secret de bind e exemplos de configuração LDAP.

Persistência de DAGs (PVC)

Os DAGs precisam de ficar disponíveis para os componentes que orquestram e executam os fluxos. Por isso, esta secção trata menos de «armazenar ficheiros» e mais de garantir que o Airflow consiga encontrar os DAGs de forma estável no ambiente.

Por predefinição o chart já cria PVC para DAGs. Ajuste tamanho, StorageClass ou modo de acesso conforme o cluster:

tdp-airflow:
  dags:
    persistence:
      enabled: true
      size: 5Gi
      storageClassName: ""
      accessMode: ReadWriteOnce

Modo de acesso

Com KubernetesExecutor, vários pods precisam de ler os mesmos DAGs.

Se o scheduler, webserver e tasks não partilharem o volume, utilize uma StorageClass com ReadWriteMany (RWX), conforme permitido pelo ambiente.

Persistência de logs (PVC)

Por predefinição os logs não ficam em PVC partilhado. Isto simplifica a instalação inicial e evita depender de um tipo específico de armazenamento logo na primeira utilização.

Na prática, com enabled: false, a retenção dos logs depende da estratégia de observabilidade já adotada no ambiente. Com enabled: true, o cluster precisa de oferecer um volume compatível com escrita por vários componentes.

Predefinição do chart: enabled: false. Se ativar, avalie o modo de acesso ao volume: os logs são escritos por vários componentes e RWO costuma ser inadequado.

tdp-airflow:
  logs:
    persistence:
      enabled: false
      size: 10Gi
      storageClassName: ""

Atenção

Com RWO, a persistência de logs costuma ser inadequada.

Prefira RWX ou outra estratégia de logs (por exemplo, stack externa) alinhada com o ambiente.

Ligação S3 (TDP)

Configure esta secção quando o Airflow precisar de aceder ao armazenamento de objetos do cluster — por exemplo, para que os DAGs fiquem armazenados no Apache Ozone em vez de em PVC, ou para que operadores Airflow leiam e gravem ficheiros no storage compatível com S3.

Para perceber o conceito e quando a ligação S3 é necessária, consulte Armazenamento compatível com S3 (Ozone) na página de Configuração Geral.

Com TDPConfigurations.s3Connection.enabled: true, o chart cria um Secret com parâmetros de ligação compatíveis com S3 para integrações TDP. Utilize placeholders; não versione credenciais em texto simples:

TDPConfigurations:
  s3Connection:
    enabled: true
    secretName: "<s3-connection-secret>"
    name: "<connection-name>"
    type: "aws"
    accessKey: "<s3-access-key>"
    secretKey: "<s3-secret-key>"
    uri: "https://<s3-endpoint>"

Variáveis de ambiente adicionais

Utilize tdp-airflow.extraEnv para referenciar Secrets ou injetar outras variáveis (por exemplo, palavra-passe LDAP):

tdp-airflow:
  extraEnv: |
    - name: EXAMPLE_ENV
      valueFrom:
        secretKeyRef:
          name: <secret-name>
          key: <secret-key>

Dependências Python e imagem

Com KubernetesExecutor, cada task corre num pod novo.

Instalar pacotes via init container em cada deploy pode aumentar muito o tempo de arranque.

A abordagem habitual em produção é imagem personalizada com dependências já instaladas; defina a mesma imagem em tdp-airflow.images.airflow e tdp-airflow.images.pod_template.

Para opções adicionais (hooks, imagens), consulte a exportação de valores do pacote (helm show values) e a documentação do chart upstream do Apache Airflow.

Parâmetros principais

A tabela seguinte resume os parâmetros mais consultados durante a configuração do Airflow. Utilize-a como referência rápida para rever o que foi alterado em relação ao padrão do componente.

Numa primeira revisão, os pontos que normalmente merecem maior atenção são: base de dados, persistência de DAGs e logs, autenticação LDAP e integrações com serviços partilhados da plataforma.

Parâmetro	Descrição	Valor por omissão
tdp-airflow.enabled	Ativa o deploy do Airflow	true
tdp-airflow.executor	Executor	KubernetesExecutor
tdp-airflow.config.core.default_timezone	Fuso horário predefinido	America/Sao_Paulo
tdp-airflow.apiServer.service.type	Tipo do Service da interface web do Airflow	ClusterIP
tdp-airflow.postgresql.enabled	PostgreSQL incorporado	true
tdp-airflow.dags.persistence.enabled	PVC de DAGs	true
tdp-airflow.dags.persistence.size	Tamanho do PVC de DAGs	5Gi
tdp-airflow.logs.persistence.enabled	PVC de logs	false
tdp-airflow.logs.persistence.size	Tamanho do PVC de logs	10Gi
tdp-airflow.ldap.enabled	LDAP	false
tdp-airflow.ldap.apiServerConfig	Trecho Flask-AppBuilder	Ver helm show values para a versão em utilização
tdp-airflow.extraEnv	Variáveis extra (ex.: Secret)	""
tdp-airflow.data	Metadados / BD externa	Desativado por predefinição; estrutura em helm show values
TDPConfigurations.externalDatabase.enabled	Helpers BD externa TDP	false
TDPConfigurations.s3Connection.enabled	Secret de ligação S3 TDP	false