Agentes de automação

Abrir na plataforma

O agente de automação é quem coloca as suas automações em prática dentro do ambiente: um serviço leve, empacotado como container Docker, que recebe da plataforma o que precisa ser feito e executa os seus runbooks ali mesmo, na sua rede. Ele faz só conexão de saída para a plataforma (nunca abre porta de entrada) e mantém os segredos locais (chave SSH, senha de banco) com você, sem nunca mandar para a SpecialOne.

Acesse por Administração → Agentes e Identidades.

Quem usa

• SRE e infra: instala e mantém os agentes nos ambientes que vão receber automação.
• Suporte: cria um agente por cliente/rede e gerencia o ciclo de vida (rotacionar credencial, revogar).

Como funciona por baixo

O agente é pull-only: ninguém empurra comando para ele. Ele é que puxa o trabalho.

flowchart LR A[Agente<br/>seu ambiente]:::agt P[Plataforma<br/>SpecialOne]:::plat A -->|1. troca credencial por token| P A -->|2. heartbeat, puxa catálogo| P A -->|3. pega execuções pendentes| P A -->|4. reporta resultado + log| P classDef agt fill:#f0e6ff,stroke:#6400df,color:#1e293b classDef plat fill:#6400df,stroke:#4a00b3,color:#ffffff

1. Troca a credencial (ID + segredo) por um token curto de acesso.
2. Manda heartbeat (diz que está vivo) e baixa o catálogo de runbooks quando muda.
3. Puxa as execuções que são dele e roda localmente.
4. Devolve resultado e log.

Isolamento por token

Cada agente só enxerga o que é dele. O token é escopado ao tenant, e o agente nunca reivindica execução de outro agente. Um agente comprometido não vê os dados de outro cliente.

Criar um agente

1. Clique em Adicionar agente.
2. Dê um nome (letras minúsculas, números, ponto, hífen e sublinhado; 3 a 64 caracteres). O nome é a identidade do agente e não muda depois.
3. Escolha o escopo (o que o agente pode fazer na API da plataforma). Para auto-remediação simples, os escopos padrão bastam.
4. Clique em Criar agente.

Ao criar, a plataforma mostra uma única vez o segredo (token) e o comando de instalação já preenchido. Copie os dois agora.

O segredo aparece só uma vez

Por segurança, a plataforma não guarda o segredo em texto. Se você fechar essa tela sem copiar, dá para rever o comando de instalação depois (com um marcador no lugar do segredo), mas para ter o comando completo de novo você precisa gerar um segredo novo (ver rever a instalação).

Instalar o agente

O comando que a plataforma gera é um docker run. Rode-o na máquina (ou VM) que fica dentro do ambiente que vai receber a automação, com Docker instalado.

LinuxWindows

docker run -d --name sp1-agent \
  -e SP1_URL=https://platform.specialone.io \
  -e SP1_AGENT_ID=<nome-do-agente> \
  -e SP1_AGENT_SECRET=<segredo-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 monta um diretório local do host dentro do agente. É onde ficam o inventário do Ansible e as chaves SSH, que nunca sobem para a plataforma.

Com Docker Desktop (PowerShell), a mesma imagem roda em Windows. Use aspas e crase para quebrar linha:

docker run -d --name sp1-agent `
  -e SP1_URL=https://platform.specialone.io `
  -e SP1_AGENT_ID=<nome-do-agente> `
  -e SP1_AGENT_SECRET=<segredo-mostrado-uma-vez> `
  -e SP1_TENANT=<codigo-do-tenant> `
  -v C:\sp1-agent\secrets:/opt/sp1-agent/work `
  registry.specialone.io/sp1-automation-agent:latest

A imagem já traz o suporte a alvos Windows via WinRM (ver runbooks Ansible).

Poucos segundos depois o agente aparece na lista como Ativo, com o último sinal de vida atualizado.

Variáveis do container

Variável	Obrigatória	Para que serve
SP1_URL	sim	Endereço da plataforma (https).
SP1_AGENT_ID	sim	Nome do agente (o que você definiu na criação).
SP1_AGENT_SECRET	sim	Segredo mostrado uma vez. Em produção, prefira montar como Docker secret (SP1_AGENT_SECRET_FILE).
SP1_TENANT	sim	Código do tenant.
SP1_ANSIBLE_INVENTORY	não	Caminho do inventário Ansible. Sem ela, o agente procura inventory.ini no diretório de trabalho.
SP1_MAX_CONCURRENT	não	Quantas execuções simultâneas (padrão 3).

Rever o comando de instalação

Se você fechou a tela de criação sem copiar, abra o menu de ações (ícone de três pontos) na linha do agente e escolha Instalação.

A janela mostra o comando docker run com um marcador (<seu segredo>) no lugar do token. Como a plataforma não guarda o segredo, você tem duas opções:

• Você ainda tem o segredo: cole-o no lugar do marcador e use o comando.
• Você perdeu o segredo: clique em Gerar novo segredo. A plataforma rotaciona a credencial (a antiga para de funcionar) e monta o comando completo, pronto para copiar.

Inventário do Ansible (alvos remotos)

Runbooks do tipo Ansible rodam contra os hosts definidos num inventário. O inventário é seu e mora no agente (a plataforma nunca recebe): você monta o arquivo no diretório de trabalho do container.

Exemplo de inventory.ini (no host, em /opt/sp1-agent/secrets/inventory.ini, que vira /opt/sp1-agent/work/inventory.ini dentro do container):

[web]
web01 ansible_host=10.0.0.11
web02 ansible_host=10.0.0.12

[web:vars]
ansible_user=deploy
ansible_ssh_private_key_file=/opt/sp1-agent/work/id_ed25519

Como o alvo é escolhido na hora de rodar:

1. O hosts: do playbook seleciona o grupo dentro do inventário (ex.: hosts: web).
2. O parâmetro reservado limit restringe a execução a um host (--limit). Numa automação de monitoramento, mapeie limit para o campo hostname do alerta e o runbook roda só no host que disparou.
3. Sem inventário, só hosts: localhost funciona (roda dentro do próprio container). Um playbook que não casa nenhum host falha com aviso, em vez de terminar "sucesso" sem fazer nada.

Detalhes e exemplos de playbook em Runbooks → Ansible.

Ciclo de vida do agente

O menu de ações de cada agente traz:

Ação	O que faz
Gatilhos	Mostra tudo que dispara trabalho nesse agente (automações de alerta, de chamado e agendamentos). Só leitura.
Instalação	Rever o comando docker run e, se preciso, gerar um segredo novo.
Editar permissões	Muda o escopo do agente na API sem trocar o segredo.
Rotacionar	Gera um segredo novo. O antigo para de funcionar na hora, atualize o container.
Revogar	Desativa o agente: o token para de valer imediatamente. O histórico é mantido.
Excluir	Só para agente revogado. Remove o agente e o rastro operacional (execuções, logs, agendamentos). Serve para limpar testes.

Revogar e excluir não são a mesma coisa

Revogar desativa mas mantém o histórico, é o que você usa ao descomissionar um agente de verdade. Excluir é limpeza definitiva e só funciona depois de revogar. Ao excluir, a evidência (o que o agente executou) é preservada na trilha de auditoria mesmo depois do agente sumir da tela; a ação de exclusão também fica registrada em Trilha de Auditoria.

Próximos passos

• Escrever os runbooks

  ---

  Os scripts que esse agente vai executar, em Python ou Ansible.

  Runbooks

• Montar a automação

  ---

  Ligar o agente a um gatilho e acompanhar as execuções.

  Automações