Jobs e Steps do Workflow

O Job de um Workflow é um conjunto de ações para uma tarefa específica dentro de um conjunto de diversos outros Jobs para executar um fluxo de trabalho ou processo maior. Cada Job gera um processo que é composto por uma série de passos ou 'Steps' e os processos são executados em uma mesma máquina / runner. Os Jobs são executados em paralelo, a menos que exista dependência entre eles. Cada Job pode conter um ou mais Steps.

Cada Step que compõe o Job pode ser de um tipo diferente. O tipo do Step determina se ele executa uma Action, outro Workflow ou aplica um Plugin.

No arquivo do Workflow (workflow.yaml), o campo 'spec:' recebe todos os parâmetros específicos do Workflow como os objetos 'jobs' e 'steps' respectivamente:

Arquivo do Workflow 'workflow.yaml'
schema-version: v1
kind: workflow
metadata:
  name: my-first-workflow
  display-name: my-first-workflow
  description: First creation of a Workflow
  version: 0.0.1
spec:
  type: reusable
  label: Workflow Title
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which runs a action and apply plugin
      steps:
        - id: step_id_1
          label: Step which run action
          name: stackspot/hello-world@1.0.0
          type: action
          inputs:
            const_input: "This is a example of fixed input"
        - id: step_id_2
          label: Step which apply plugin
          name: stackspot/plugin-basic@1.0.0
          type: plugin
          inputs:
            const_input: "This is a example of fixed input"

    - id: job_id_2
      label: Job Which runs another workflow
      depends-on:
        - job_id_1
      steps:
        - id: step_id_1
          name: stackspot/workflow@1.0.0
          type: workflow
          inputs:
            const_input: "This is a example of fixed input"

Campo do Workflow	Descrição
`spec.jobs`	Agrupamentos de tarefas que precisam ser executadas no Workflow.
`spec.jobs[i].id`	Identificador do Job para referência no Workflow, deve seguir o formato snake_case.
`spec.jobs[i].label`	Texto apresentado para o usuário quando o Job estiver executando.
`spec.jobs[i].depends-on`	Lista de outros Jobs dos quais o Job depende. Jobs com dependências resolvidas executam em paralelo.
`spec.jobs[i].when`	Condição para que o Job execute, definida por uma expressão Jinja que deve retornar “true” (case insensitive).
`spec.jobs[i].steps`	Lista de passos que serão executados nos Jobs.
`spec.jobs[i].steps[i].type`	Tipo de passo: “action”, “plugin”, “workflow”, "run" e “suspend”.
`spec.jobs[i].steps[i].workdir`	Diretório onde o Step será executado. Atributo opcional.
`spec.jobs[i].steps[i].id`	Id do passo para referência dentro do Workflow, deve seguir o formato snake_case.
`spec.jobs[i].steps[i].label`	Texto apresentado no Portal quando o Step for exibido.
`spec.jobs[i].steps[i].when`	Condição para execução do Step, definida por uma expressão Jinja.
`spec.jobs[i].steps[i].inputs`	Mapeamento dos valores de inputs a serem passados para a Action/Plugin/Workflow.
`spec.jobs[i].steps[i].name`	Indica qual Action/Plugin/Workflow será executado/aplicado.
`spec.jobs[i].steps[i].generated-connections`	Mapa de conexões geradas pelo Plugin. A chave é o alias da conexão e o valor é o nome indicado pelo usuário.

Criando dependência entre Jobs de Workflows

Os Jobs de um Workflow são executados em paralelo a menos que tenham dependências. Se houver dependências, elas precisam ser resolvidas antes da execução.

Para criar uma dependência entre os Jobs de um Workflow, use o parâmetro **depends-on**. Nele você define em forma de lista os outros Jobs dos quais o Job atual depende.

depends-on: Lista de outros Jobs dos quais o Job atual depende. Disponível apenas para Jobs.

Job de um Workflow que possui dependência com outro Job.
schema-version: v1
kind: workflow
metadata:
  name: my-first-workflow
  display-name: my-first-workflow
  description: First creation of a Workflow
  version: 0.0.1
spec:
  type: reusable
  label: Workflow Title
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  Jobs:
    - id: optional
      label: Optional job
      depends-on:
        - some_job_id
      when: "{{ boolean_input }}"

Dependências de Workflows com o uso do parâmetro `targets`

O uso da opção targets tem as seguintes regras:

Workflow com o target infra tem que ter ao menos um Plugin do tipo infra ou um outro Workflow com o target infra. Se não tiver um target, verifique os Plugins e Workflows da Stack do Workflow que é a dependência.
Workflow com o target app tem que ter ao menos um Plugin do tipo app ou um Workflow com target app. Se não tiver um target app, verifique os Plugins e Workflows da Stack do Workflow que é a dependência.
Workflows do tipo reusable só podem ter dependência de outros Workflows do tipo reusable.
Sempre que um Workflow ou Workflows dentro desse Workflow tiverem o parâmetro targets com o tipo app ou infra definidos, os Plugins do Workflow devem ter como dependência um Plugin do tipo do target.

