Configuração do Airflow

Para saber mais

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

No arquivo 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 padrão.

Configuração padrão

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

Comportamento por omissão do chart tdp-airflow:

Por padrão, o chart prioriza 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 desses padrões depende da política operacional adotada para banco, armazenamento, autenticação e observabilidade, conforme descrito em Configuração Geral.

• Executor: KubernetesExecutor
• Banco de dados: PostgreSQL embutido (subchart), com tdp-airflow.postgresql.enabled: true por padrão
• DAGs: persistência em PVC habilitada por padrão (tdp-airflow.dags.persistence.enabled: true, tamanho típico 5Gi)
• Logs: persistência em PVC desabilitada por padrão (tdp-airflow.logs.persistence.enabled: false); habilite apenas se o StorageClass atender ao padrão de acesso necessário (em geral RWX)

O comando abaixo representa a forma usual de instalar ou atualizar o Airflow. O arquivo 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 levar alguns minutos (imagens, migrations, hooks). Use --wait com um timeout adequado (por exemplo --timeout 15m) para evitar falha prematura do Helm.

Acesso

O acesso à interface web do Airflow é feito por 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 do banco de dados

O Airflow precisa de um banco de dados relacional para armazenar seus metadados: DAGs registrados, histórico de execuções, conexões, variáveis e usuários.

Sem um banco 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 embutido e externo é uma das primeiras decisões de configuração:

• o PostgreSQL embutido simplifica a instalação inicial;
• o PostgreSQL externo costuma ser preferido quando o ambiente já possui padrões próprios de backup, disponibilidade e administração de banco.

Para entender quando usar cada um, consulte PostgreSQL interno versus externo na página de Configuração Geral.

PostgreSQL embutido (padrão)

Indicado apenas para desenvolvimento e testes:

tdp-airflow:
  postgresql:
    enabled: true

Atenção

Para produção, prefira PostgreSQL externo.

PostgreSQL externo

Desative o banco embutido e informe os dados de conexão do PostgreSQL externo. Na prática, isso é o cenário mais comum quando o cliente já utiliza um PostgreSQL da própria plataforma ou um serviço de banco 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 informados para alinhar banco, usuário 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 conexão.

Autenticação LDAP

LDAP é opcional e vem desligado por padrão.

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

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

Documentação detalhada

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

Persistência de DAGs (PVC)

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

Por padrã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 ler os mesmos DAGs.

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

Persistência de logs (PVC)

Por padrão os logs não ficam em PVC compartilhado. Isso simplifica a instalação inicial e evita depender de um tipo específico de armazenamento logo no primeiro uso.

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 oferecer um volume compatível com escrita por múltiplos componentes.

Padrão do chart: enabled: false. Se habilitar, 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 ao ambiente.

Conexão S3 (TDP)

Configure esta seção quando o Airflow precisar acessar o 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 arquivos no storage S3-compatível.

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

Com TDPConfigurations.s3Connection.enabled: true, o chart cria um Secret com parâmetros de conexão S3-compatível para integrações TDP. Use placeholders; não versione credenciais em texto plano:

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

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

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

Dependências Python e imagem

Com KubernetesExecutor, cada task roda em um pod novo.

Instalar pacotes via init container em todo deploy pode aumentar muito o tempo de subida.

A abordagem usual em produção é imagem customizada 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 a seguir resume os parâmetros mais consultados durante a configuração do Airflow. Use-a como referência rápida para revisar o que foi alterado em relação ao padrão do componente.

Para uma primeira revisão, os pontos que normalmente merecem mais atenção são: banco de dados, persistência de DAGs e logs, autenticação LDAP e integrações com serviços compartilhados da plataforma.

Parâmetro	Descrição	Valor por omissão
tdp-airflow.enabled	Habilita o deploy do Airflow	true
tdp-airflow.executor	Executor	KubernetesExecutor
tdp-airflow.config.core.default_timezone	Fuso padrão	America/Sao_Paulo
tdp-airflow.apiServer.service.type	Tipo do Service da interface web do Airflow	ClusterIP
tdp-airflow.postgresql.enabled	PostgreSQL embutido	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 uso
tdp-airflow.extraEnv	Variáveis extras (ex.: Secret)	""
tdp-airflow.data	Metadados / DB externo	Desligado por padrão; estrutura em helm show values
TDPConfigurations.externalDatabase.enabled	Helpers DB externo TDP	false
TDPConfigurations.s3Connection.enabled	Secret de conexão S3 TDP	false