Tipos Inputs

Tipos de Input

Confira os tipos de Inputs disponíveis no Workflow da StackSpot. Eles são definidos no campo type.

Tipos	Valor
text	String.
textarea	String.
bool	Boolean.
int	Integer.
password	Criptografa o valor informado. (string)
select	Lista os valores, permitindo escolher apenas 1 valor (string).
multiselect	Lista os valores, permitindo escolher 1 ou mais valores (string).
list	Lista de Inputs de um mesmo tipo (text, int, object e required-connection).
object	Armazena um conjunto de Inputs dentro de um objeto. O objeto passa a ser um input pai com um conjunto de inputs filhos.
required-connection	Armazena um conjunto de Inputs necessários para se conectar em uma Infraestrutura dentro de um objeto.
generated-connection	Armazena um conjunto de Inputs necessários para criar uma Infraestrutura dentro de um objeto.

Confira a seguir um exemplo de workflow.yaml do tipo create, que utiliza todos os tipos de input disponíveis na StackSpot. O exemplo mostra como declarar cada tipo de input e como usá-los em steps de jobs, tornando o Workflow pronto para testes e customizações.

schema-version: v1
kind: workflow
metadata:
  name: create-full-inputs-demo
  display-name: Criação Completa com Todos os Inputs
  description: "Exemplo funcional de Workflow StackSpot usando todos os tipos de input."
  version: 1.0.0
spec:
  type: create
  label: "Create Full Inputs Demo"
  targets:
    - app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  inputs:
    - label: "Project Name"
      name: project_name
      type: text
      required: true
      help: "Enter the project name (e.g., my-app)"
    - label: "Project Description"
      name: project_description
      type: textarea
      required: false
      help: "Describe your project"
    - label: "Enable Monitoring?"
      name: enable_monitoring
      type: bool
      required: true
      default: false
      help: "Enable monitoring for this application?"
    - label: "Number of Replicas"
      name: replicas
      type: int
      required: true
      default: 1
      help: "Set the number of application replicas"
    - label: "Database Password"
      name: db_password
      type: password
      required: true
      help: "Enter the database password"
    - label: "Choose Environment"
      name: environment
      type: select
      required: true
      items:
        - dev
        - staging
        - production
      help: "Select the deployment environment"
    - label: "Select Features"
      name: features
      type: multiselect
      required: false
      items:
        - logging
        - monitoring
        - tracing
      help: "Select the features to enable"
    - label: "Allowed IPs"
      name: allowed_ips
      type: list
      add-question: "Add another IP?"
      input:
        type: text
        label: "IP Address"
        pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$'
        help: "Enter an allowed IP address"
    - label: "Database Config"
      name: db_config
      type: object
      inputs:
        - label: "Host"
          name: host
          type: text
          required: true
        - label: "Port"
          name: port
          type: int
          required: true
        - label: "User"
          name: user
          type: text
          required: true
        - label: "Password"
          name: password
          type: password
          required: true
    - label: "Select S3 Connection"
      name: s3_connection
      type: required-connection
      connection-interface-type: aws-s3-conn
      help: "Choose the S3 connection to use"
    - label: "Create S3 Connection"
      name: new_s3_connection
      type: generated-connection
      connection-interface-type: aws-s3-conn
      outputs:
        - from: aws-s3-alias-arn
          to: arn
        - from: aws-s3-alias-bucket_name
          to: bucket_name
      help: "Create a new S3 connection for this workflow"
    - type: import
      label: "Import S3 Starter Inputs"
      from: job_apply_starter.step_apply_starter
      name: s3_starter_inputs
      includes:
        - bucket_name
        - region
      excludes:
        - encryption

  jobs:
    - id: job_apply_starter
      label: "Apply S3 Starter Workflow"
      steps:
        - id: step_apply_starter
          type: workflow
          name: stackspot-cloud/aws-s3-starter-workflow@1
          workdir: storage-infra/stackspot/{{ var.STK_WORKFLOW_EXECUTION_ID }}
          inputs:
            bucket_name: "{{ project_name }}-bucket"
            region: "us-east-1"
            encryption: true
    - id: job_create_app
      label: "Create Application"
      depends-on:
        - job_apply_starter
      steps:
        - id: step_create_app
          type: plugin
          name: fictitious-org/app-create-plugin@1.0.0
          inputs:
            project_name: "{{ project_name }}"
            project_description: "{{ project_description }}"
            enable_monitoring: "{{ enable_monitoring }}"
            replicas: "{{ replicas }}"
            db_password: "{{ db_password }}"
            environment: "{{ environment }}"
            features: "{{ features }}"
            allowed_ips: "{{ allowed_ips }}"
            db_config: "{{ db_config }}"
            s3_connection: "{{ s3_connection }}"
            new_s3_connection: "{{ new_s3_connection }}"
        - id: step_use_imported_inputs
          type: action
          name: fictitious-org/use-imported-inputs-action@1.0.0
          inputs-from:
            - s3_starter_inputs
          inputs:
            extra_param: "example"

