Plantillas

Las plantillas forman el catálogo de lo que se puede desplegar. Cada una describe un tipo de aplicación ("Ubuntu VM", "PostgreSQL", "Kubernetes cluster") como un documento YAML que compone proyectos de Terraform y scripts, cada uno leído de su repositorio Git.

Las plantillas oficiales de Sora están en sora-project-infrastructure.

Gestionar el catálogo

Importar

Hay tres formas de añadir una plantilla:

• Desde Git, con un escaneo que encuentra las plantillas de un repositorio.
• Subiendo un fichero.
• Con el asistente, que dibuja el pipeline mientras se construye y lee las variables de cada Terraform o script en el momento de elegirlo.

Sea cual sea la forma, Horizon lee el Terraform y los scripts, descubre sus variables y salidas, y guarda la plantilla completa en su base de datos.

Sincronizar

Una plantilla importada desde Git se actualiza con Sync, y solo cambia así: el repositorio es la fuente de verdad. Las subidas y las del asistente se editan directamente en Horizon.

precaución

Sync solo vuelve a leer las variables de un proyecto cuando el campo version de la plantilla es mayor que el guardado. Un cambio en un .tf o en un script sin subir la versión no llega a Horizon.

Retirar y borrar

Una plantilla retirada sigue funcionando en sus stacks, pero no permite crear nuevos. Es reversible. Solo se puede borrar una plantilla retirada y sin stacks activos.

Tipos

kind	Para qué
ProxmoxVmTemplate	Desplegar VMs de Proxmox. Horizon reconoce su vocabulario de variables y rellena él mismo el host, la ISO, la llave SSH, el registro DNS, la MAC y la monitorización, de forma que el operador solo responde lo que realmente le corresponde
ApplicationTemplate	El tipo libre: cualquier otra cosa. Todas las variables se preguntan al operador
IsoTemplate	Un único proyecto de Terraform que deja una imagen de instalación en Proxmox

Estructura

Una plantilla es una lista ordenada de fases, cada una con uno o varios trabajos:

• Los trabajos de una fase se ejecutan en paralelo; la siguiente fase empieza cuando todos han terminado bien.
• Un trabajo es un proyecto de Terraform o un script que se ejecuta por SSH en la VM de un trabajo anterior.
• Cada trabajo indica su repositorio, rama y ruta. Una plantilla puede usar varios repositorios.
• Un trabajo puede permitir múltiples ejecuciones (multiple_runs), opcionalmente en serie (serial) y creando antes de destruir (replace_order: create_first).
• Un trabajo lee las salidas de otro con steps.<trabajo>.<salida>.

Un ejemplo simplificado:

apiVersion: horizon/v1
kind: ProxmoxVmTemplate
name: Mi aplicación
version: 1.0.0

phases:
  - name: infra
    jobs:
      - id: vm
        kind: terraform
        terraform:
          repository: https://gitlab.com/ReiIzumi/sora-project-infrastructure.git
          name: linux/terraform
  - name: app
    jobs:
      - id: app
        kind: shell
        target: vm                    # se ejecuta en la VM del trabajo "vm"
        script:
          repository: https://gitlab.com/usuario/mi-app.git
          name: jobs/20-install.sh

actions:
  - id: rotate
    kind: shell
    target: vm
    script:
      repository: https://gitlab.com/usuario/mi-app.git
      name: actions/rotate.sh

Scripts

Un script declara sus variables y salidas en un bloque al inicio, y reporta las salidas imprimiendo nombre=valor:

#!/usr/bin/env bash
# horizon:begin
# lifecycle: [create]
# variables:
#   - name: cluster_token
#     type: string
#     required: true
#     sensitive: true
# outputs:
#   - name: join_command
# horizon:end
set -euo pipefail

echo "join_command=kubeadm join ${HORIZON_MASTER_K8S_MASTER_IP}:6443 --token ${cluster_token}"

Un script que no imprime alguna de las salidas que promete hace fallar su trabajo. Con run_on: [create, destroy] también se ejecuta al eliminar la máquina o el stack.

Checks de Nagios

El bloque nagios: lista los checks de cada VM. Horizon los publica en su servidor Nagios al terminar un despliegue correcto y los quita al destruir:

nagios:
  - job: vm
    checks:
      - name: PING
        service_template: sora-service
        command: check_ping!100.0,20%!500.0,60%
      - name: Hard disk - Root
        service_template: sora-hdd
        command: check_nrpe_disk_root
      - name: Prometheus Node Exporter
        service_template: sora-metrics
        http: steps.vm.metrics_urls.node
        content: node_exporter_build_info

Horizon valida los comandos y plantillas contra el catálogo del servidor Nagios al sincronizar y antes de cada despliegue.

Editores de variables

Una variable libre puede pedir un editor concreto en el formulario:

Editor	Qué ofrece
cron	Expresiones habituales, validación y su descripción en texto
github-release	Rellena la última release de un repositorio de GitHub, opcionalmente de una línea concreta (v1.36.)
docker-tag	Rellena el último tag de una imagen de Docker Hub
options	Una lista de valores, abierta o cerrada
shared-folder-server, shared-folder-path, mount-path	Una carpeta compartida que la VM puede usar, y dónde se monta
dns-record, dns-record-field, dns-alias	Un registro DNS del inventario (reservado o solo referenciado), uno de sus campos o uno de sus alias

Plantillas ISO

Una plantilla ISO envuelve un único proyecto de Terraform que deja una imagen en Proxmox. Por lo demás, se comporta igual: importación, sincronización, retirada y borrado.

Contratos

Todo lo que una plantilla debe cumplir está documentado en docs/contracts:

• application-template.md: el manifiesto (fases, trabajos, acciones, binds).
• application-template-lifecycle.md: qué ocurre al desplegar, editar, reintentar y destruir.
• proxmox-vm-template.md: el vocabulario de variables de una VM de Proxmox.
• shell-script.md: el bloque de un script y el entorno que recibe.
• application-template-nagios.md: los checks de Nagios.
• application-template-ui.md: los editores de variables.
• iso-template.md: las plantillas ISO.