Pular para o conteúdo principal

Prompts

Prompts são flags e opções predefinidas, específicas de cada tipo de template, que você pode ativar para permitir a personalização em tempo de execução. Diferentemente das Variáveis de Survey, que são campos personalizados criados por você, os prompts são opções integradas que correspondem a flags de CLI específicas do Ansible, Terraform e outras ferramentas.

Esse recurso permite:

  • Substituir os padrões do template em tempo de execução
  • Direcionar hosts ou recursos específicos
  • Controlar o comportamento da execução com flags de CLI
  • Passar opções de execução por chamadas de API ou agendamentos

Prompts vs. Variáveis de Survey​

RecursoPromptsVariáveis de Survey
DefiniçãoOpções predefinidas específicas do templateCampos personalizados criados por você
ExemplosAnsible: --limit, --tags
Terraform: workspaces, -destroy		Nome do ambiente, número da versão, parâmetros personalizados
ConfiguraçãoAtivadas por caixas de seleção no templateAdicionadas nas configurações do template com nome e tipo
Passadas comoFlags de CLI integradasAnsible: --extra-vars
Terraform: -var

Os Prompts são opções padronizadas integradas ao Semaphore para ferramentas específicas, enquanto as Variáveis de Survey são campos personalizados flexíveis que você mesmo define.

Prompts do Ansible​

Para templates de playbook do Ansible, você pode ativar prompts para as seguintes opções de CLI:

Limit​

Ative o prompt --limit para especificar quais hosts serão o alvo ao executar o playbook.

Equivalente na CLI: ansible-playbook playbook.yml --limit webservers

Casos de uso:

  • Executar o playbook em um subconjunto de hosts do inventory
  • Direcionar servidores específicos para o deploy
  • Testar alterações em um único host antes de aplicá-las em todos

Exemplo:

  • Seu inventory contém 50 servidores web
  • Ative o prompt Limit
  • Ao executar a tarefa, especifique web-01.example.com para direcionar apenas esse servidor
  • Ou especifique webservers:&production para direcionar os servidores web de produção

Tags​

Ative o prompt --tags para executar apenas as tarefas com tags específicas.

Equivalente na CLI: ansible-playbook playbook.yml --tags deploy,restart

Casos de uso:

  • Executar apenas partes específicas de um playbook
  • Executar as etapas de deploy sem as tarefas de configuração
  • Reiniciar serviços rapidamente sem executar o playbook completo

Exemplo:

---
- hosts: all
  tasks:
    - name: Install packages
      apt:
        name: nginx
      tags: install

    - name: Deploy application
      copy:
        src: app.tar.gz
        dest: /opt/app/
      tags: deploy

    - name: Restart service
      service:
        name: nginx
        state: restarted
      tags: restart

Ative o prompt Tags e informe deploy,restart para pular a etapa de instalação.

Skip Tags​

Ative o prompt --skip-tags para pular as tarefas com tags específicas.

Equivalente na CLI: ansible-playbook playbook.yml --skip-tags testing,debug

Casos de uso:

  • Pular tarefas opcionais em produção
  • Excluir tarefas de depuração ou de teste
  • Ignorar tarefas demoradas quando não forem necessárias

Exemplo: Usando o playbook acima, ative Skip Tags e informe install para pular a instalação de pacotes e executar apenas as tarefas de deploy e reinicialização.

Ativando os prompts do Ansible​

Para ativar os prompts do Ansible:

  1. Vá em Templates de Tarefa e selecione o seu template do Ansible
  2. Localize a seção Ansible Prompts nas configurações do template
  3. Marque as caixas de seleção dos prompts que você deseja:
    • ☐ Limit - Ativa a flag --limit
    • ☐ Tags - Ativa a flag --tags
    • ☐ Skip Tags - Ativa a flag --skip-tags
  4. Salve o template

Quando ativados, esses campos aparecem no formulário de execução da tarefa, nas requisições de API e nas configurações de agendamento.

Prompts do Terraform/OpenTofu​

Para templates do Terraform e do OpenTofu, o Semaphore oferece vários prompts integrados:

