Skip to content
📌 OpenRun 1.0 is released, read the announcement
Container Plugin

Container Plugin

The container.in plugin allows configuring and using the container backend for an app.

Introduction

OpenRun can build and manage containers for implementing the app backend APIs. The config API is used to configure at the app level what configuration is used for the container. The sidecar API declares additional containers which run alongside the app container. The run API runs a command inside a container created from the app’s image.

APIs

The container.in plugin has the following APIs:

APITypeNotes
configReadConfigures the container details for the app
sidecarReadDeclares one sidecar container, for config(sidecars=[..])
runWriteRuns a command in a container using the app’s image

The plugin also defines the following constants:

ConstantValueNotes
container.URLPlaceholder for the container URL, for use with the proxy plugin, like proxy.config(container.URL)
container.AUTOautosrc value to auto detect the Containerfile/Dockerfile
container.IMAGE_PREFIXimage:Prefix for the src value when using a prebuilt image
container.COMMANDcommandlifetime value for command-only apps
container.NIXPACKSnixpacksReserved for nixpacks builds, not supported yet

config

The config API supports the following parameters:

ParameterTypeDefaultNotes
srcstringauto (container.AUTO)The source for the containerfile, see the src values below
portintThe port number exposed from the container. port can also be specified in the container file, using an EXPOSE directive; a value other than zero in the config takes precedence over the value in the Expose
schemestringhttpThe url scheme
healthstring/The health check API
lifetimestringstart a service when the app is initializedThe lifetime for the container. Set to container.COMMAND to allow running commands against the container using container.run without starting a service
build_dirstring/The build directory for the build
volumeslist of stringsThe volumes to mount in the container. Supports named volumes (myvolume:/data), bind mounts (./config.yaml:/app/config.yaml) and generated secret mounts (cl_secret:secret.tmpl:/app/secret.ini)
cargsdictThe container build arguments, Containerfile ARG values passed as --build-arg during the image build. Values set in the app metadata with openrun app create --carg key=value or openrun app update carg key=value /myapp override values set here
dev_settingsdictSettings for the dev mode fast reload flow. The allowed keys are target, command, dir, reload, env_files, additional_mounts, port, dev_stage and disable. These settings apply in dev mode only
sidecarslistThe sidecar containers for the app. Each entry must be created with container.sidecar(...), a plain dict is not accepted

The src value selects how the image is built:

src valueBehavior
auto (container.AUTO)The container file is auto detected: checks for presence of either Containerfile or Dockerfile
image:<name> (container.IMAGE_PREFIX)The portion after image: is treated as the image to download. No image build is done
Any other valueTreated as the file name to use as the container file

A sample program using the container config is

app.star
load("proxy.in", "proxy")
load("container.in", "container")

app = ace.app("My App",
              routes=[
                  ace.proxy("/", proxy.config(container.URL))
              ],
              container=container.config(container.AUTO)
       ) 

With the default server config, both proxy.config(container.URL) and container.config(...) are approved implicitly. That default container.config(...) approval does not allow secrets:

  • Add an explicit ace.permission("container.in", "config", ..., secrets=[...]) entry when the app needs to pass secrets to the container, or when you want to narrow the allowed arguments.
  • Declaring the secrets does not by itself grant them: the app still deploys without approval (the config call is allowed by the server config), but the secrets resolve only once the app is approved with openrun app approve or --approve. Create and reload print a warning while the declared access is not approved.
  • The built-in specs declare this permission with their secrets param as the allowlist; it is empty by default, so set it to pass secrets, e.g. --param secrets='[["DB_PASSWORD"]]'.

sidecar

The sidecar API declares one sidecar container: a background worker running the app’s own image with a different command, or a companion service from another image. The result is passed to container.config in the sidecars list. The API supports the following parameters:

