Skip to main content

Specification

info

This feature is in beta. Please leave feedback via our community GitHub or Slack.

Overview​

A Signadot Job specification describes how to execute code within the context defined by its associated JobRunnerGroup.

Here is an example:

spec:
  namePrefix: my-job
  runnerGroup: my-runner-group
  labels:
    my-custom-label: foo
    env: bar
  script: |
    #!/bin/sh
    echo hello > /tmp/my-artifact.txt
  uploadArtifacts:
  - path: /tmp/my-artifact.txt
  routingContext:
    sandbox: my-sandbox
  trafficManager:
    injectRoutingKey: auto

This document details all the fields and constraints associated with a valid job specification.

Usage​

A job spec is used to submit a job with the CLI. Once submitted, the spec is immutable.

Fields​

spec.runnerGroup​

runnerGroup is a required field specifying the name of the associated JobRunnerGroup.

spec.namePrefix​

The namePrefix field is an optional field specifying the prefix of the name of submitted jobs. The namePrefix must

  • be no longer than 32 bytes in length.
  • match the regular expression [a-zA-Z0-9-_]*.

Once a spec is submitted, a Job is returned with a name whose prefix is .spec.namePrefix.

spec.script​

A job spec must specify exactly one of spec.script or spec.command.

A script is a string that is run in a shell in the home directory of the default user of the main container in the Pod defined by the associated JobRunnerGroup.

A script must start with #!.

Example:

scipt: |
  #!/bin/sh
  echo hey there

The environment variable $SIGNADOT_ROUTING_KEY is available and set to the routing key of the sandbox or routegroup associated with the job, if any.

spec.command​

A job spec must specify exactly one of spec.script or spec.command.

A command is a string array corresponding to the command line arguments. For example

command:
- ls
- -l

The environment variable $SIGNADOT_ROUTING_KEY is available and set to the routing key of the sandbox or routegroup associated with the job, if any.

spec.uploadArtifacts​

The uploadArtifacts field specifies files to upload once the script or command has completed. It is an array of objects each specifying the expected path of a file to upload and optionally, some associated metadata:

uploadArtifacts:
- path: /tmp/out-1.txt
  meta:
    someKey: someValue

An associated job artifact will be created if the path exists once the script or command has completed.

Job artifacts are then accessible via the CLI or dashboard.

The meta field has the same restrictions as the spec.labels field, specified below.

spec.routingContext​

The routingContext field is an optional field which defines a sandbox or routegroup which is associated with the Job. If specified, the execution of the job will monitored for sandbox or routegroup readiness. If the associated sandbox or routegroup becomes not ready, the job will be re-queued.

Examples:

routingContext:
  sandbox: my-sandbox
---
routingContext:
  routegroup: my-routegroup

Exactly 1 of sandbox or routegroup must be specified.

spec.trafficManager​

The trafficManager field is an optional field which defines the traffic-related settings of the Job.

spec.trafficManager.injectRoutingKey​

injectRoutingKey is an optional field that accepts the following values: auto and disabled. When set to auto all the outgoing traffic from the Job will be intercepted by a proxy (running alongside the main container of the Job Runner pod), and based on the specified spec.routingContext, routing key headers will be automatically injected for all non-TLS HTTP-based traffic (including gRPC). TLS and non-HTTP based traffic will be treated as TCP pass-through. In this context, server-first protocols (e.g.: MySQL protocol) are likely to timeout unless appProtocol is set in the destination Service.

The default value for injectRoutingKey is disabled.

Note

This feature requires version v0.8.1+ of the Signadot CLI and v0.18+ of the Signadot Operator.

spec.labels​

Labels are a map from strings to strings, for example

spec:
  labels:
    dev: jane
    feature: x

A label key must not exceed 255 bytes in length and must contain at least 1 character. Additionally, it must contain only the characters

A-Z // upercase alphabetic
a-z // lowercase alphabetic
0-9 // numeric
-   // dash
_   // underscore

A label value can be an arbitrary string which also must not exceed 255 bytes in length and must contain at least one character. However, value contents are not otherwise restricted.

Job labels are optional and immutable.