Seleção de workspace​

Selecione qual workspace do Terraform será usado na execução da tarefa.

Equivalente na CLI: terraform workspace select staging

Casos de uso:

  • Gerenciar vários ambientes (dev, staging, produção)
  • Separar arquivos de estado para configurações diferentes
  • Testar alterações de infraestrutura de forma isolada

Configuração:

  1. Crie os workspaces na aba Workspaces do template
  2. O seletor de workspace aparece automaticamente no formulário da tarefa
  3. Os usuários escolhem o workspace de destino ao executar as tarefas

Consulte Workspaces do Terraform para a configuração detalhada.

Flag Destroy​

Ative a flag -destroy para desmontar a infraestrutura.

Equivalente na CLI: terraform apply -destroy

Casos de uso:

  • Limpar ambientes de teste temporários
  • Desativar infraestrutura
  • Remover recursos específicos

Importante: Esta é uma operação destrutiva. Use com cautela e considere exigir confirmação nos seus fluxos de trabalho.

Flag Migrate State​

Ative a flag -migrate-state ao alterar a configuração do backend.

Equivalente na CLI: terraform init -migrate-state

Casos de uso:

  • Mover o estado para um backend diferente
  • Migrar entre locais de armazenamento
  • Atualizar a configuração do backend

Ativando os prompts do Terraform​

Os prompts do Terraform estão disponíveis nas configurações do template:

  1. Vá em Templates de Tarefa e selecione o seu template do Terraform
  2. Configure os prompts disponíveis nas configurações do template:
    • Seleção de workspace (ativada automaticamente se houver workspaces configurados)
    • Opção da flag destroy
    • Opção migrate state
  3. Salve o template

O formulário da tarefa exibe essas opções ao executar tarefas do Terraform.

Prompts do Bash, PowerShell e Python​

Para templates do Bash, PowerShell e Python, os prompts são mínimos, pois a maior parte da personalização é feita por meio de Variáveis de Survey.

Os prompts disponíveis são:

  • CLI args
  • Branch

Esses tipos de template se beneficiam mais de Variáveis de Survey personalizadas para passar parâmetros aos scripts.

Usando os prompts​

Execução manual de tarefas​

Ao executar uma tarefa a partir de um template com prompts ativados:

  1. Clique em Run no template
  2. Um formulário aparece com os campos dos prompts ativados
  3. Preencha os valores dos prompts que deseja usar (os campos opcionais podem ficar vazios)
  4. Clique em Run Task

A tarefa é executada com os valores de prompt especificados, passados como flags de CLI.

Chamadas de API​

Para passar valores de prompt pela API, inclua-os no payload da requisição:

Exemplo com Ansible:

curl -XPOST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "template_id": 123,
    "limit": "webservers",
    "tags": "deploy,restart",
    "skip_tags": "testing"
  }' \
  https://your-semaphore.com/api/project/1/tasks

Importante: Os prompts precisam estar ativados no template para que os valores sejam aceitos. Se você passar valores de prompt pela API sem ativá-los, esses valores serão ignorados.

Tarefas agendadas​

Os agendamentos podem incluir valores de prompt para personalizar a execução automatizada de tarefas:

Exemplo: Agendamento com prompts do Ansible

  • Agendamento de deploy diário com limit: "production" e tags: "deploy"
  • Agendamento de manutenção semanal com tags: "updates,cleanup"

Configure os valores dos prompts nas configurações do agendamento para que cada execução agendada use as opções especificadas.

Integrações e webhooks​

As integrações podem extrair valores de webhooks e mapeá-los para prompts:

Exemplo: Um webhook do GitHub aciona o deploy

  • Extraia o nome do branch do webhook
  • Mapeie-o para o prompt Limit para direcionar um ambiente específico
  • Faça o deploy apenas nos servidores correspondentes ao ambiente do branch

Consulte Integrações para a configuração de webhooks.

Boas práticas​

Ative apenas os prompts necessários​

Cada prompt ativado adiciona um campo ao formulário da tarefa. Ative apenas os prompts que os usuários realmente precisarão personalizar.

