Manifest-Referenz

Vollständige Feldreferenz für das SteadyCron v2-YAML-Manifest — Jobs, Kanäle, Regeln, Variablen, Tags und Namespaces.

Das v2-Manifest ist die maßgebliche Definition Ihres SteadyCron-Kontos. Eine einzelne Datei (oder ein Verzeichnis von Dateien) deklariert jeden Job, jeden Alert-Kanal, jedes Tag und jede Variable, die die CLI verwaltet.

Struktur auf oberster Ebene

namespace: my-app        # optional — begrenzt IaC-Eigenverantwortung
variables:               # Server-seitige Template-Variablen (Liste von Objekten)
channels:                # Alert-Kanal-Definitionen
tags:                    # Wiederverwendbare Tag-Definitionen
shaping:                 # Rate-Limit-Hinweise
jobs:                    # HTTP-Jobs und Heartbeat-Checks
                         # Alarmierungsregeln werden pro Job unter jobs[].rules deklariert

`namespace`

Ein String, der alle Ressourcen in diesem Manifest einem Scope zuordnet. Die CLI verwaltet (und löscht mit --prune) nur Ressourcen, die zu diesem Namespace gehören — sodass IaC-verwaltete Jobs und manuell erstellte Jobs sicher im selben Konto koexistieren können.

namespace: production

Wird namespace weggelassen, wird der Standard-Namespace verwendet. Weitere Informationen zu Multi-Umgebungs-Setups finden Sie unter Namespaces & Eigenverantwortung.

`jobs[]`

Jeder Eintrag ist entweder ein HTTP-Job (kind: http), der Ihren Endpunkt nach Zeitplan aufruft, oder ein Heartbeat-Check (kind: heartbeat), der einen Ping von Ihrem eigenen Cron erwartet.

Gemeinsame Felder

Feld	Typ	Erforderlich	Beschreibung
`id`	string	Nein	Stabiler Abstimmungsschlüssel. Bei Angabe sind Umbenennungen sicher — die `id` ändert sich nie, sodass Heartbeat-Ping-URLs erhalten bleiben. Fällt auf `name` zurück, wenn nicht angegeben.
`name`	string	Ja	Anzeigename im Dashboard und in Alert-Nachrichten. Muss innerhalb des Manifests eindeutig sein.
`kind`	`http` \| `heartbeat`	Nein	Job-Typ. Standard: `http`.
`schedule`	string	Ja*	Fünffeldriger Cron-Ausdruck (`minute hour dom month dow`).
`interval`	integer	Ja*	Fester Intervall in Sekunden (10–86400). Alternative zu `schedule`.
`timezone`	string	Nein	IANA-Zeitzonenname, z. B. `Europe/Berlin`. Standard: UTC.
`paused`	boolean	Nein	Job im pausierten Zustand erstellen oder halten.
`tags`	string[]	Nein	Tag-Referenzen als `"key:value"`-Strings, z. B. `["env:prod", "team:backend"]`.
`rules`	object[]	Nein	Job-spezifische Alarmierungsregeln. Siehe Alarmierungsregeln.

*Genau eines von schedule oder interval ist erforderlich.

HTTP-Job-Felder

