Versão 3.0

Configuração do Airflow

ChartVersion3.0.1TypeapplicationAppVersion3.0.2

CompatibilidadeKubernetes1.32+OpenShift4.19+Rancher2.10.x+

Suporte a recursosLDAPsuportadoS3suportadoExternal DBsuportadoIngresssuportadoGateway APIsuportado

O que é o Apache Airflow?

O Apache Airflow é a ferramenta de orquestração de workflows do TDP. Ele permite criar, agendar e monitorar pipelines de dados definidos como código Python (DAGs), com KubernetesExecutor como executor padrão.

O chart tdp-airflow empacota o Apache Airflow 3.0.2 para Kubernetes.

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

Estrutura de valores (Helm)

Este é um chart umbrella. Todas as opções do Apache Airflow devem ficar agrupadas sob a chave tdp-airflow: (alias da dependência no Chart.yaml).

Respeitar esse prefixo garante que o Helm aplique os valores no subchart correto. Para quem opera com GitOps, isso se reflete diretamente no que o Argo CD aplica — um argocd app diff ou helm template só mostrará CPU, conexões e demais chaves se estiverem aninhadas sob tdp-airflow:.

tdp-airflow:
  apiServer:
    resources:
      requests:
        cpu: "500m"
        memory: "1Gi"

Visão geral

Propriedade	Valor
Chart	`tdp-airflow`
Versão do Airflow	3.0.2
Versão do chart	3.0.1
Executor padrão	`KubernetesExecutor`
Banco de metadados	PostgreSQL embutido por padrão, com opção de PostgreSQL externo
Persistência	DAGs, logs e Triggerer podem usar PVCs
Exposição HTTP	UI/API via Service interno, Ingress ou Gateway API

Páginas relacionadas

Integrações — Airflow — PostgreSQL externo e conexão S3
Segurança — Airflow — LDAP e Secrets
Exposição externa: Ingress e Gateway API — exposição HTTP/HTTPS da UI

Pré-requisitos

Kubernetes 1.32+, Red Hat OpenShift 4.19+ ou Rancher Manager 2.10.x+.
Helm 3.2.0+.
StorageClass disponível quando a persistência de DAGs, logs ou Triggerer estiver habilitada.

Instalação
Parâmetros principais
Detalhes de configuração
Acesso & Segurança
Desinstalação

Instalação

Instalação mínima via registry OCI:

Terminal input

helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-airflow -n <NAMESPACE> --create-namespace --timeout 10m

O arquivo de values adicional — por exemplo 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_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-airflow -n <NAMESPACE> --create-namespace -f <VALUES_FILE> --wait --timeout 15m

Dica

A primeira instalação pode levar alguns minutos (imagens, migrations, hooks). Os flags --wait --timeout 15m aguardam a conclusão dos pods e hooks antes de retornar. Aumente o timeout se o seu cluster for mais lento.

OpenShift

Desde a release 3.0.1, o Airflow é compatível com Red Hat OpenShift 4.19+.

Instalação com ajuste exigido pelas Security Context Constraints do OpenShift:

Terminal input

helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-airflow -n <NAMESPACE> --create-namespace --timeout 10m --set tdp-airflow.securityContexts.containers.runAsNonRoot=true

O parâmetro runAsNonRoot=true é exigido pelas Security Context Constraints (SCCs) do OpenShift.

Para detalhes sobre compatibilidade e ajustes adicionais, consulte Configuração Geral, aba Decisões de ambiente que afetam a configuração, no tópico Compatibilidade do orquestrador e ajustes de segurança.

Parâmetros principais