Dica!

• Sempre defina os campos obrigatórios: label, name, type.
• Use o tipo de input adequado para cada necessidade.
• Documente cada input com o campo help.
• Utilize objetos e listas para inputs complexos.
• Prefira o tipo import e inputs-from para reaproveitar inputs de outros steps em Workflows.

Confira nesta página os campos obrigatórios dos Inputs com os respectivos exemplos.

Importar Inputs dos conteúdos no Workflow

O Workflow usa nos Steps dos Jobs os Inputs de diferentes conteúdos disponíveis nos Estúdios, como Plugins, Actions e outros Workflows.

Para usar esses inputs, você precisa declarar manualmente os Inputs de cada conteúdo. Se o seu Workflow executa uma Action, aplica um Plugin ou utiliza outro Workflow ao mesmo tempo, é necessário declarar os inputs separadamente para cada um deles.

Para facilitar o uso dos Inputs no seu Workflow, você pode:

• Gerar um input do tipo import para reunir todos os Inputs necessários em um único objeto.
• Usar a opção inputs-from nos Steps do seu Workflow para aproveitar os Inputs importados ou um input do tipo objeto.

Você não precisa declarar cada input separadamente.

Input do tipo import

O Input do tipo import deve ser utilizado apenas em Workflows da StackSpot e possui os campos a seguir:

• type: o tipo do Input. O seu valor deve ser import.
• from: referência dos Inputs que você deseja importar. A referência deve conter a sintaxe: 'job_id.step_id', exemplo: “job_01.step_01”. Os Steps referenciados devem ser do tipo ‘plugin’, ‘action’ ou ‘workflow’.
• label: texto exibido no terminal para o seu Input do tipo import.
• name: nome do input para identificar os Inputs importados.
• includes: campo Opcional. Lista para especificar quais Inputs importar.
• excludes: campo Opcional. Lista para especificar quais Inputs não importar.

Cuidado

Se você não utilizar os campos includes e excludes, todos os Inputs do step que você está referenciando serão importados.

Confira um exemplo de Input do tipo import:

Campo 'inputs' de um workflow.yaml

inputs: 
  - type: import
    label: Add your bucket S3 inputs
    from: job_create_app.step_workflow_starter # steps do tipo action, plugin, workflow
    name: s3_starter_inputs
    includes: # Opcional: importar inputs específicos.
      - bucket_name
      - region
    excludes: # Opcional: excluir inputs específicos.
      - encryption 

Usar campo inputs-from em Steps

O campo inputs-from permite usar inputs importados diretamente no conteúdo de um Step do Workflow. Esses conteúdos podem ser Actions, Plugins e Workflows executados em Steps do mesmo tipo.

Atenção!

Use apenas Inputs do tipo objeto no campo inputs-from. Os objetos que você pode usar são:

• Input do tipo import: ao criar um Input do tipo import, ele gera um objeto com todos os Inputs importados.
• Objeto - input: é um objeto que contém todos os Inputs de um conteúdo.
• Usar um Input do tipo objeto diretamente no campo inputs-from.

Você pode mesclar o uso do de Inputs importados com inputs-from e inputs:

Campo 'steps' de um workflow.yaml

