Metaplane Gate

Metaplane Gate

Certified

Gate a pipeline on one or more Metaplane monitors, synchronously

Optionally enqueues one or more monitors to run, then polls their status until each result is fresh (its timestamp is at or after the moment this task started) or a bounded timeout elapses. Unlike Get, this task can fail the flow itself: it combines every monitor's effective status (escalating a stale result to FAIL when maxAge is set) using failStrategy to decide whether the gate passes.

When runFirst is false, no run is triggered: each monitor's current status is read once and, if maxAge is set, flagged stale when older than maxAge. When runFirst is true, a stale result can never occur since the polled result is always freshly produced after this task started.

Throws an actionable error naming the still-pending monitor(s) if the poll times out before every monitor becomes fresh.

For grouped monitors, set perGroup to evaluate each group on its own and drop stale "ghost" groups, so a dead group no longer fails the gate on its own.

yaml
type: io.kestra.plugin.metaplane.Gate

Run a Metaplane monitor and gate the pipeline synchronously on its fresh result

yaml
id: metaplane_sync_gate
namespace: company.team

tasks:
  - id: quality_gate
    type: io.kestra.plugin.metaplane.Gate
    apiToken: "{{ secret('METAPLANE_API_TOKEN') }}"
    monitorIds:
      - "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    runFirst: true
    pollInterval: PT10S
    timeout: PT10M
    failStrategy: FAIL_IF_ANY

  - id: publish
    type: io.kestra.plugin.core.log.Log
    message: "Quality gate passed, publishing. Details: {{ outputs.quality_gate.monitors }}"

Batch-gate several monitors with a staleness check, without triggering a new run

yaml
id: metaplane_batch_gate
namespace: company.team

tasks:
  - id: gate
    type: io.kestra.plugin.metaplane.Gate
    apiToken: "{{ secret('METAPLANE_API_TOKEN') }}"
    monitorIds:
      - "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      - "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    runFirst: false
    maxAge: PT6H
    failStrategy: NONE
    failOn:
      - FAIL
      - ERROR

  - id: report
    type: io.kestra.plugin.core.log.Log
    message: "Gate passed={{ outputs.gate.passed }}, failed monitors={{ outputs.gate.failedMonitorIds }}"

Gate a grouped monitor per group, ignoring stale ghost groups older than maxAge

yaml
id: metaplane_grouped_gate
namespace: company.team

tasks:
  - id: gate
    type: io.kestra.plugin.metaplane.Gate
    apiToken: "{{ secret('METAPLANE_API_TOKEN') }}"
    monitorIds:
      - "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    runFirst: false
    perGroup: true
    maxAge: PT6H
    failStrategy: FAIL_IF_ANY

  - id: report
    type: io.kestra.plugin.core.log.Log
    message: "Gate passed={{ outputs.gate.passed }}, groups={{ outputs.gate.monitors[0].groups }}"
Properties

Metaplane API token

API token used to authenticate against the Metaplane API. Generate one at https://app.metaplane.dev/account/manage-tokens and store it as a Kestra secret.

SubTypestring

Monitor IDs to gate on

UUIDs of the Metaplane monitors to poll and evaluate. Must contain at least one ID.

Defaulthttps://dev.api.metaplane.dev

Metaplane API base URL

Base endpoint for all Metaplane API calls. Defaults to https://dev.api.metaplane.dev.

SubTypestring
Default["FAIL","ERROR"]
Possible Values
PASSIN_TRAININGNOT_ENOUGH_DATAFAILED_TO_PREDICTINVALID_INPUTERRORFAILUNKNOWN

Statuses considered failing

Monitor statuses whose presence counts as a failure for the fail strategy above. Defaults to FAIL and ERROR.

DefaultFAIL_IF_ANY
Possible Values
FAIL_FASTFAIL_IF_ANYFAIL_IF_ALLNONE

Multi-monitor fail strategy

How the effective status of every monitor is combined into a single pass/fail decision:

  • FAIL_FAST: stop polling as soon as one monitor's effective status is in failOn; monitors never reached are reported as pending, not fabricated.
  • FAIL_IF_ANY: the gate fails if at least one monitor's effective status is in failOn. Default.
  • FAIL_IF_ALL: the gate fails only if every monitor's effective status is in failOn.
  • NONE: the gate never fails; failedMonitorIds is still populated for reporting.