A tabela a seguir resume os parâmetros mais consultados durante a configuração do Airflow. 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.apiServer.service.ports`	Portas do Service da UI/API	Ver `helm show values`
`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.dags.persistence.storageClassName`	StorageClass do PVC de DAGs	`""`
`tdp-airflow.logs.persistence.enabled`	PVC de logs	`false`
`tdp-airflow.logs.persistence.size`	Tamanho do PVC de logs	`5Gi`
`tdp-airflow.triggerer.persistence.enabled`	PVC do Triggerer	`true`
`tdp-airflow.triggerer.persistence.size`	Tamanho do PVC do Triggerer	`5Gi`
`tdp-airflow.ldap.enabled`	LDAP	`false`
`tdp-airflow.ldap.apiServerConfig`	Trecho Flask-AppBuilder	Ver `helm show values`
`tdp-airflow.extraEnv`	Variáveis extras (ex.: Secret)	`""`
`tdp-airflow.data`	Metadados / DB externo	Desligado por padrão
`TDP-Settings.externalDatabase.enabled`	Helpers DB externo TDP	`false`
`TDP-Settings.externalDatabase.recreate`	Recriar DB/usuário no install/upgrade	`false`
`TDP-Settings.externalDatabase.externalSecret.releaseName`	Release do Secret PostgreSQL externo	`<POSTGRESQL_RELEASE>`
`TDP-Settings.s3Connection.enabled`	Secret de conexão S3 TDP	`false`
`TDP-Settings.s3Connection.secretName`	Nome do Secret S3	`tdp-airflow-minio-connection`
`TDP-Settings.s3Connection.uri`	URI do endpoint S3	`https://<S3_ENDPOINT>`
`TDP-Settings.gateway.ingress.enabled`	Habilita Ingress	`false`
`TDP-Settings.gateway.gatewayApi.enabled`	Habilita Gateway API	`false`

Configuração padrão

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)

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-Settings:
  externalDatabase:
    enabled: true
    recreate: false
    externalSecret:
      releaseName: "<POSTGRESQL_RELEASE>"

tdp-airflow:
  postgresql:
    enabled: false

  data:
    metadataSecretName: "<RELEASE_NAME>-airflow-database"
    metadataConnection:
      user: airflow
      pass: ""
      protocol: postgresql
      host: "<POSTGRESQL_SERVICE>.<NAMESPACE>.svc.cluster.local"
      port: 5432
      db: airflow
      sslmode: disable

Com TDP-Settings.externalDatabase.enabled: true, o chart utiliza o release informado 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.

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: ""

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: 5Gi

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.

Persistência do Triggerer (PVC)

O Triggerer é um componente de Airflow 2.2+ responsável por gerenciar eventos e execuções assíncronas de tasks. Por padrão, armazena logs de heartbeats em um PVC separado.

O padrão do chart é:

tdp-airflow:
  triggerer:
    persistence:
      enabled: true
      size: 5Gi

Ajuste o tamanho e a StorageClass conforme necessário, seguindo as mesmas recomendações de Armazenamento descrito em Configuração Geral.

Conexão S3 (TDP)

Configure esta seção quando integrações TDP precisarem de parâmetros de conexão S3-compatible. A configuração s3Connection cria ou referencia um Secret com esses parâmetros; ela não substitui, por si só, a configuração de persistência de DAGs.

O conceito usado pela plataforma está detalhado na página Configuração Geral, aba Decisões de ambiente que afetam a configuração, no tópico Armazenamento S3-compatível (Ozone, MinIO ou outro endpoint).

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

TDP-Settings:
  s3Connection:
    enabled: true
    secretName: "<S3_SECRET_NAME>"
    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>

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_NAME>-api-server 8080:8080

Para exposição externa estável por Ingress ou Gateway API, consulte Exposição externa: Ingress e Gateway API.

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.

Desinstalação

Para remover a instalação do Airflow:

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>

Este comando remove todos os recursos do release (pods, services, configmaps, secrets). Os PVCs (volumes) são mantidos por padrão para preservar os dados. Se deseja remover também os PVCs:

Terminal input

kubectl delete pvc -n <NAMESPACE> -l app.kubernetes.io/instance=<RELEASE_NAME>

O que é o Apache Airflow?​

Estrutura de valores (Helm)​

Visão geral​

Páginas relacionadas​

Pré-requisitos​

Instalação​

OpenShift​

Parâmetros principais​

Configuração padrão​

Configuração do banco de dados​

PostgreSQL embutido (padrão)​

PostgreSQL externo​

Persistência de DAGs (PVC)​

Persistência de logs (PVC)​

Persistência do Triggerer (PVC)​

Conexão S3 (TDP)​

Variáveis de ambiente adicionais​

Acesso​

Autenticação LDAP​

Desinstalação​

O que é o Apache Airflow?

Estrutura de valores (Helm)

Visão geral

Páginas relacionadas

Pré-requisitos

Instalação

OpenShift

Parâmetros principais

Configuração padrão

Configuração do banco de dados

PostgreSQL embutido (padrão)

PostgreSQL externo

Persistência de DAGs (PVC)

Persistência de logs (PVC)

Persistência do Triggerer (PVC)

Conexão S3 (TDP)

Variáveis de ambiente adicionais

Acesso

Autenticação LDAP

Desinstalação