✅ Bom: Ativar Limit para equipes de operações que precisam direcionar hosts específicos ❌ Ruim: Ativar todos os prompts "por precaução"

Combine com Variáveis de Survey​

Use prompts para as opções de CLI específicas da ferramenta e Variáveis de Survey para parâmetros personalizados:

Exemplo de template do Ansible:

  • Prompts: Limit (quais hosts), Tags (quais tarefas)
  • Variáveis de Survey: app_version (qual versão), enable_rollback (lógica personalizada)

Documente o uso da API​

Se os templates forem acionados pela API, documente quais prompts estão disponíveis e o formato esperado:

## API Usage

Enabled prompts:
- `limit`: Host pattern (optional)
- `tags`: Comma-separated tag list (optional)

Example:
POST /api/project/1/tasks
{
  "template_id": 123,
  "limit": "webservers:&production",
  "tags": "deploy"
}

Use Limit para testes seguros​

Sempre teste playbooks potencialmente destrutivos primeiro com o prompt Limit:

  1. Ative o prompt Limit no template
  2. Primeira execução: especifique limit: "test-server-01" para testar em um único host
  3. Verifique o sucesso
  4. Segunda execução: especifique limit: "production" para aplicar em todos os hosts

Valide as combinações de prompts​

Algumas combinações de prompts podem não fazer sentido. Adicione documentação ou validação:

  • Usar --tags deploy junto com --skip-tags deploy gera conflito
  • Especificar workspace e a flag destroy ao mesmo tempo exige cautela extra

Casos de uso comuns​

Implantação gradual com Limit​

Faça o deploy em produção gradualmente usando o Limit do Ansible:

  1. Execução 1: limit: "web-01.example.com" - Deploy em um servidor
  2. Monitore possíveis problemas
  3. Execução 2: limit: "webservers:&canary" - Deploy nos servidores canary
  4. Valide as métricas
  5. Execução 3: limit: "webservers:&production" - Implantação completa

Execução seletiva com Tags​

Use Tags para executar apenas partes específicas de um playbook:

Manhã: tags: "deploy" - Deploy da nova versão Tarde: tags: "config" - Atualização da configuração Noite: tags: "restart" - Reinicialização dos serviços com a nova configuração

Gerenciamento de ambientes com Workspaces​

Use a seleção de workspace do Terraform para gerenciar ambientes:

  • Desenvolvimento: selecione o workspace dev - recursos mais baratos, iteração mais rápida
  • Staging: selecione o workspace staging - semelhante à produção, para testes
  • Produção: selecione o workspace prod - infraestrutura de produção completa

Limpeza com Destroy​

Use o destroy do Terraform para infraestrutura temporária:

  1. Crie o ambiente de teste: execute com o workspace test-branch-123
  2. Execute os testes de integração
  3. Limpe: execute com a flag destroy ativada e o workspace test-branch-123

Solução de problemas​

Valores de prompt ignorados​

Problema: Os valores de prompt são passados, mas não têm efeito

Solução: Verifique se o prompt correspondente está ativado nas configurações do template. Os prompts precisam ser ativados explicitamente.

Não é possível especificar o limit​

Problema: O campo Limit não aparece no formulário da tarefa

Solução:

  1. Edite o template
  2. Localize a seção "Ansible Prompts"
  3. Marque a caixa de seleção "Limit"
  4. Salve o template

Chamadas de API falham com valores de prompt​

Problema: Requisições de API com valores de prompt retornam erros

Solução:

  1. Certifique-se de que os prompts estão ativados no template
  2. Verifique a formatação do JSON no corpo da requisição
  3. Confira se os nomes dos campos correspondem exatamente (limit, e não host_limit)

Tags não filtram as tarefas​

Problema: As tags são especificadas, mas todas as tarefas continuam sendo executadas

Solução:

  1. Verifique se as tarefas do playbook têm as tags definidas corretamente
  2. Confira se há erros de digitação nos nomes das tags
  3. Certifique-se de que as tags estão separadas por vírgula, sem espaços: deploy,restart, e não deploy, restart