Permalink
Fetching contributors…
Cannot retrieve contributors at this time
291 lines (197 sloc) 8.52 KB

Available Actions

The work performed by a Task or LRP is expressed in terms of composable Actions.

The following actions are available. The details are presented below:

  • RunAction: runs a process in the container
  • DownloadAction: fetches an archive (.tgz or .zip) and extracts it into the container
  • UploadAction: uploads a single file, in the container, to a URL via POST
  • ParallelAction: runs multiple actions in parallel.
  • CodependentAction: runs multiple actions in parallel and exits all actions after any action exits
  • SerialAction: runs multiple actions in order.
  • EmitProgressAction: wraps another action and logs messages when the wrapped action begins and ends.
  • TimeoutAction: fails if the wrapped action does not exit within a time interval.
  • TryAction: runs the wrapped action but ignores errors generated by the wrapped action.

RunAction

The run action runs a process in the container:

{
    "run": {
        "path": "/path/to/executable",
        "args": ["some", "args to", "pass in"],
        "dir": "/path/to/working/directory",
        "env": [
            {"name": "ENVNAME", "value": "ENVVALUE"},
        ],
        "resource_limits": {
            "nofile": N,
        },
        "user": "username",
        "log_source": "some-log-source"
    }
}

path [required]

The path to the executable.

dir [optional]

The working directory in which to execute the process.

args [optional]

An array of command line arguments for the executable.

env [optional]

A list of environment variables. These are applied on top of any container-level environment variables.

resource_limits [optional]

A set of constraints to apply to the process. Currently only file descriptor limits (nofile) are enforceable.

user [required]

The user that runs the action. Running as 'root' may be disabled by the operator managing Diego. If it is disabled, the RunAction will fail. If the associated Task/LRP has the container-level privileged flag set to true then this will correspond to real root, otherwise the process will be run as a user-namespaced root.

log_source [optional]

If provided, logs emitted by this process will be tagged with the provided log_source. Otherwise the container-level log_source is used.

DownloadAction

The download action downloads an archive and extracts it to a specified location:

{
    "download": {
        "artifact": "download name"
        "from": "http://some/endpoint",
        "to": "/some/container/path",
        "user": "username",
        "cache_key": "some-cache-key",
        "log_source": "some-log-source"
    }
}

artifact [optional]

If specified, additional logs will be emitted to signify the progress of the download action including the bytes downloaded.

from [required]

The url from which to fetch the archive. The downloaded asset must be a gzipped tarball, or a zip archive.

to [required]

The absolute path to extract the archive into.

user [required]

The user that downloads the artifact. Running as 'root' may be disabled by the operator managing Diego. If it is disabled, the DownloadAction will fail. If the associated Task/LRP has the container-level privileged flag set to true then this will correspond to real root, otherwise the download will be run as a user-namespaced root.

cache_key [optional]

If specified, Diego will cache the downloaded asset. The cached downloaded user ETag and LastModified headers to invalidate the cache.

log_source [optional]

If provided, logs emitted by this action will be tagged with the provided log_source. Otherwise the container-level log_source is used.

UploadAction

The upload action uploads a file to the specified location:

{
    "upload": {
        "artifact": "upload name"
        "to": "http://some/endpoint",
        "from": "/some/container/file",
        "user": "username",
        "log_source": "some-log-source"
    }
}

artifact [optional]

If specified, additional logs will be emitted to signify the progress of the upload action including the bytes uploaded.

from [required]

The absolute path to a file in the container.

to [required]

A URL to upload the file to. The upload will be an HTTP POST.

user [required]

The user that uploads the artifact. Running as 'root' may be disabled by the operator managing Diego. If it is disabled, the UploadAction will fail. If the associated Task/LRP has the container-level privileged flag set to true then this will correspond to real root, otherwise the upload will be run as a user-namespaced root.

log_source [optional]

If provided, logs emitted by this action will be tagged with the provided log_source. Otherwise the container-level log_source is used.

SerialAction

{
    "serial": {
        "actions": [
            { ...an embedded action... },
            { ...an embedded action... },
            ...
        ]
        "log_source": "some-log-source"
    }
}

actions [required]

An array of embedded actions to run. The actions are run in series.

If an action fails the serial action returns with the failure. Subsequent actions are not run.

log_source [optional]

If provided, logs emitted by this action and its subactions will be tagged with the provided log_source. Otherwise the container-level log_source is used.

ParallelAction

{
    "parallel": {
        "actions": [
            { ...an embedded action... },
            { ...an embedded action... },
            ...
        ]
        "log_source": "some-log-source"
    }
}

actions [required]

An array of embedded actions to run. The actions are run in parallel.

The parallel action returns after all actions have returned. The parallel action errors if any of the actions error, returning the first error it sees.

log_source [optional]

If provided, logs emitted by this action and its subactions will be tagged with the provided log_source. Otherwise the container-level log_source is used.

CodependentAction

{
    "codependent": {
        "actions": [
            { ...an embedded action... },
            { ...an embedded action... },
            ...
        ]
        "log_source": "some-log-source"
    }
}

actions [required]

An array of embedded actions to run. The actions are run in parallel.

The codependent action returns after any action exits. The codependent action always errors as it is intended to run indefinitely.

log_source [optional]

If provided, logs emitted by this action and its subactions will be tagged with the provided log_source. Otherwise the container-level log_source is used.

EmitProgressAction

{
    "emit_progress": {
        "action": { ...an embedded action... },
        "start_message": "some message",
        "success_message": "some message",
        "failure_message_prefix": "some message",
        "log_source": "some-log-source"
    }
}

action [required]

The action to run.

start_message [optional]

If present, a message to emit before the action runs.

success_message [optional]

If present, a message to emit when the action succeeds.

failure_message_prefix [optional]

If present, a message to emit when the action fails. The corresponding error if emittable will be appended with a ':' separator.

log_source [optional]

If provided, logs emitted by this action and its subaction will be tagged with the provided log_source. Otherwise the container-level log_source is used.

TimeoutAction

{
    "timeout": {
        "action": { ...an embedded action... },
        "timeout": N (in nanoseconds)
    }
}

action [required]

The action to run.

timeout [required]

The number of nanoseconds (1 second = 1e9 nanoseconds) to wait before giving up on the action and failing. timeout must be greater than 0.

TryAction

{
    "try": {
        "action": { ...an embedded action... },
        "log_source": "some-log-source"
    }
}

action [required]

The action to run. Errors generated by the action are swallowed by the TryAction.

log_source [optional]

If provided, logs emitted by this action and its subaction will be tagged with the provided log_source. Otherwise the container-level log_source is used.

back