Exemplos prontos¶
Receitas completas, do zero ao funcionando. Cada uma é pensada para você copiar e ajustar ao seu caso: troque os nomes de host, o serviço e as credenciais, e está pronta. Todas assumem que você já sabe o básico de agentes, runbooks e automações; se ainda não, dá para seguir mesmo assim, os passos são autocontidos.
| Receita | Gatilho | Tipo | Alvo |
|---|---|---|---|
| 1. Reiniciar um serviço no Windows | Alerta | Ansible (WinRM) | Windows |
| 2. Reiniciar um serviço no Linux | Alerta | Python (SSH) | Linux |
| 3. Limpeza de disco agendada | Agendamento | Ansible | Linux |
| 4. Atender um chamado | Chamado | Python | qualquer |
Receita 1: reiniciar um serviço no Windows (do zero)¶
O caso completo: você tem um servidor Windows onde o serviço W3SVC (IIS) às vezes cai, e quer que o monitoramento reinicie sozinho. Vamos do container vazio até a automação disparando.
Passo 1: preparar o inventário no host do agente¶
O agente vai falar com o Windows por WinRM. O inventário e as credenciais moram na máquina do agente, nunca na plataforma. Crie a pasta e o arquivo:
mkdir -p /opt/sp1-agent/secrets
cat > /opt/sp1-agent/secrets/inventory.ini <<'EOF'
[windows]
win01 ansible_host=10.0.0.21
[windows:vars]
ansible_connection=winrm
ansible_user=Administrator
ansible_password=TROQUE_AQUI
ansible_winrm_transport=ntlm
ansible_port=5985
ansible_winrm_server_cert_validation=ignore
EOF
A senha fica só aqui
O ansible_password fica neste arquivo, na máquina do agente. A plataforma nunca recebe. Em produção, prefira um cofre (Ansible Vault) ou uma conta de serviço dedicada com o mínimo de permissão.
Passo 2: subir o agente com a pasta ligada¶
Gere o agente em Administração → Agentes e Identidades → Adicionar agente (o token aparece uma vez, copie). Depois suba o container montando a pasta do inventário no diretório de trabalho:
docker run -d --name sp1-agent \
-e SP1_URL=https://platform.specialone.io \
-e SP1_AGENT_ID=win-agent \
-e SP1_AGENT_SECRET=<token-mostrado-uma-vez> \
-e SP1_TENANT=<codigo-do-tenant> \
-v /opt/sp1-agent/secrets:/opt/sp1-agent/work \
registry.specialone.io/sp1-automation-agent:latest
O -v é o que liga a pasta: o inventory.ini que você criou vira /opt/sp1-agent/work/inventory.ini dentro do agente, e ele acha sozinho. Em segundos o agente aparece como Ativo na lista.
Passo 3: criar o runbook¶
Em DevOps → Runbooks → Adicionar runbook, tipo Ansible, nome restart-windows-service:
---
- hosts: windows
gather_facts: false
tasks:
- name: Reiniciar o servico do Windows
ansible.windows.win_service:
name: "{{ service | default('W3SVC') }}"
state: restarted
register: r
- name: Confirmar que subiu
ansible.windows.win_service_info:
name: "{{ service | default('W3SVC') }}"
register: check
- name: Falhar se nao estiver rodando
ansible.builtin.assert:
that: check.services[0].state == 'started'
fail_msg: "Servico nao voltou a rodar"
success_msg: "Servico ativo apos o restart"
Repare que o playbook já valida: reinicia, consulta o estado e falha se não voltar. Assim a execução só aparece como sucesso quando o serviço está realmente de pé.
Passo 4: montar a automação¶
Em DevOps → Automações → Adicionar → Observabilidade:
- Ação: agente
win-agent, runbookrestart-windows-service. - Gatilho: por alerta. Host
win01, nome do alerta*IIS*ou*W3SVC*, severidade Crítico. - Para mirar só o host que alertou, adicione o parâmetro
limitmapeando o campohostnamedo alerta (assim o--limitrestringe a execução).
Passo 5: validar¶
Antes de esperar um alerta real, use a aba Executar agora com service=W3SVC e veja o log ao vivo. O PLAY RECAP com failed=0 e a mensagem "Servico ativo apos o restart" confirmam. A partir daí, todo alerta que casar o gatilho reinicia o IIS sozinho.
Receita 2: reiniciar um serviço no Linux (por alerta)¶
Mesma ideia da Receita 1, mas em Linux e com Python + SSH, que é útil quando você não quer manter inventário Ansible e prefere um script direto.
Passo 1: chave SSH no agente¶
Na máquina do agente, deixe uma chave que acesse os hosts alvo (usuário com sudo no serviço). Monte a pasta no container igual à Receita 1 (-v /opt/sp1-agent/secrets:/opt/sp1-agent/work), com a chave em /opt/sp1-agent/secrets/id_ed25519.
Passo 2: runbook Python¶
DevOps → Runbooks → Adicionar, tipo Python, nome restart-service:
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 cru do alerta
if not host or not all(c.isalnum() or c in ".-" for c in host):
raise SystemExit(f"host invalido: {host!r}")
ssh = ["ssh", "-i", "/opt/sp1-agent/work/id_ed25519",
"-o", "StrictHostKeyChecking=accept-new",
f"deploy@{host}"]
# reinicia e confirma que o serviço voltou (is-active)
subprocess.run(ssh + ["sudo", "systemctl", "restart", service], check=True, timeout=60)
r = subprocess.run(ssh + ["systemctl", "is-active", service],
capture_output=True, text=True, timeout=30)
print(f"{service} em {host}: {r.stdout.strip()}")
raise SystemExit(0 if r.stdout.strip() == "active" else 1)
Passo 3: automação¶
Observabilidade, agente do Linux, runbook restart-service, gatilho por alerta no grupo web*. Os campos do alerta (hostname, alert_name, severity, etc.) chegam sozinhos em SP1_PARAMS, o script lê o hostname direto.
Passo 4: validar¶
Aba Executar agora com host=web03, service=nginx. O log deve terminar com nginx em web03: active e a execução como concluída.
Receita 3: limpeza de disco agendada¶
Nem toda automação vem de um alerta. Esta roda todo dia de madrugada, sem gatilho de problema, só o relógio.
Passo 1: runbook Ansible¶
DevOps → Runbooks → Adicionar, tipo Ansible, nome disk-cleanup:
---
- hosts: all
gather_facts: false
tasks:
- name: Remover temporarios com mais de 7 dias
ansible.builtin.find:
paths: /tmp
age: 7d
recurse: true
register: velhos
- name: Apagar
ansible.builtin.file:
path: "{{ item.path }}"
state: absent
loop: "{{ velhos.files }}"
loop_control: { label: "{{ item.path }}" }
- name: Resumo
ansible.builtin.debug:
msg: "{{ velhos.files | length }} arquivo(s) removido(s)"
Passo 2: agendar¶
Em DevOps → Job Scheduler → Adicionar:
- Agente: o do ambiente alvo.
- Runbook:
disk-cleanup. - Frequência: Diário, às
03:00, de segunda a sexta.
Cada execução entra na fila do agente na hora marcada e aparece em Execuções. O agendamento também fica listado nos Gatilhos do agente, junto com os alertas e chamados que o acionam.
Centraliza o que estaria em cron espalhado
Em vez de um crontab por máquina (que ninguém audita), a rotina fica num lugar só, com histórico de cada execução e o log do que foi apagado.
Receita 4: atender um chamado (e responder no próprio chamado)¶
A mais completa: um usuário abre um chamado, o agente executa a ação e escreve a resposta de volta no chamado, resolvendo sozinho. Sem risco de segurança, é uma ação operacional comum de mesa de ajuda (reiniciar uma aplicação a pedido).
Como funciona¶
O segredo é que o agente recebe, junto com os dados do chamado, um token de API da plataforma (SP1_API_TOKEN, escopo Service Manager). Com ele, o runbook chama a API do Service Desk e escreve de volta no chamado.
Passo 1: runbook que age e responde¶
DevOps → Runbooks → Adicionar, tipo Python, nome atende-reinicio:
import os
import json
import subprocess
import urllib.request
params = json.loads(os.environ.get("SP1_PARAMS") or "{}")
ticket_id = params.get("ticket_id") # numero do chamado (vem do gatilho)
host = params.get("host", "app02")
service = params.get("service", "app")
# 1) executa a acao pedida
ok = subprocess.run(
["ssh", "-i", "/opt/sp1-agent/work/id_ed25519", f"deploy@{host}",
"sudo", "systemctl", "restart", service],
timeout=60,
).returncode == 0
# 2) responde NO PROPRIO CHAMADO via API da plataforma
api = os.environ["SP1_URL"] + f"/api/v2/itsm/tickets/{ticket_id}"
body = {
"public_log": (f"Servico {service} reiniciado com sucesso em {host}."
if ok else f"Falha ao reiniciar {service} em {host}."),
"status": "resolved" if ok else "assigned",
}
req = urllib.request.Request(
api, data=json.dumps(body).encode(), method="PATCH",
headers={"Authorization": "Bearer " + os.environ["SP1_API_TOKEN"],
"Content-Type": "application/json"},
)
urllib.request.urlopen(req, timeout=30)
print("chamado", ticket_id, "atualizado")
raise SystemExit(0 if ok else 1)
O public_log vira um comentário público no chamado (o solicitante vê), e status: resolved fecha o atendimento. Se falhar, deixa o chamado atribuído pra um humano olhar, em vez de resolver errado.
Passo 2: dar o escopo certo ao agente¶
O agente precisa poder escrever no Service Desk. Em Agentes e Identidades, no menu do agente → Editar permissões, marque Service Manager: Leitura + escrita. Sem isso, a chamada da API é recusada.
Passo 3: automação de chamado¶
Em DevOps → Automações → Adicionar → Gestão de Serviços → Chamado aciona agente:
- Escopo: tipo Requisição, categoria "Reinício de serviço" (a categoria/subcategoria que você usa).
- Agente e runbook: o agente e
atende-reinicio. - Mapa de parâmetros: mapeie o número do chamado para o parâmetro
ticket_id(é o que o runbook usa pra responder de volta).
Passo 4: validar (com segurança)¶
Ligue a automação em modo simulação (dry-run) primeiro: ela mostra quais chamados casariam sem executar nada. Confira o escopo, depois desligue a simulação. Abra um chamado de teste na categoria e acompanhe: em segundos o agente responde no chamado com o comentário e o status resolvido, e a execução aparece em Execuções.
Escolha ações sem risco
Prefira automatizar ações operacionais e reversíveis (reiniciar um serviço, limpar uma fila, recarregar um cache, rodar um diagnóstico e anexar o resultado). Deixe fora do fluxo automático o que é sensível ou irreversível (mexer em permissão, apagar dado, alterar senha), esse tipo de pedido continua passando por um humano.
Próximos passos¶
-
Detalhe dos agentes
Inventário, WinRM, ciclo de vida e segurança do agente.
-
Detalhe das automações
As abas, os agendamentos, as execuções e o relatório.