Maximum acceptable age of a monitor's result

ISO-8601 duration. Only applied when runFirst is false: a monitor whose result is older than this age is flagged stale and its effective status is escalated to FAIL for the purposes of the gate, regardless of its reported status. Must be at most PT24H (24 hours). Optional, no staleness check is performed by default.

HTTP client options

Optional HTTP configuration (timeouts, proxy, SSL) applied to every Metaplane API call.

Definitions
allowFailedbooleanstring
Defaultfalse

If true, allow a failed response code (response code >= 400)

allowedResponseCodesarray
SubTypeinteger

List of response code allowed for this request

auth

The authentication to use.

type*Requiredobject
passwordstring

The password for HTTP basic authentication.

usernamestring

The username for HTTP basic authentication.

type*Requiredobject
tokenstring

The token for bearer token authentication.

type*Requiredobject
passwordstring

The password for HTTP Digest authentication.

usernamestring

The username for HTTP Digest authentication.

basicAuthPasswordDeprecatedstring

The password for HTTP basic authentication. Deprecated, use auth property with a BasicAuthConfiguration instance instead.

basicAuthUserDeprecatedstring

The username for HTTP basic authentication. Deprecated, use auth property with a BasicAuthConfiguration instance instead.

connectTimeoutDeprecatedstring
Formatduration

The time allowed to establish a connection to the server before failing.

connectionPoolIdleTimeoutDeprecatedstring
Formatduration

The time an idle connection can remain in the client's connection pool before being closed.

defaultCharsetstring
DefaultUTF-8

The default charset for the request.

enabledTcpExtendedKeepAlivebooleanstring
Defaulttrue

Whether to enable TCP Keep-Alive extended socket options (TCP_KEEPIDLE, TCP_KEEPINTERVAL, TCP_KEEPCOUNT).

Set to false when running on Windows workers, as these extended socket options are not supported by the Windows JDK and will cause connection failures.

followRedirectsbooleanstring
Defaulttrue

Whether redirects should be followed automatically.

logLevelDeprecatedstring
Possible Values
ALLTRACEDEBUGINFOWARNERROROFFNOT_SPECIFIED

The log level for the HTTP client.

logsarray
SubTypestring
Possible Values
REQUEST_HEADERSREQUEST_BODYRESPONSE_HEADERSRESPONSE_BODY

The enabled log.

maxContentLengthDeprecatedinteger

The maximum content length of the response.

proxy

The proxy configuration.

addressstring

The address of the proxy server.

passwordstring

The password for proxy authentication.

portintegerstring

The port of the proxy server.

typestring
DefaultDIRECT
Possible Values
DIRECTHTTPSOCKS

The type of proxy to use.

usernamestring

The username for proxy authentication.

proxyAddressDeprecatedstring

The address of the proxy server.

proxyPasswordDeprecatedstring

The password for proxy authentication.

proxyPortDeprecatedinteger

The port of the proxy server.

proxyTypeDeprecatedstring
Possible Values
DIRECTHTTPSOCKS

The type of proxy to use.

proxyUsernameDeprecatedstring

The username for proxy authentication.

readIdleTimeoutDeprecatedstring
Formatduration

The time allowed for a read connection to remain idle before closing it.

readTimeoutDeprecatedstring
Formatduration

The maximum time allowed for reading data from the server before failing.

ssl

The SSL request options

insecureTrustAllCertificatesbooleanstring

Whether to disable checking of the remote SSL certificate.

Only applies if no trust store is configured. Note: This makes the SSL connection insecure and should only be used for testing. If you are using a self-signed certificate, set up a trust store instead.

timeout

The timeout configuration.

connectTimeoutstring

The time allowed to establish a connection to the server before failing.

readIdleTimeoutstring
DefaultPT5M

The time allowed for a read connection to remain idle before closing it.

Defaultfalse

Evaluate grouped monitors per group, excluding stale "ghost" groups