schema-version: v1
kind: workflow
metadata:
  name: my-create-app-workflow
  display-name: my-create-app-workflow
  description: Creation of a Application
  version: 2.0.0
spec:
  type: reusable
  label: Workflow Title
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which runs a action and apply plugin
      steps:
        - id: step_id_1
          label: Step which run action
          name: stackspot/hello-world@1.0.0
          type: action
          inputs:
            const_input: "This is a example of fixed input"
        - id: step_id_2
          label: Step which apply plugin
          name: stackspot/plugin-basic@1.0.0
          type: plugin
            inputs:
            const_input: "This is a example of fixed input"  

Steps do Workflow

Step do tipo `plugin`

O Step do tipo plugin executa a aplicação de Plugins pelo Job do seu Workflow. Este Step permite que você defina todos os valores que devem ser obtidos pelo Workflow e utilizados durante a aplicação dos Plugins.

Exemplo:

schema-version: v1
kind: workflow
metadata:
  name: my-create-app-workflow
  display-name: my-create-app-workflow
  description: Creation of a Application
  version: 2.0.0
spec:
  type: reusable
  label: Workflow Title
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which apply plugin
      steps:
        - type: plugin
          name: nome-estudio/optional_plugin@1
          id: apply_optional_plugin
          label: Apply optional plugin
          when: "{{ boolean_input }}"
          inputs:
            some_plugin_input: "fixed_value"
            other_plugin_input: "{{ text_input | lower }}"
            input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

type: tipo do Step.
name: nome do Plugin que vai ser aplicado pelo Step. Use o formato: nome-estudio/nome-plugin@1.0.0(versão semântica).

Atenção!

O campo name sempre usa o Studio Qualifier do Plugin. Isto permite que ele seja aplicado dentro ou fora de um Workspace. Saiba mais detalhes sobre o Studio Qualifier de Plugins.

id: id identificador do Step.
label: nome exibido na tela de Atividades no log do Workflow.
when: (Opcional) parâmetro para usar um valor booleano como condicional para execução do Job ou Step.
inputs: preenchimento dos inputs dos Plugins definidos no Workflow. A sintaxe para preenchê-los é:
- nome_do_input: "valor_do_input"

Exemplo:

inputs:
  some_plugin_input: "fixed_value"
  other_plugin_input: "{{ text_input | lower }}"
  input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

Step do tipo `action`

O Step do tipo action executa uma Action em um Job do seu Workflow. Este Step permite que você defina todos os valores que devem ser obtidos pelo Workflow e utilizados durante a execução da Action.

Exemplo:

schema-version: v1
kind: workflow
metadata:
  name: my-create-app-workflow
  display-name: my-create-app-workflow
  description: Creation of a Application
  version: 2.0.0
spec:
  type: reusable
  label: Workflow Title
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  jobs:
    - id: job_id_1
      label: Job which runs a action and apply plugin
      steps:
        - id: action_example
          label: Example of step run action
          name: nome-estudio/nome-da-action@1.0.0
          type: action
            inputs:
            input_1: "This is a example of fixed input"

id: id identificador do Step.
label: nome exibido na tela de Atividades no log do Workflow.
name: nome da Action que o Step vai executar. Use o formato: nome-estudio/nome-action@1.0.0(versão semântica).
type: o tipo do Step.
inputs: preenchimento dos inputs da Action definidos no Workflow. A sintaxe para preenchê-los é:
- nome_do_input: "valor_do_input".

Step do tipo `suspend`

O Step do tipo suspend pausa a execução do Workflow até que alguém aprove para o Workflow continuar. Sempre que a execução de um Workflow é pausada pelo Step do tipo suspend, o responsável pela conta ou Workspace da sua Organização deve aprovar a continuação da execução do Workflow.

Outra forma de continuar a execução de um Workflow suspenso, é executar o comando stk resume workflow em execuções locais ou em etapas pré-configuradas em uma pipeline.

steps:
  - id: example_suspend
    label: Example of step suspend
    type: suspend

id: id identificador do Step.
label: nome exibido na tela de Atividades no log do Workflow.
type: tipo do Step.

Step do tipo `run`

O Step do tipo run executa comandos Shell arbitrários.

O comando no parâmetro script faz a compactação dos arquivos em um arquivo tar.gz
steps:
  - id: step_id_1
    label: Step which say hello
    type: run
    script: |
      tar -czvf archive.tar.gz file1 file2

id: id identificador do Step.
label: nome exibido na tela de Atividades no log do Workflow.
type: tipo do Step.
script: script Shell que vai ser executado pelo Step.

Dica!

Confira como gerar outputs no step do tipo run

Step do tipo `workflow`

O Step do tipo workflow executa outro Workflow publicado em seu Estúdio.

