Flujo de trabajo IaC

Cómo adoptar, validar, previsualizar y aplicar un manifiesto YAML de SteadyCron — desde el primer export hasta la automatización CI/CD.

La CLI de SteadyCron convierte su cuenta en un archivo de texto que puede versionar, revisar en PRs y desplegar desde CI. Esta página explica cada comando del flujo de trabajo.

Requisitos previos {#prerequisites}

Instalar la CLI

Opción 1 — herramienta global de .NET (recomendado)

Requiere el runtime de .NET 10.

dotnet tool install -g steadycron
steadycron --version

Actualice más tarde con dotnet tool update -g steadycron.

Opción 2 — binario autocontenido

Sin runtime requerido. Descargue el binario desde la página Releases:

# Linux x64
curl -Lo steadycron https://github.com/steadycron/cli/releases/latest/download/steadycron-linux-x64
chmod +x steadycron && sudo mv steadycron /usr/local/bin/

Los binarios para Linux arm64, macOS y Windows están en la misma página Releases.

Autenticación

Cree una clave de API en Configuración → Claves de API del dashboard. Los comandos con escritura (apply, sync, jobs create, etc.) requieren una clave de acceso completo; export, validate y plan funcionan con una clave de solo lectura.

Configure la clave en su entorno:

export STEADYCRON_API_KEY=sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

O guárdela en el archivo de configuración para que persista entre sesiones de shell:

steadycron config set --api-key sc_...

Verifique la conectividad:

steadycron config show --check

Comandos de un vistazo

Comando	Qué hace
`steadycron export`	Exportar el estado actual de la cuenta a un manifiesto
`steadycron validate`	Comprobar un manifiesto en busca de errores de esquema
`steadycron plan`	Previsualizar qué cambiaría — sin escrituras
`steadycron sync`	Aplicar cambios (crear + actualizar; sin eliminaciones)
`steadycron apply`	Aplicar cambios; añada `--prune` para también eliminar

Paso 1 — export (adoptar una cuenta existente)

Si ya tiene jobs en el dashboard, export los vuelca en un manifiesto para que pueda empezar a gestionarlos como código sin perder nada:

export STEADYCRON_API_KEY=sc_...
steadycron export --namespace production > manifests/production.yaml

El archivo exportado es seguro para committear. Cualquier clave de API, URL de webhook u otros secrets se reemplazan por marcadores de posición ${VAR_NAME} — usted proporciona los valores reales a través de variables de entorno en el momento de aplicar. Las variables de plantilla ({{var}}) en los campos de jobs HTTP se conservan tal cual.

Revise el archivo, añada valores id a los jobs que no los tengan y haga commit.

Paso 2 — validate

Compruebe un manifiesto en busca de errores de esquema antes de aplicarlo:

steadycron validate manifests/production.yaml

Termina con 0 en caso de éxito, 1 con una lista de errores en caso de fallo. Intégrelo en CI como verificación previa en cada PR.

Paso 3 — plan

plan le muestra exactamente qué cambiaría — con un formato similar a terraform plan — sin escribir nada:

steadycron plan manifests/production.yaml

Ejemplo de salida:

  ~ weekly-digest       update  retries: 2 → 3
  + invoice-reminder    create  kind: http  schedule: 0 17 * * 5
  - old-report          (not in manifest — would be deleted with --prune)

  1 to create · 1 to update · 1 pending deletion

Use esto en su pipeline de PR para publicar el diff del plan como comentario en cada pull request. Consulte Configuración CI/CD para conocer la GitHub Action que lo hace automáticamente.

Paso 4 — sync / apply

sync crea nuevos jobs y actualiza los modificados. No elimina los jobs que existen en su cuenta pero están ausentes del manifiesto:

steadycron sync manifests/production.yaml

Para también eliminar los jobs no gestionados (los que están en el namespace pero no en el archivo), use apply --prune:

steadycron apply --prune manifests/production.yaml

apply es transaccional: si alguna operación falla, el resto del lote no se aplica y se informa del error con el recurso específico que lo causó.

Dry-run

Pase --dry-run a cualquier llamada de sync o apply para imprimir qué sucedería sin realizar cambios — equivalente a plan pero útil al scripting:

steadycron apply --prune --dry-run manifests/production.yaml

Namespaces y propiedad {#namespaces}

Un namespace delimita qué recursos gestiona la CLI. Sin un namespace, la CLI opera en el namespace por defecto y no puede usar --prune de forma segura (eliminaría cualquier job que no esté en el manifiesto, incluidos los creados desde el dashboard).

Nombre los namespaces según entornos o equipos:

# manifests/production.yaml
namespace: production
jobs: [...]

# manifests/staging.yaml
namespace: staging
jobs: [...]

El dashboard muestra el namespace al que pertenece cada job. Los recursos creados desde el dashboard (sin namespace) pertenecen al namespace por defecto y no son afectados por un apply --prune con namespace.

Múltiples namespaces en un monorepo

Organice un archivo de manifiesto por namespace:

manifests/
  production.yaml    # namespace: production
  staging.yaml       # namespace: staging
  workers.yaml       # namespace: workers-team

Aplique cada uno de forma independiente:

steadycron apply --prune manifests/production.yaml
steadycron apply --prune manifests/staging.yaml

Identidad estable y seguridad al renombrar

Cada recurso en un manifiesto tiene un campo id. Esta es la clave interna estable — nunca cambia, aunque usted renombre el name del job.

jobs:
  - id: nightly-backup         # ← estable para siempre
    name: Nightly database backup (prod)   # ← libre de renombrar
    kind: heartbeat
    schedule: "0 2 * * *"

Por qué importa para los heartbeats: cada check de heartbeat tiene una URL de ping única vinculada a su ID interno. Cuando renombra un job de heartbeat, la URL de ping se conserva — no necesita actualizar sus scripts, pipelines de CI o integraciones de monitoreo.

Si dos entradas tienen el mismo id, validate rechazará el manifiesto.

Secrets y variables {#secrets}

Los secrets nunca deben aparecer literalmente en el manifiesto. SteadyCron ofrece dos mecanismos:

1. `${ENV_VAR_NAME}` — sustitución de entorno por la CLI

La CLI los lee del entorno del proceso en el momento de aplicar y los sustituye antes de enviar el manifiesto a la API. Funciona en cualquier campo.

channels:
  - id: ops-slack
    name: Slack #ops
    kind: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}   # ← la CLI lee del entorno al aplicar

jobs:
  - id: invoice-job
    kind: http
    url: https://${API_HOST}/jobs/invoices
    headers:
      Authorization: Bearer ${INVOICE_API_KEY}

En CI, defínalos como secrets del repositorio y páselos al job:

# GitHub Actions
env:
  STEADYCRON_API_KEY: ${{ secrets.STEADYCRON_API_KEY }}
  SLACK_WEBHOOK_URL:  ${{ secrets.SLACK_WEBHOOK_URL }}
  INVOICE_API_KEY:    ${{ secrets.INVOICE_API_KEY }}

2. `{{template_var}}` — sustitución en el servidor

Las variables de plantilla son resueltas por el servidor de SteadyCron en el momento de la ejecución, no al aplicar. Solo funcionan en campos de jobs HTTP (url, headers, body) y son útiles para valores que varían por ejecución o se calculan en el servidor.

jobs:
  - id: data-export
    kind: http
    url: https://api.myapp.com/export/{{date}}
    body: '{"run_id": "{{uuid}}"}'

steadycron export emite ambos tipos de marcadores de posición automáticamente — el manifiesto exportado es seguro para committear sin depuración manual.