How to use the Veeam Backup & Replication plugin

This plugin lets Kestra flows manage Veeam Backup & Replication (VBR) jobs, sessions, and restores over its REST API v1.

Authentication

Every task and the trigger require:

• host — hostname or IP of the VBR server.
• username — VBR account used for the OAuth 2.0 password grant.
• password — the account's password; the only connection field masked as a secret in the UI.
• port — REST API port, defaults to 9419.
• apiVersion — sent as the mandatory x-api-version header on every request, including authentication. Defaults to 1.3-rev1 (VBR 12.1+); a missing or unsupported value causes VBR to reject requests with HTTP 400.

Store credentials as secrets, or set them once via plugin defaults for io.kestra.plugin.ee.veeam.*.

An access token is acquired at the start of every task run and refreshed automatically (or a fresh login is performed if the refresh fails) when a task polls across the token's expires_in window, such as sessions.Get with waitForCompletion: true.

Self-signed certificates: VBR servers ship a self-signed certificate by default. Prefer configuring a trust store on the options property so the server's certificate is properly verified. As a last resort, options.ssl.insecureTrustAllCertificates: true skips certificate validation entirely and exposes the connection to man-in-the-middle attacks; without either option, the first request fails with a TLS handshake error instead of a clear authentication error. This is the most common first-run failure.

Tasks

Jobs (jobs)

• jobs.List — lists jobs with optional filters and pagination. Supports fetchType (FETCH, FETCH_ONE, STORE, NONE).
• jobs.Get — fetches a single job's configuration by jobId.
• jobs.Start — starts a job and returns the sessionId created for the run; fails with the server's error message if the job is already running.
• jobs.Stop — stops a job's currently running session.

Sessions (sessions)

• sessions.List — lists job sessions with optional filters and pagination, same fetchType semantics as jobs.List.
• sessions.Get — fetches a session by sessionId. With waitForCompletion: true, polls every pollInterval until the session reaches a terminal state (SUCCESS, WARNING, FAILED) or already has an end time (even with a normalized status of UNKNOWN, for example a canceled session), or fails deterministically if timeout is reached first. This blocking poll holds a worker thread for up to timeout; killing the execution stops the poll promptly instead of pinning the worker until timeout elapses. Output includes a normalized status (RUNNING, SUCCESS, WARNING, FAILED, UNKNOWN) alongside the raw state/result values.
• sessions.GetLogs — writes a session's log records to internal storage as ION and returns the uri and count, to avoid unbounded task output on large sessions.

Restores (restores)

• restores.TriggerInstantVmRestore — starts a vSphere instant VM recovery from restorePointId and returns the sessionId. Only the vSphere endpoint is covered; Hyper-V and Azure instant recovery use separate VBR REST API endpoints not exposed by this task. type selects OriginalLocation (default) or Customized, and secureRestoreAntivirusScan (defaults to false) enables an antivirus scan of the recovered VM's disks before it is made available.
• restores.TriggerFileLevelRestore — mounts a restore point for file-level restore and returns the sessionId. type is the guest OS of the restore point (Windows default, or Linux). autoUnmount (default true) and autoUnmountAfterMinutes (default 30) control automatic release of the mount after a period of inactivity.

Both restore tasks accept additionalOptions, a free-form map merged into the request body, since advanced restore parameters (target host, datastore, network mapping) vary by VBR version and infrastructure. Chain either task with sessions.Get (waitForCompletion: true) to wait for the restore to finish.

Triggers

• jobs.OnJobCompleted — polls /api/v1/sessions at interval and emits one execution per evaluation containing every session that reached a terminal state since the previous evaluation and whose name matches the glob jobNameFilter (defaults to *). Dedupe relies on the trigger's own evaluation date, so already-reported sessions are never re-emitted. Dedup compares the VBR server's session end time against the trigger's own evaluation date; if the VBR server clock and the Kestra server clock drift, sessions can be missed or re-emitted at the window boundary, so keep both clocks in sync (e.g. via NTP). Output exposes sessions (list) and count.