Ana içeriğe geç
Bu sayfa henüz Türkçeye çevrilmedi; İngilizce sürümü gösteriliyor.
Versiyon: 1.0.1

Jobs as Code

Clicking jobs together in the dashboard is fine for one environment. Once you have staging and production, or several teams, you want job definitions in Git: reviewed in pull requests, applied by CI, the same in every environment.

Milvaion offers two ways to do that. Both use the regular REST API with an api key, so they need nothing extra on the server.

milvaion CLITerraform provider
DefinitionsYAML files (apiVersion: milvaion/v1)HCL, milvaion_job resources
StateNone. Jobs are matched by name on every runTerraform state
Good forTeams without Terraform, quick scripts, CI checksTeams that already manage infrastructure with Terraform
Also doesget, trigger, logs, exportData sources for jobs and workers

Pick one tool per job. If the CLI and Terraform both manage the same job, each one will keep undoing the other's changes.

The Api Key​

Create a key under User Management → Api Keys with these permissions:

UsePermissions
apply, diff, TerraformScheduledJobManagement.List, .Detail, .Create, .Update, .Delete
get workers, milvaion_workerWorkerManagement.List, WorkerManagement.Detail
triggerScheduledJobManagement.Trigger
get occurrences, logsScheduledJobManagement.List, .Detail

A drift check in CI (milvaion diff --exit-code) only needs List and Detail.

The milvaion CLI​

Install​

Download the archive for your platform from the GitHub releases tagged cli-v*, extract milvaion and put it on your PATH. Each release has a checksums file to verify the download.

With Go installed you can also build it from source:

go install github.com/Milvasoft/milvaion/tools/milvaion-cli@latest

That installs the binary as milvaion-cli; rename it to milvaion if you like.

Log In​

milvaion login --url https://milvaion.example.com --api-key "$KEY"

login checks the key and saves the URL and key to milvaion/config.yaml in your user config directory (~/.config on Linux, ~/Library/Application Support on macOS, %AppData% on Windows), readable only by you. Set MILVAION_CONFIG to use another file. To keep the key out of your shell history, pipe it in with --api-key-stdin.

In CI, skip login and set environment variables instead. They override the saved login:

export MILVAION_URL=https://milvaion.example.com
export MILVAION_API_KEY=...

Describe Jobs in YAML​

apiVersion: milvaion/v1
kind: Job
metadata:
name: nightly-invoice-report # the job's display name, and the key apply matches on
spec:
description: Sends yesterday's invoices to finance
tags: [billing, reports]
worker: reporter-worker # worker id
jobName: InvoiceReportJob # job type on that worker
cron: "0 0 2 * * *" # six fields, seconds first: 02:00 every day
concurrencyPolicy: Skip # Skip or Queue
jobData: # any YAML, sent to the job as JSON
recipients: [[email protected]]
format: pdf
executionTimeoutSeconds: 900
autoDisable:
enabled: true
threshold: 5
failureWindowMinutes: 60

Put several jobs in one file, either as YAML documents separated by ---, or as a list:

apiVersion: milvaion/v1
kind: JobList
items:
- metadata: {name: cleanup-temp-files}
spec:
worker: maintenance-worker
jobName: CleanupJob
cron: "0 30 3 * * *"
- metadata: {name: one-off-migration}
spec:
worker: sample-worker
jobName: MigrateJob
executeAt: 2026-12-01T22:00:00Z # one-time job
active: false

Run milvaion schema for the full field list. The fields are:

FieldNotes
descriptionFree text.
tagsList of tags.
workerWorker id. Changing it replaces the job (see below).
jobNameJob type on the worker.
cronRecurring schedule. Six fields, seconds first.
executeAtOne-time run, RFC 3339. Ignored when cron is set. Changing it replaces the job.
activeDefault true.
concurrencyPolicySkip (default) or Queue.
jobDataPayload. A YAML value or a JSON string.
zombieTimeoutMinutesLeave out to use the server default.
executionTimeoutSecondsLeave out to use the worker default.
autoDisable{enabled, threshold, failureWindowMinutes}. Leave it out and apply leaves the server's settings alone.
external, externalJobIdFor jobs reported by Hangfire or Quartz. Changing them replaces the job.

Leaving out any other field means "the default": removing description from the file clears it on the server.

Preview and Apply​

milvaion diff -f jobs/
~ update nightly-invoice-report (01a1d6f5-59e0-7465-9423-a145e95a45a1)
cron: "0 0 2 * * *" -> "0 0 3 * * *"
+ create cleanup-temp-files
worker: "maintenance-worker"
jobName: "CleanupJob"
cron: "0 30 3 * * *"
active: true
concurrencyPolicy: "Skip"

Plan: 1 to create, 1 to update, 0 to replace, 0 to delete, 4 unchanged.
milvaion apply -f jobs/

-f takes a file, a directory of .yaml/.yml files, or - for standard input, and can be repeated. Running apply twice with the same files changes nothing the second time.

How jobs are matched. metadata.name is the job's display name, and apply looks the job up by it. A name that does not exist yet is created. If two jobs on the server have the same name, apply stops and asks you to fix that first, rather than guess.

Renaming a job in the file creates a new job under the new name. The old one stays (and keeps its run history) until you run apply --prune. To keep the history on the renamed job, rename it in the dashboard first, then in the file.

Replacements. The API cannot change worker, executeAt, external or externalJobId on an existing job. When one of them changes, apply creates the new job and then deletes the old one, which drops its run history. It refuses to do that unless you pass --allow-replace. If the create fails, the old job is left untouched.

Pruning​

