Runbooks

Abrir na plataforma

Um runbook é o script que os seus agentes executam. É a sua biblioteca de tarefas prontas: reiniciar um serviço, limpar disco, criar um usuário, resetar uma sessão. Cada runbook é Python ou Ansible, e fica disponível para os agentes do seu tenant.

Acesse por DevOps → Runbooks.

Quem usa

• SRE e infra: escreve e mantém a biblioteca de scripts de operação.
• Suporte: usa os runbooks prontos, sob demanda ou por automação, sem precisar acessar cada host na mão.

Como o parâmetro chega no script (nunca como código)

Regra de segurança do módulo: os parâmetros (host, nome do serviço, dados do alerta) entram no runbook como variáveis, nunca como código. O script é fixo, veio do catálogo; o que muda é o dado. Assim, texto que vem de um alerta nunca vira comando executável.

• Python: os parâmetros chegam na variável de ambiente SP1_PARAMS, em JSON.
• Ansible: os parâmetros chegam como extra-vars do playbook.

Quais campos você recebe

Quais dados chegam em SP1_PARAMS depende do gatilho da automação:

Por alerta (Observabilidade) , todos estes campos chegam sozinhos, sem você configurar nada:

Campo	Conteúdo
hostname	host que disparou o alerta
alert_name	nome do alerta
severity	severidade (critical, high, medium, information)
status	problem (disparo) ou recovery (recuperação)
alert_id	identificador do disparo do alerta
tags	tags do alerta, cru (ex.: container=nginx,env=prod); extraia o que precisar no script

Por chamado (Gestão de Serviços) , você escolhe quais campos do chamado enviar, no mapa de parâmetros da automação (cada linha: nome do parâmetro ← campo do chamado). Disponíveis:

Campo do chamado	Conteúdo
ID do chamado	número interno; mapeie-o para poder responder no chamado via API (ver Exemplos → Atender um chamado)
Número / referência	referência exibida ao usuário (ex.: R-000123)
Título	título do chamado
Organização	organização/cliente do chamado
Serviço	serviço da categoria
Subcategoria	subcategoria da categoria
Status	status atual
Prioridade	prioridade

Por agendamento ou manual , não vêm campos de gatilho. Só chegam os parâmetros fixos que você definir (na automação ou no campo do Executar agora).

Parâmetros fixos sempre valem

Além dos campos do gatilho, você pode definir parâmetros fixos na aba Ação da automação (ex.: service=nginx). Eles chegam sempre, em qualquer gatilho, e sobrescrevem um campo de mesmo nome.

Confirmação de identidade (step-up)

Runbook é código que roda dentro do seu ambiente, então criar, editar ou apagar um runbook exige uma confirmação de identidade na hora, além do login. Ao entrar na tela, a plataforma pede um código enviado para o email da sua conta.

O código só é enviado quando você pede (o botão Enviar código), e a confirmação vale pelo resto da sessão, você não repete a cada edição.

A lista

Coluna	Conteúdo
Nome	Identificador do runbook, é o que você seleciona numa automação ou agendamento.
Tipo	Badge Python ou Ansible.
Descrição	Texto livre opcional.
Status	Ativo ou Inativo. Só runbooks ativos entram no catálogo dos agentes.

Criar um runbook

1. Clique em Adicionar runbook.
2. Dê um nome (mesma regra dos agentes: minúsculas, números, ponto, hífen, sublinhado).
3. Escolha o tipo (Python ou Ansible). A plataforma já preenche um modelo mínimo do tipo escolhido.
4. Escreva o script.
5. Salve.

Exemplos por tipo

Python

O script recebe os parâmetros em SP1_PARAMS (JSON) e roda dentro do container do agente. Bom para lógica, chamadas de API, manipulação de dados.

Exemplo: reiniciar um serviço via SSH (Linux)

import os
import json
import subprocess

params = json.loads(os.environ.get("SP1_PARAMS") or "{}")
host = params.get("hostname") or params.get("host")
service = params.get("service", "nginx")

# valida a entrada (nunca confie no dado do alerta cru)
if not host or not host.replace(".", "").replace("-", "").isalnum():
    raise SystemExit(f"host invalido: {host!r}")

cmd = ["ssh", f"deploy@{host}", "sudo", "systemctl", "restart", service]
r = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
print(r.stdout)
print(r.stderr)
raise SystemExit(r.returncode)

Segredos ficam no agente

A chave SSH usada acima mora no diretório de trabalho do agente (o -v do docker run), não na plataforma. O runbook só referencia; a credencial nunca sai da sua rede.

Ansible

O script é um playbook. Os parâmetros chegam como extra-vars, e os alvos vêm do inventário configurado no agente. Bom quando você já tem inventário e quer agir em vários hosts de forma idempotente.

Exemplo: reiniciar um serviço (Linux, via inventário)

---
- hosts: all
  gather_facts: false
  tasks:
    - name: Reiniciar o servico
      ansible.builtin.service:
        name: "{{ service | default('nginx') }}"
        state: restarted
      become: true

Ao rodar, mire o host com o parâmetro limit (vira --limit). Numa automação de alerta, mapeie limit para hostname e o playbook roda só no host que disparou.

Exemplo: reiniciar um serviço no Windows (via WinRM)

A imagem do agente já traz as collections do Windows. O inventário aponta para o host Windows com WinRM, e o playbook usa o módulo nativo:

---
- hosts: windows
  gather_facts: false
  tasks:
    - name: Reiniciar o servico do Windows
      ansible.windows.win_service:
        name: "{{ service | default('W3SVC') }}"
        state: restarted

Inventário correspondente (no agente, em inventory.ini):

[windows]
win01 ansible_host=10.0.0.21

[windows:vars]
ansible_connection=winrm
ansible_user=Administrator
ansible_winrm_transport=ntlm
ansible_port=5985

Sem inventário, só localhost

Um playbook Ansible com hosts: all ou hosts: web precisa que esses hosts existam no inventário do agente. Sem inventário, apenas hosts: localhost roda. Um playbook que não casa nenhum host falha com um aviso explicando o que faltou, em vez de terminar em falso "sucesso".

Executar na hora

Para testar um runbook sem esperar gatilho nenhum, use Executar agora no menu da linha: escolha o agente e (opcional) os parâmetros em JSON. O trabalho entra na fila do agente e você acompanha em Execuções.

Próximos passos

• Ligar num gatilho

  ---

  Fazer o runbook rodar sozinho quando um alerta ou chamado acontece.

  Automações

• Agendar

  ---

  Rodar o runbook em horários fixos.

  Agendamentos