Evaluate each monitor group by group instead of on its single rolled-up status, and drop stale "ghost" groups so a dead group cannot fail the gate on its own. Only live groups are combined; a failing group-by query is ERROR, and an all-ghost monitor is treated as failing.

A group is a ghost when its latest evaluation is older than maxAge, or predates this task's start when runFirst is true. maxAge is therefore required when perGroup is true and runFirst is false.

Costs one extra API call per group per monitor, so it is opt-in. Defaults to false.

Reference (ref) of the pluginDefaults to apply to this task.

DefaultPT10S

Delay between two polls

ISO-8601 duration between poll rounds while runFirst is true and at least one monitor has not yet produced a fresh result. Must be strictly positive and at most PT1H (1 hour). Defaults to PT10S.

Defaultfalse

Run the monitors before gating

When true, enqueues every monitor to run (as Run does) before polling, and only accepts a result whose timestamp is at or after this task's start. When false, no run is triggered: each monitor's current status is read directly. Defaults to false.

DefaultPT10M

Maximum time to wait for a fresh result

ISO-8601 duration. The task fails with an actionable error naming the still-pending monitor(s) if this deadline elapses before every monitor has produced a fresh result. In perGroup mode it also bounds the per-group evaluation-history fan-out, which is checked against this deadline between group reads. Must be strictly positive and at most PT24H (24 hours), since this task blocks the flow execution for its whole duration. Note the actual wait may end up to one pollInterval short of this value, since the loop only starts a new poll round if it can complete before the deadline. Defaults to PT10M.

SubTypestring

IDs of the monitors whose effective status counted as failing

Per-monitor result

One entry per monitorId, in the same order. A monitor never reached because of a timeout or a FAIL_FAST short-circuit only has monitorId set.

Definitions
checkedAtstring
Formatdate-time

Timestamp of the monitor's result, if reported by the API

groupsarray

Per-group evaluation

Populated only when perGroup is true: one entry per group, with its latest evaluation timestamp and whether it was excluded from the gate decision as a stale ghost group. Null in the default monitor-level mode.

evaluatedAtstring
Formatdate-time

Timestamp of this group's latest evaluation

Read from the monitor's evaluation history. Null when the group has no history.

ghostboolean
Defaultfalse

Whether this group was excluded as a stale ghost group

True when the group's latest evaluation is older than the staleness threshold, so it did not count toward the monitor's effective status.

groups

Group-by values identifying this group

Shape not documented by Metaplane, kept opaque, mirrors SeriesStatus.groups.

statusstring
Possible Values
PASSIN_TRAININGNOT_ENOUGH_DATAFAILED_TO_PREDICTINVALID_INPUTERRORFAILUNKNOWN

Latest status reported for this group

monitorIdstring

Monitor ID

seriesarray

Per-series status

Status of each of the monitor's group-by series.

groups

Group-by values identifying this series

Shape not documented by Metaplane, kept opaque.

lowerBoundnumber

Lower bound of the expected range for this series

openRelatedIncidentsarray
SubTypeinteger

IDs of incidents currently open for this series

resultnumber

Observed value for this series

statusstring
Possible Values
PASSIN_TRAININGNOT_ENOUGH_DATAFAILED_TO_PREDICTINVALID_INPUTERRORFAILUNKNOWN

Status of this series

upperBoundnumber

Upper bound of the expected range for this series

staleboolean
Defaultfalse

Whether this result is stale

In monitor-level mode, true when maxAge is set, runFirst is false, and the result is older than maxAge. In perGroup mode, true when every group is a ghost. Either way the effective status is escalated to FAIL for the gate's fail decision even though status stays truthful.

statusstring
Possible Values
PASSIN_TRAININGNOT_ENOUGH_DATAFAILED_TO_PREDICTINVALID_INPUTERRORFAILUNKNOWN

Reported monitor status

The raw status as returned by the API, never escalated by staleness. Null if the monitor was never reached.

Defaultfalse

Whether the gate passed

Always true when failStrategy is NONE.

More Plugins in this Category

Liquibase
Liquibase

Tasks that run Liquibase change management commands.

Data

2 tasks

PostgreSQL
PostgreSQL

Tasks that connect to PostgreSQL via JDBC to run queries and loads.

Data

6 tasks

25 blueprints