steps:
  - id: call_starter
    type: workflow
    name: stackspot-cloud/aws-s3-starter-workflow@1
    workdir: storage-infra/stackspot/{{ var.STK_WORKFLOW_EXECUTION_ID }}
    inputs-from:
      - s3_starter_inputs
    inputs:
      bucket_encryption: true # Inputs adicionais ou fixos

Usar o objeto Inputs para enviar todos os Inputs de um conteúdo para o Workflow:

Campo 'steps' de um workflow.yaml

steps:
  - id: call_starter
    type: workflow
    name: stackspot-cloud/aws-s3-starter-workflow@1
    workdir: storage-infra/stackspot/{{ var.STK_WORKFLOW_EXECUTION_ID }}
    inputs-from:
      # todos os inputs são repassados para o Workflow sendo chamado
      - inputs

Usar um Input do tipo objeto:

Campo 'steps' de um workflow.yaml

steps:
  - id: call_starter
    type: workflow
    name: test-cloud/aws-s3-starter-workflow@1
    workdir: storage-infra/stackspot/{{ var.STK_WORKFLOW_EXECUTION_ID }}
    inputs-from:
      # todos os campos do input object_input são repassados para o Workflow sendo chamado
      - object_input

Exemplo: Workflow com import de inputs e inputs-from

Confira um exemplo de Workflow StackSpot adaptado para um cenário que utilize o input do tipo import e o recurso inputs-from. O exemplo simula um fluxo comum:

1. Aplicar um Plugin de autenticação,
2. Executar um Workflow de deploy e,
3. Executar um script customizado.

schema-version: v1
kind: workflow
metadata:
  name: workflow-auth-deploy
  display-name: Workflow Auth Deploy
  description: Exemplo de Workflow que importa inputs de um Plugin e Workflow para orquestrar um deploy autenticado.
  version: 1.0.0
spec:
  type: reusable
  label: Deploy com Autenticação
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  inputs:
    - type: import
      label: "Inputs do Plugin de Autenticação"
      from: apply_auth_plugin.apply_auth_plugin_step
      name: auth_plugin_inputs
    - type: import
      label: "Inputs do Workflow de Deploy"
      from: run_deploy_workflow.run_deploy_workflow_step
      name: deploy_workflow_inputs
    - label: Nome do serviço a ser deployado
      name: service_name
      type: text
      required: true
    - label: Ambiente de deploy
      name: environment
      type: select
      items:
        - dev
        - staging
        - prod
      default: dev
      required: true
  jobs:
    - id: apply_auth_plugin
      label: Aplicar Plugin de Autenticação
      steps:
        - id: apply_auth_plugin_step
          label: Step de plugin de autenticação
          name: "studio/plugin-auth@1.0.0"
          type: plugin
          inputs-from:
            - auth_plugin_inputs
    - id: run_deploy_workflow
      label: Rodar Workflow de Deploy
      steps:
        - id: run_deploy_workflow_step
          label: Step de workflow de deploy
          name: "studio/workflow-deploy@1.0.0"
          type: workflow
          inputs-from:
            - deploy_workflow_inputs
    - id: run_custom_script
      label: Executar Script Customizado
      steps:
        - id: run_custom_script_step
          label: Step de execução de script
          type: run
          script: |
            echo "Serviço: {{service_name}}"
            echo "Ambiente: {{environment}}"

Explicação dos inputs importados e reaproveitados:

• auth_plugin_inputs:
  Importa todos os inputs necessários do step apply_auth_plugin_step (do plugin de autenticação).
  Exemplo: usuário, senha, token, etc.

• deploy_workflow_inputs:
  Importa todos os inputs necessários do step run_deploy_workflow_step (do workflow de deploy).
  Exemplo: nome do repositório, branch, configurações de build, etc.

• service_name e environment:
  Inputs próprios deste workflow, preenchidos pelo usuário para customizar o deploy.

• inputs-from:
  Nos steps dos jobs, o campo inputs-from garante que todos os valores importados sejam automaticamente passados para o step correspondente, evitando repetição e facilitando a manutenção.

Dica!

1. Use o tipo import para inputs já definidos em outros steps, plugins ou workflows.
2. Utilize inputs-from para evitar repetição e garantir consistência.