Usando o Apache Airflow™ com a Cortex Code CLI¶

O Cortex Code oferece suporte interno para o Apache Airflow™, fornecendo uma interface em linguagem natural para gerenciar DAGs, depurar falhas, criar pipelines, analisar dados e rastrear a linhagem em suas implantações do Airflow.

Recursos¶


Recurso	Descrição	Exemplo de prompt
Monitoramento de pipelines	Verificações de integridade, inspeção de DAG, visibilidade de conexão e de variáveis, controle de agendamento	«Minha instância do Airflow é íntegra?»
Gerenciamento de execuções	Acionar DAGs sob demanda, aguardar resultados, passar uma configuração personalizada	«Teste o DAG daily_etl e me avise quando terminar»
Depuração de falhas	Análise de causa raiz em estado de execução, instâncias de tarefas e logs com avaliação de impacto e recomendações de correção	«Por que my_pipeline falhou a noite passada?»
Criação de DAG	Criação de DAG guiada usando seus padrões, conexões e provedores existentes com um fluxo de trabalho descobrir-planejar-implementar-validar-testar	«Crie um DAG para extrair do Snowflake e carregar no S3 diariamente»
Análise de dados	Consultas de warehouse, criação de perfil de tabela e verificações de atualização com cache de padrão e aprendizado de conceito para tabela	«Quantos clientes ativos temos este trimestre?»
Linhagem de dados	Rastreamento de origem upstream e análise de impacto downstream por meio do código-fonte do DAG com classificações de criticidade	«O que pode ser prejudicado se eu alterar o esquema da tabela de clientes?»
Migração do Airflow 3	Migração automatizada de código com regras Ruff , correções de importação, substituições de chaves de contexto e atualizações de padrões de acesso a metadados	«Migre meus DAGs do Airflow 2 para o Airflow 3»
Integração do dbt	Execução de projetos dbt Core ou Fusion como DAGs do Airflow via Astronomer Cosmos com análise, execução e configuração de perfil	«Configure meu projeto dbt para execução no Airflow usando Cosmos»
Human-in-the-Loop	Portões de aprovação, entradas de formulário e ramificação orientada por humanos em DAGs (Airflow 3.1 ou superior)	«Adicione uma etapa de aprovação antes da tarefa de implantação»
Ambientes locais	Iniciar, parar, reiniciar e solucionar problemas de ambientes Airflow locais com a Astro CLI	«Inicie meu ambiente Airflow local»

Pré-requisitos¶

A integração do Cortex Code ao Airflow requer o uv. Se o uv não estiver instalado,o cortex airflow mostrará uma mensagem útil com o link de instalação.

Configurando a integração do Airflow¶

Antes de gerenciar sua instância do Airflow com o Cortex Code, você deve configurar uma conexão. Você pode fazer isso usando variáveis de ambiente ou com um comando de configuração interativo na Cortex Code CLI.

Configuração de variável de ambiente

Exporte as variáveis necessárias em seu shell antes de iniciar o Cortex Code, da seguinte forma. Você pode usar a autenticação baseada em token ou a autenticação com nome de usuário/senha. Se você sempre usa a mesma instância do Airflow, inclua um código como este no perfil do shell (~/.bashrc ou ~/.zshrc) para evitar ter que inseri-lo novamente toda vez.

# Token auth
export AIRFLOW_API_URL=https://airflow.example.com
export AIRFLOW_AUTH_TOKEN=your-api-token

# Username/password auth
export AIRFLOW_API_URL=https://airflow.example.com
export AIRFLOW_USERNAME=your-username
export AIRFLOW_PASSWORD=your-password

Configuração interativa

Emita /airflow no Cortex Code para gerenciar instâncias usando a UI em tela cheia. As autenticações tanto por token quanto com nome de usuário/senha são compatíveis.


Comando	Descrição
`/airflow`	Gerenciar instâncias do Airflow (abre o gerenciador de instâncias)
`/airflow show`	Mostrar a configuração atual (os segredos são mascarados)
`/airflow clear`	Remover toda a configuração

O /airflow oferece suporte a várias instâncias nomeadas. Use o gerenciador de instâncias para adicioná-las, alternar entre elas ou removê-las.

Comandos da Airflow CLI¶

Use cortex airflow para interagir com sua instância do Airflow usando o terminal, conforme mostrado nos exemplos abaixo.

Verificar a integridade da instância:

cortex airflow health

Listar todos os DAGs:

cortex airflow dags list

Obter detalhes sobre um DAG específico:

cortex airflow dags get my_pipeline

Visualizar o código-fonte do DAG:

cortex airflow dags source my_pipeline

Acionar a execução de um DAG:

cortex airflow runs trigger my_pipeline

Listar as execuções recentes de umDAG:

cortex airflow runs list my_pipeline

Verificar o status da tarefa para uma execução específica:

cortex airflow tasks list my_pipeline <run_id>

Pausar ou retomar um DAG:

cortex airflow dags pause my_pipeline
cortex airflow dags unpause my_pipeline

Emita cortex airflow --help para obter a lista completa de comandos.

Solução de problemas¶

Conexão recusada

Sintoma: operações do Airflow falham com erros de conexão.

Solução: verifique se o URL da sua instância está correto e se o a API do Airflow está acessível. Verifique a configuração atual da sua instância e teste a conectividade com uma verificação de integridade.

Falhas na autenticação

Sintoma: as operações retornam erros 401 ou 403.

Solução: tente as seguintes etapas:

Certifique-se de que seu token ou as credenciais estejam corretos.
Verifique se o token expirou; gere-o novamente, se necessário.
Certifique-se de que o usuário e a função tenham permissões de acesso à API no Airflow.

DAG não encontrado

Sintoma: operações relatam que o DAG não existe.

Solução: verifique se há erros de importação ou análise que possam impedir o carregamento do DAG. Certifique-se de que o ID do DAG corresponda exatamente.

uv não instalado

Sintoma: cortex airflow mostra «cortex airflow requires uv».

Solução: instale o uv do site do uv.