steps:
  - id: step_id_1
    name: nome-studio/nome-workflow@1.0.0
    type: workflow
    inputs:
      input_1: "This is a example of fixed input"

id: identificador do Step.
name: nome do Workflow que o Step vai executar. Use o formato: nome-estudio/nome-workflow@1.0.0(versão semântica).

Atenção!

O campo name sempre usa o Studio Qualifier do Workflow. Isto permite que ele seja executado dentro ou fora de um Workspace. Saiba mais detalhes sobre o Studio Qualifier de Plugins para executar outros Workflows.

type: tipo do Step.
inputs: preenchimento dos inputs do Workflow que vai ser executado. A sintaxe para preenchê-los é:
- nome_do_input: "valor_do_input".

O uso do parâmetro label é opcional para o Step do tipo workflow.

Executar Steps com Strategy Loop

O Strategy Loop no Workflow da StackSpot permite executar um Step repetidamente para cada valor de uma lista fornecida. O Strategy Loop executa o mesmo Step para cada valor da lista, iterando sobre os elementos.

Durante a execução do Strategy Loop, duas variáveis são disponibilizadas automaticamente para uso no Step:

stk_loop_index: Representa a posição atual do elemento na lista.
stk_loop_value: Representa o valor atual do elemento na lista.

Essas variáveis podem ser utilizadas em diferentes partes do Step, como no campo script para personalizar a execução com base no valor atual da iteração.

Exemplo do trecho de um Workflow, demonstrando o uso do Strategy Loop.
jobs:
  - id: job_id
    label: Label do Job
    steps:
      - id: ID do Step
        type: run # Step do tipo 'run'
        label: label do step, imprime as variáveis {{stk_loop_index}} e {{stk_loop_value}}
        strategy:
          loop: input_list # input do tipo lista informado no 'strategy.loop' do Workflow
        script: |
          echo "Script de exemplo que imprime a posição e valor dos itens da lista informada: {{stk_loop_index}} e {{stk_loop_value}}"

Como funciona o Strategy Loop

Definição da lista: A lista que o Strategy Loop recebe pode ser fornecida de duas formas:

Por Input: um input do tipo lista definido no Workflow.

Exemplo de input do tipo lista que recebe uma lista de strings de IPs.
inputs:
  - label: Informe a lista de IPs
    name: ips
    type: list
    add-question: Deseja adicionar mais IPs na lista?
    input:
      type: text
      label: Endereço IP

Neste exemplo, a lista de IPs é fornecida como input do Workflow.
jobs: # Job do StackSpot Workflow
  - id: processar_lista_ips
    label: Processar IPs
    steps: # Step que vai usar a lista 'ips'
      - id: processo_ip
        type: run 
        label: Processar IP {{stk_loop_index}} - {{stk_loop_value}}
        strategy:
          loop: ips # input do tipo lista definido no exemplo anterior
        script: | # execução de um script que utiliza as variáveis do 'strategy.loop'
          echo "IP processado no index {{stk_loop_index}}: {{stk_loop_value}}"

Dica!

O exemplo usa um input do tipo lista com inputs do tipo texto, mas você pode usar qualquer tipo de input suportado pelo input do tipo lista:

text;
int;
object;
required-connection.

Para mais detalhes sobre o input do tipo lista, confira a página de Inputs.

Hardcoded: a lista é definida diretamente no campo strategy.loop do Workflow:

Exemplo de lista de string.
strategy:
  loop:
    - "192.168.0.1"
    - "10.0.0.1"
    - "172.16.0.1"

strategy:
  loop: ["192.168.0.1", "10.0.0.1", "172.16.0.1"]

Criando gatilhos condicionais para Jobs e Steps

Para declarar um gatilho condicional em um Job ou Step, use o parâmetro e when:

when: recebe um input booleano, definido por uma expressão Jinja que deve retornar "true" para que o Job ou Step seja executado. Disponível para Jobs e Steps.

Steps do tipo 'plugin', de um Workflow.
steps:
  - type: plugin
    name: studio/optional_plugin@1
    id: apply_optional_plugin
    label: Apply optional plugin
    when: "{{ boolean_input }}"
    inputs:
      some_plugin_input: "fixed_value"
      other_plugin_input: "{{ text_input | lower }}"
      input_from_other_job: "{{ outputs.some_job.some_action_execution.some_action_output }}"

Isto permite que um Job inteiro ou um Step seja ignorado na execução do Workflow, caso não cumpra alguma condição.

Criando dependência entre Jobs de Workflows

Dependências de Workflows com o uso do parâmetro targets

Steps do Workflow

Step do tipo plugin

Step do tipo action

Step do tipo suspend

Step do tipo run

Step do tipo workflow

Executar Steps com Strategy Loop

Como funciona o Strategy Loop

Criando gatilhos condicionais para Jobs e Steps

Dependências de Workflows com o uso do parâmetro `targets`

Step do tipo `plugin`

Step do tipo `action`

Step do tipo `suspend`

Step do tipo `run`

Step do tipo `workflow`