Every job that apply creates or updates gets the tag managed-by:milvaion-cli. With --prune, apply deletes jobs that carry that tag but are no longer in the files:

milvaion apply -f jobs/ --prune

Jobs made in the dashboard do not have the tag, so --prune never touches them. When several repositories manage jobs on the same Milvaion, give each its own tag so one repository's prune cannot delete another's jobs:

milvaion apply -f jobs/ --prune --managed-tag managed-by:billing-repo

The tag shows up in the dashboard like any other tag. export and diff hide it.

Adopting Existing Jobs​

milvaion export > jobs.yaml
milvaion apply -f jobs.yaml

Drift Detection in CI​

diff --exit-code exits 0 when the server matches the files and 2 when it does not:

# .github/workflows/milvaion-jobs.yml
name: Milvaion jobs
on:
pull_request:
paths: ['jobs/**']
push:
branches: [main]
paths: ['jobs/**']

jobs:
jobs:
runs-on: ubuntu-latest
env:
MILVAION_URL: ${{ vars.MILVAION_URL }}
MILVAION_API_KEY: ${{ secrets.MILVAION_API_KEY }}
steps:
- uses: actions/checkout@v4
- name: Install milvaion
run: |
curl -sSL https://github.com/Milvasoft/milvaion/releases/download/cli-v1.0.0/milvaion_1.0.0_linux_amd64.tar.gz | tar xz milvaion
sudo mv milvaion /usr/local/bin/
- name: Show changes
run: milvaion diff -f jobs/
- name: Apply
if: github.event_name == 'push'
run: milvaion apply -f jobs/ --prune

Everyday Commands​

milvaion get jobs                     # --tag, --search, -o json|yaml
milvaion get workers
milvaion get occurrences --job nightly-invoice-report --status Failed --limit 10

milvaion trigger nightly-invoice-report # prints the occurrence id
milvaion trigger nightly-invoice-report --follow # streams logs; exits 1 if the run fails
milvaion trigger nightly-invoice-report --data '{"format":"csv"}' --reason "rerun for audit"

milvaion logs 01a1d6f5-857c-7b21-995d-93ea2aea8ab5
milvaion logs --job nightly-invoice-report -f # newest run, follow until it finishes

Wherever a command takes a job, you can pass its name or its id.

The Terraform Provider​

Configure the Provider​

terraform {
required_providers {
milvaion = {
source = "milvasoft/milvaion"
version = "~> 1.0"
}
}
}

provider "milvaion" {
url = "https://milvaion.example.com"
# api_key = var.milvaion_api_key # or set MILVAION_API_KEY
}

url and api_key fall back to MILVAION_URL and MILVAION_API_KEY. Keep the key out of .tf files.

Define Jobs​

data "milvaion_worker" "reporter" {
worker_id = "reporter-worker"
}

resource "milvaion_job" "invoice_report" {
name = "nightly-invoice-report"
description = "Sends yesterday's invoices to finance"
tags = ["billing", "reports"]
worker_id = data.milvaion_worker.reporter.worker_id
job_name = "InvoiceReportJob"
cron_expression = "0 0 2 * * *"

job_data = jsonencode({
recipients = ["[email protected]"]
format = "pdf"
})

execution_timeout_seconds = 900

auto_disable = {
threshold = 5
failure_window_minutes = 60
}

lifecycle {
# Fail the plan early if the worker does not offer this job type.
precondition {
condition = contains(data.milvaion_worker.reporter.job_names, "InvoiceReportJob")
error_message = "reporter-worker does not offer InvoiceReportJob."
}
}
}
AttributeNotes
nameRequired. Display name.
description, tags, job_name, cron_expressionUpdated in place.
worker_id, execute_at, is_external, external_job_idChanging them replaces the job.
is_activeDefault true.
concurrent_execution_policySkip (default) or Queue.
job_dataJSON string. Use jsonencode(). Key order and whitespace do not cause diffs.
zombie_timeout_minutes, execution_timeout_secondsLeave out to use the defaults.
auto_disableLeave it out to keep whatever the server has. Removing it later stops managing it; it does not reset it.

Terraform tracks jobs by id, not by name, so renaming a milvaion_job updates it in place and keeps its history.

Import Existing Jobs​

terraform import milvaion_job.invoice_report 01a1d6f5-59e0-7465-9423-a145e95a45a1

Or, with Terraform 1.5 and later:

import {
to = milvaion_job.invoice_report
id = "01a1d6f5-59e0-7465-9423-a145e95a45a1"
}

milvaion get jobs lists the ids.

Data Sources​

# Look a job up by name (it must be unique) or by id.
data "milvaion_job" "cleanup" {
name = "cleanup-temp-files"
}

# A registered worker: status, version, job_names, routing_patterns, instance_count.
data "milvaion_worker" "maintenance" {
worker_id = "maintenance-worker"
}

output "cleanup_schedule" {
value = data.milvaion_job.cleanup.cron_expression
}

Things to Know​

  • Cron has six fields. Milvaion cron expressions start with seconds: 0 */5 * * * * is every five minutes. Both tools reject five-field expressions before calling the API.
  • Workers must be running. Milvaion checks that the worker exists, is active and offers the job type when a job is created. Start the worker before you apply.
  • Times are UTC. executeAt / execute_at accept any offset and store UTC.
  • Edits in the dashboard are drift. The next apply puts the file's values back. Pausing a job in the dashboard during an incident is fine, but expect the next deploy to switch it on again unless the file says active: false.

Next Steps​

  • Api Keys: create and rotate the key the tools use
  • MCP Server: ask an AI assistant about the jobs you deployed
  • Workflows: chain jobs into pipelines