Ir para o conteúdo
Promovaweb

Flows e tasks em YAML

StayCloudVPS Agêntica

30% off na sua VPS Agêntica nos 2 primeiros meses

A StayCloud aplica o desconto sozinha no plano mensal, sem fidelidade. Suba uma VPS em São Paulo, instale o SetupVibe Desktop e desenvolva com agentes num ambiente que fica ligado o tempo todo.

Aproveitar a Black Friday

Link de parceiro da Promovaweb.

Black Friday até 30/11

30%off

nos 2 primeiros meses do plano mensal da VPS

  • Backup diário grátis para sempre
  • Servidores em São Paulo no datacenter da Ascenty
  • Datacenter Tier III manutenção sem parada
  • Acesso root com disco SSD NVMe
  • Réplica do backup em Ashburn, nos EUA

Um flow do Kestra é um arquivo YAML com as propriedades obrigatórias id e namespace e com a lista de tasks, as ações que ele executa em ordem. As tasks flowable controlam ramificações, laços e paralelismo, enquanto as runnable fazem o trabalho pesado, como consultas, chamadas HTTP e scripts.

Sumário da página

  1. O arquivo descreve a rotina inteira
  2. Runnable e flowable
  3. Inputs, variáveis e outputs
  4. Subflows quebram rotinas grandes
  5. Revisões e rascunhos
  6. O que muda em relação a um script com cron

O arquivo descreve a rotina inteira

Abra um flow do Kestra e você lê a rotina do começo ao fim, sem clicar em caixas para descobrir o que cada uma faz. A documentação define o flow como um container de tasks e da lógica que orquestra essas tasks. Ele precisa de só três propriedades. O id identifica o flow. O namespace diz a qual grupo ele pertence. A lista de tasks traz as ações.

Todo o resto é opcional e entra quando a rotina precisa. Entre as propriedades opcionais da documentação estão os inputs, os triggers, o tratamento de erros, os retries e a concorrência. Uma rotina de backup simples pode ter cinco linhas. Uma sincronização em lote com aviso de falha pode ter cem e continua legível porque cada bloco tem nome e função.

  • id: backup-postgresIdentificador do flow dentro do namespace.
  • namespace: agencia.infraGrupo do flow, com acesso aos arquivos, ao KV Store e aos segredos do grupo.
  • inputs:Valores informados na hora de executar, com tipo e valor padrão.
  • variables:Valores reutilizados nas tasks com {{ vars.nome }}.
  • tasks:A lista de tasks, executadas em ordem.
  • - id: dumpUma task runnable, como um script Shell ou uma consulta SQL.
  • - id: enviarOutra task, que lê a saída da anterior com {{ outputs.dump... }}.
  • errors:Tasks que rodam quando uma task do flow falha.
  • outputs:Valores que o flow devolve ao flow pai ou à chamada da API.
  • triggers:Agenda cron, webhook, fim de outro flow ou evento externo.
As partes de um flow, com os nomes de propriedade da documentação. As três primeiras são obrigatórias. As demais entram conforme a rotina.

Runnable e flowable

As tasks se dividem em dois tipos. A diferença explica muito do comportamento do Kestra. A documentação descreve as tasks runnable como as que fazem o processamento, como uma consulta ao banco ou uma chamada de API. Elas rodam no worker. As tasks flowable controlam a orquestração, como um laço ou dois ramos em paralelo, sem fazer a computação pesada. Elas ficam com o executor.

Na prática, você combina os dois tipos. Um Parallel dispara o backup de cinco bancos ao mesmo tempo, com um limite opcional de quantos rodam juntos. Um If decide se o relatório vai por e-mail ou fica só no armazenamento. Dentro de cada ramo, as tasks runnable fazem o trabalho real.

Task flowableO que controlaQuando aparece numa rotina
SequentialRoda as tasks filhas uma depois da outra, com blocos opcionais de erro e limpeza.Agrupar etapas que dependem umas das outras.
ParallelInicia ramos ao mesmo tempo, com limite opcional de concorrência.Backup de vários bancos ou download de vários relatórios.
If e SwitchEscolhem o ramo pelo valor de uma condição ou de uma expressão.Tratar de um jeito o cliente A e de outro o cliente B.
LoopRepete as tasks para cada item de uma lista ou de um arquivo, cada um numa subexecução.Processar cada linha de um arquivo exportado do ERP.
SubflowInicia outro flow como execução filha, com inputs e espera opcional pelo resultado.Reaproveitar a rotina de aviso em vários flows.
PauseSuspende a execução até a retomada manual ou o fim de um prazo.Esperar a aprovação do gestor antes de publicar.

Inputs, variáveis e outputs

Três mecanismos levam valores de um lugar para outro. Os inputs são valores dinâmicos passados ao flow na hora da execução, com tipo e valor padrão. Quando você executa o flow pela interface, o Kestra monta um formulário com esses campos. Quando um webhook ou outro flow dispara a execução, os valores chegam pela chamada.

As variáveis guardam valores fixos que se repetem nas tasks, como o nome de um bucket ou o endereço de uma API. As tasks leem cada uma com uma expressão entre chaves duplas, no formato {{ vars.nome }}.

Os outputs carregam o resultado de uma task para as seguintes. A task HTTP Request, por exemplo, guarda o status, o corpo e os cabeçalhos da resposta. A task seguinte lê o corpo com {{ outputs.id_da_task.body }}. O flow também pode declarar outputs próprios, que voltam ao flow pai quando ele roda como subflow. Arquivos grandes, como o dump de um banco, ficam no armazenamento interno. As tasks passam adiante só a referência ao arquivo.

Subflows quebram rotinas grandes

Quando a mesma sequência aparece em vários flows, ela vira um flow próprio, chamado pela task Subflow. O aviso de falha com mensagem no Discord, a compactação e o envio de um arquivo para o S3 e a verificação de espaço em disco são exemplos de pedaços que se repetem. Cada subflow tem inputs e outputs, como uma função. A execução filha aparece ligada à execução que a chamou.

Isso mantém cada arquivo curto e com um propósito só. Você corrige o aviso de falha num lugar. Na execução seguinte, todos os flows que o chamam já usam a versão nova.

Revisões e rascunhos

Cada alteração gravada num flow cria uma revisão nova. O Kestra guarda o histórico de forma automática, num esquema parecido com o controle de versão. A opção de rascunho prepara as mudanças sem afetar as execuções em andamento. A revisão em rascunho só roda depois de publicada.

Esse histórico não substitui o Git, mas resolve a pergunta mais comum depois de uma falha: o que mudou no flow desde a última execução bem-sucedida. A comparação das revisões responde sem abrir o servidor.

O que muda em relação a um script com cron

Um script Shell chamado pelo cron faz o mesmo backup, mas carrega sozinho a ordem das etapas, o tratamento de erro, as novas tentativas e o registro do que aconteceu. No flow, cada uma dessas responsabilidades tem uma propriedade com nome. A ordem está na lista de tasks, o paralelismo num Parallel, as tentativas num bloco retry e o aviso de falha na lista errors. O script continua existindo, agora como uma task. O Kestra cuida do resto.

O hub seguinte mostra o que coloca um flow para rodar: os triggers e as agendas.