Playbook Runner

Lanza tus playbooks desde una pestaña del navegador.

Playbook Runner es una interfaz web autoalojada para Ansible: inventario, credenciales SSH, playbooks, programaciones y el registro en directo de cada ejecución, sin el peso de AWX o Tower.

Instalar en un servidor
curl -fsSL https://raw.githubusercontent.com/Nonetss/playbook-runner/main/scripts/bootstrap.sh | bash

Ejecútalo en un directorio vacío. Hace unas pocas preguntas, genera todos los secretos y arranca el stack con Docker Compose.

Leer la documentaciónCódigo en GitHub
runner.example.com/

Qué incluye

  1. Tu inventario, con la clave correcta ya asignada.

    Dispositivos y grupos viven en la base de datos. Cada dispositivo apunta a una credencial SSH, así que basta con elegir un grupo: el usuario y la clave correctos acompañan a cada host. Genera un par ed25519 en el navegador y copia un script que da de alta el usuario en un host nuevo.

    runner.example.com/inventory

  2. Mira cada tarea mientras ocurre.

    Elige un playbook y un grupo, confirma y ejecuta. Las líneas PLAY y TASK llegan al navegador a medida que ansible-runner las emite, sin sondeos. Si cierras la pestaña, la ejecución se cancela en el ejecutor.

    runner.example.com/playbooks/:id/run

  3. O guarda tus playbooks en Git.

    Añade un repositorio por HTTPS o SSH, elige rama y subdirectorio. Sus playbooks aparecen en solo lectura y se ejecutan desde una copia del commit sincronizado, así que los roles, plantillas y group_vars que tengan al lado funcionan sin más.

    runner.example.com/playbooks

  4. Prográmalo y luego revisa qué pasó.

    Dale a un job una expresión cron y el backend lo lanza a su hora. Un job nunca se solapa consigo mismo, y el historial guarda el estado, la duración y los hosts de cada ejecución.

    runner.example.com/jobs/:id

  5. Automatízalo a través de la API.

    Cada endpoint está documentado en una referencia OpenAPI interactiva servida en /scalar. Crea una API key personal y llámala desde scripts o CI.

    runner.example.com/scalar

Y el resto de la caja de herramientas

Scripts
Guarda scripts de Bash o Python y ejecútalos sobre una selección de hosts, con la misma consola en directo.
Comandos ad-hoc
Lanza el módulo shell o command contra cualquier selección, con become opcional, para lo puntual que no merece un playbook.
Usuarios y roles
Sin registro público. Los administradores crean las cuentas y asignan admin, user o pending, que puede iniciar sesión pero espera aprobación.
Inicio de sesión único
Cualquier proveedor OIDC (Keycloak, Authentik, Google…) junto a email y contraseña. Se activa con tres variables.
API keys
Claves personales enviadas como x-api-key, para scripts y pipelines de CI.
Instalable en el móvil
La interfaz es una PWA: añádela a la pantalla de inicio y revisa una ejecución desde cualquier sitio.

Cómo está montado

Cuatro servicios y PostgreSQL, levantados con Docker Compose. El navegador solo habla con el gateway Caddy, que manda la API al backend y todo lo demás al frontend. El backend es el dueño de la base de datos y llega al ejecutor de Ansible por gRPC, a través del router interno del gateway.

Recorrido de las peticiones

Abrir una página
  1. Navegador
    → HTTPS
  2. Gateway:80
    Caddy
    → /*
  3. Frontend:4321
    Astro SSR
Ejecutar un playbook
  1. Navegador
    → /rpc
  2. Gateway:80
    Caddy
  3. Backend:3000
    Hono · oRPC
    PostgreSQL
    → gRPC
  4. Router gRPC:50050
    Caddy
    → /run.*
  5. Ejecutor:50051
    ansible-runner
    → SSH
  6. Tus hosts

Enrutado del gateway

PeticiónVa a
/rpc /api /scalar /openapi.jsonbackend:3000
cualquier otra rutafrontend:4321
gRPC /run.* en :50050ansible:50051
cualquier otro servicio gRPCUNIMPLEMENTED

Solo el puerto 80 del gateway se mapea al host, como GATEWAY_PORT. El resto de servicios solo son accesibles dentro de la red de Compose.

Las claves privadas no salen del servidor.
Las claves SSH se cifran en reposo con AES-256-GCM y la API nunca las devuelve. Solo se descifran para preparar una ejecución, y el ejecutor borra los ficheros de clave al terminar.
El ejecutor no tiene base de datos.
El backend resuelve el playbook, los hosts y sus claves, y envía un único paquete completo por gRPC, autenticado con un token compartido. La salida vuelve por la misma llamada.
Las ejecuciones tienen límite.
Por defecto corren como mucho ocho procesos de Ansible a la vez; las peticiones de más se rechazan en lugar de encolarse. Las claves de host SSH se verifican: se confía en el primer contacto y se rechazan las que cambian.
Leer la arquitectura en la documentación

En marcha con un solo comando.

En un host Linux con Docker, curl y openssl, desde un directorio vacío:

curl -fsSL https://raw.githubusercontent.com/Nonetss/playbook-runner/main/scripts/bootstrap.sh | bash

Haz copia del .env generado, sobre todo de CREDENTIALS_ENCRYPTION_KEY. Si la pierdes, ninguna clave SSH guardada se podrá recuperar.

¿Prefieres montarlo a mano? Desplegar con Docker Compose

Qué hace el script

  1. 1Pregunta la URL pública, el puerto y el primer administrador, y opcionalmente los datos de OIDC.
  2. 2Genera todos los secretos con openssl, incluida la clave que cifra las claves SSH guardadas.
  3. 3Escribe .env y compose.yml en el directorio actual.
  4. 4Descarga las imágenes de ghcr.io y arranca el stack. El backend migra la base de datos y crea el administrador al arrancar.
runner.example.com