ParameterTypeRequiredNotes
namestringyesThe sidecar name, 1 to 20 lower case letters, digits and dashes, starting with a letter or digit. Used as the container name suffix and in the CL_SIDECAR_<NAME>_ADDR env var name
imagestringnoThe image for the sidecar, like image:memcached:1.6-alpine (the image: prefix is optional). If empty, the sidecar runs the app’s own image
commandlist of stringsnoOverrides the image entrypoint. Required for sidecars running the app image, since the image default command is the app’s web server
argslist of stringsnoArguments passed to the command (or to the image entrypoint)
envdictnoThe sidecar’s own environment variables, overlaid on the inherited app env
inherit_envboolnoWhether to copy the app’s env (params, binding env vars, CL_* vars) into the sidecar. Defaults to True for app image sidecars and False for foreign images. The app PORT is never inherited; a sidecar with a port gets PORT set to its own port
portintnoThe port the sidecar listens on. Sidecars with a port are readiness checked before the app container starts, and the app gets CL_SIDECAR_<NAME>_ADDR to reach them. Must differ from the app port and from other sidecars
healthstringnoThe readiness probe for sidecars with a port. Empty does a TCP connect to the port, http:/path does an HTTP GET expecting a 200 response
volumeslist of stringsnoSame syntax as the config volumes; a named volume also used by the app refers to the same volume
always_onboolnoDocker/Podman only, keep the sidecar running when the app container is stopped for idleness. Defaults to True for sidecars without a port (workers) and False for sidecars with a port
optionsdictnoContainer options for the sidecar, same keys as the app container options --copt (kubernetes.cpus, kubernetes.memory, …)

Each container.sidecar call needs its own container.in sidecar permission, with the sidecar name and image as the positional arguments, so foreign images are visible during app approval:

app.star
load("container.in", "container")

app = ace.app("Orders",
    container=container.config(container.AUTO, port=8000,
        sidecars=[
            container.sidecar("cache", "image:memcached:1.6-alpine", port=11211, args=["-m", "64"]),
            container.sidecar("worker", command=["python", "-m", "orders.worker"], env={"ORDERS_ROLE": "worker"}),
        ]),
    permissions=[
        ace.permission("container.in", "sidecar", ["cache", "image:memcached:1.6-alpine"]),
        ace.permission("container.in", "sidecar", ["worker"]),
    ],
)

See Sidecar Containers for details on how sidecars are run and how operators can add sidecars through the app metadata.

run

The run API runs a command inside a new container created from the app’s image (like docker run --rm image command args...), with the app’s environment (params, binding env vars) and configured volumes. The container is removed after the command completes. The API supports the following parameters:

ParameterTypeRequiredNotes
pathstringyesThe command to run inside the container
argslist of stringsnoArguments to pass to the command
process_partialboolnoWhether to process the output when the command fails
stdout_fileboolnoWhether to send the stdout for the command to a temporary file on disk. The response value is then the temp file name; the app is responsible for deleting the file. Not supported with stream
parsestringnoWhether to parse the stdout. Supported options are json (the whole output is one JSON object, returned as a list with that one dict) and jsonlines (each output line is a JSON object, returned as a list of dicts)
streamboolnoReturn the output as a stream which is read as the response is being generated, instead of buffering the full output; an action handler can return it in ace.result(stream=...) to show the output live (see streaming output). Not supported with parse="json"
include_stderrboolno, default TrueWhether to include the stderr output in the command output. If False, stderr is reported only in the error message when the command fails

The response format is the same as the exec plugin run API: a list of output lines by default, parsed JSON with parse, a temp file name with stdout_file. The env and cwd parameters of exec.run are not used in container mode; the container gets the app’s environment.

An app which runs a command against a specified image (see image-cmd spec) is

app.star
load("container.in", "container")

def run(dry_run, args):
    split = args.command.split(" ")
    res = container.run(split[0], split[1:], parse="json" if args.json else "").value
    return ace.result("Command output", res)

app = ace.app(param.app_name + " : " + param.image ,
    actions=[
       ace.action("Run Command using " + param.image, "/", run, description="Run specified command in container", hidden=["secrets", "app_name", "image"])
    ],
    container=container.config("image:" + param.image, lifetime=container.COMMAND),
    permissions=[
       ace.permission("container.in", "run", secrets=param.secrets)
    ]
)

The explicit container.in.run permission is still required in this example. container.config(...) is implicitly approved by default without secret access; see the config section for when an explicit ace.permission("container.in", "config", ..., secrets=[...]) entry is needed and how the declared secrets get approved.