Feld	Typ	Erforderlich	Beschreibung
`method`	string	Nein	HTTP-Methode. Eines von `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. Standard: `GET`.
`url`	string	Ja	Aufzurufender Endpunkt. Unterstützt `${ENV}`- (CLI-Substitution) und `{{template_var}}`-Platzhalter (serverseitig).
`headers`	object	Nein	Zusätzliche Anfrage-Header. Werte unterstützen `${ENV}`-Platzhalter.
`body`	string	Nein	Anfrage-Body. Unterstützt `{{template_var}}`-Platzhalter.
`timeout`	integer	Nein	Anfrage-Timeout in Sekunden. Standard: 60.
`retries`	integer	Nein	Anzahl der Wiederholungsversuche bei Nicht-2xx-Antwort oder Timeout. Standard: 0.
`retry_backoff`	integer	Nein	Sekunden zwischen Wiederholungsversuchen. Standard: 30.
`retry_on_timeout`	boolean	Nein	Timeouts als Fehler für Wiederholungszwecke zählen. Standard: `true`.
`retry_on_status`	integer[]	Nein	HTTP-Statuscodes, die einen Wiederholungsversuch auslösen (100–599).
`skip_if_running`	boolean	Nein	Ausführung überspringen, wenn der vorherige Lauf noch aktiv ist. Standard: `false`.
`misfire_policy`	string	Nein	Verhalten bei verpasster geplanter Ausführung: `do_nothing` (Standard) oder `fire_once_now`.

Heartbeat-Check-Felder

Feld	Typ	Erforderlich	Beschreibung
`grace`	integer	Nein	Sekunden, die nach dem erwarteten Ping-Zeitpunkt gewartet wird, bevor ein Alert ausgelöst wird. Standard: 60.
`stuck_run_detection`	boolean	Nein	Alarmiert, wenn ein Lauf `max_run_duration` überschreitet. Standard: `true`.
`max_run_duration`	integer	Nein	Maximale erlaubte Laufdauer in Sekunden (60–86400).

`channels[]`

Alert-Kanäle, die von Job-Regeln über ihre id oder ihren name referenziert werden.

Feld	Typ	Erforderlich	Beschreibung
`id`	string	Nein	Stabiler Referenzschlüssel, der in `jobs[].rules[].channel` verwendet wird.
`name`	string	Ja	Menschenlesbarer Name im Dashboard und in Alert-Nachrichten.
`kind`	string	Ja	Eines von `slack`, `discord`, `email`, `telegram`, `webhook`.
`config`	object	Nein	Art-spezifische Schlüssel-Wert-Konfiguration. Verwenden Sie `${ENV}`-Platzhalter — committen Sie niemals echte Secrets.

channels:
  - id: ops-slack
    name: Slack #ops
    kind: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}

Alarmierungsregeln {#alert-rules}

Alarmierungsregeln werden pro Job unter jobs[].rules definiert. Jede Regel verknüpft ein Trigger-Ereignis mit einem Benachrichtigungskanal.

jobs:
  - id: weekly-digest
    name: Weekly digest email
    kind: http
    schedule: "0 9 * * 1"
    url: https://api.myapp.com/jobs/digest
    rules:
      - channel: ops-slack
        trigger: on_failure
        severity: p1
      - channel: ops-slack
        trigger: on_recovery

Feld	Typ	Erforderlich	Beschreibung
`channel`	string	Ja	Zu benachrichtigende Kanal-`id` oder `-name`.
`trigger`	string	Ja	Ereignis, das die Regel auslöst: `on_failure`, `on_recovery`, `on_missed_heartbeat`.
`severity`	string	Nein	Schweregradlabel, das an den Kanal weitergeleitet wird (z. B. `p1`, `p2`, `p3`).
`params`	object	Nein	Trigger-spezifische Parameter.
`dedup_window_seconds`	integer	Nein	Zeitfenster zur Alert-Deduplizierung in Sekunden.

`tags[]`

Tags gruppieren Jobs im Dashboard. Jedes Tag hat einen key und einen value; Jobs referenzieren sie als "key:value"-Strings.

tags:
  - id: env-prod
    key: env
    value: prod
  - id: team-backend
    key: team
    value: backend

Job-Referenz: tags: ["env:prod", "team:backend"]

Feld	Typ	Erforderlich	Beschreibung
`id`	string	Nein	Stabiler Referenzschlüssel.
`key`	string	Ja	Tag-Kategorie (z. B. `env`, `team`).
`value`	string	Ja	Tag-Wert (z. B. `prod`, `backend`).
`color`	string	Nein	Hexadezimaler Farbcode für das Dashboard.

`variables`

Server-seitige Template-Variablen. Jede Variable ist ein Objekt mit id, name und value. Die CLI löst ${ENV_VAR} in value zur Anwendungszeit auf; der Server ersetzt {{name}} in HTTP-Job-Feldern zur Ausführungszeit. Secrets landen nie in git.

variables:
  - id: digest-token
    name: digest_token
    value: ${DIGEST_TOKEN}

Verwenden Sie {{digest_token}} in HTTP-Feldern url, headers oder body.

Feld	Typ	Erforderlich	Beschreibung
`id`	string	Nein	Stabiler Referenzschlüssel.
`name`	string	Ja	Variablenname für `{{name}}`-Server-seitige Substitutionen.
`value`	string	Nein	Variablenwert. Unterstützt `${ENV_VAR}`-CLI-Substitution.

`shaping`

Request Shaping steuert Parallelität und Rate-Limits für HTTP-Jobs — nützlich, wenn viele Jobs zur selben Minute feuern und Sie die Last verteilen möchten.

shaping:
  max_concurrent_jobs: 5
  max_jobs_per_minute: 30

Feld	Typ	Beschreibung
`max_concurrent_jobs`	integer	Maximale Anzahl parallel ausgeführter HTTP-Jobs.
`max_jobs_per_minute`	integer	Maximale HTTP-Job-Ausführungen pro Minute.

Vollständiges Beispiel

namespace: production

variables:
  - id: digest-token
    name: digest_token
    value: ${DIGEST_TOKEN}

channels:
  - id: ops-slack
    name: Slack #ops
    kind: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}

tags:
  - id: env-prod
    key: env
    value: prod
  - id: team-backend
    key: team
    value: backend

jobs:
  - id: weekly-digest
    name: Weekly digest email
    kind: http
    method: POST
    url: https://api.myapp.com/jobs/digest
    schedule: "0 9 * * 1"
    timezone: Europe/Berlin
    timeout: 120
    retries: 3
    tags: ["env:prod", "team:backend"]
    rules:
      - channel: ops-slack
        trigger: on_failure
        severity: p1
      - channel: ops-slack
        trigger: on_recovery

  - id: nightly-backup
    name: Nightly DB backup
    kind: heartbeat
    schedule: "0 2 * * *"
    grace: 1800
    tags: ["env:prod"]
    rules:
      - channel: ops-slack
        trigger: on_missed_heartbeat
        severity: p1

Secrets: zwei Mechanismen im Vergleich

	`${ENV_VAR_NAME}`	`{{template_var}}`
Aufgelöst von	CLI zur Anwendungszeit	Server zur Ausführungszeit
Funktioniert in	Jedem Feld	Nur `url`, `headers`, `body` bei HTTP-Jobs
Verwenden für	API-Schlüssel, Webhook-URLs, umgebungsspezifische Werte	Dynamische Werte pro Ausführung
Exportiert als	Platzhalter `${VAR}`	Platzhalter `{{var}}`

steadycron export gibt beide Arten von Platzhaltern automatisch aus, wo immer es ein Secret oder eine Template-Variable erkennt, sodass das exportierte Manifest direkt commit-sicher ist.