Learn how buildpacks deploy sidecar processes alongside your app.
Sidecar processes are additional dependent processes that are run in the same container as the main app process. For more information, see How to Push an App to Cloud Foundry with Sidecars.
A buildpack can specify sidecar processes with a launch.yml
file at the root of the deps
directory during the supply
phase. The deps
directory is a combination of the DEPS_DIR
and DEP_IDX
values. For more information about how these two values are passed to the buildpack interface, see How buildpacks work.
The following defines the relevant fields of the launch.yml
file in more detail:
type
: A key that is mapped to a individual command.
It is possible for multiple buildpacks to write their own launch.yml
files. If two of these files have the same type
keys, the launch.yml
file written last overwrites the previous commands of the same type
.
command
: The command to be run in the container. Container health is dependent on this command. The container fails when the command is no longer running.
limits
: Resource limits that are placed on the sidecar process.
memory
: The memory limit is in MB. If you use the sidecar buildpack with a Java app, you must configure this field to allocate memory to the sidecar. If you do not configure the field, the Java buildpack allocates all of the available memory to the app.
platforms
: A key specifying the data that must be read by a platform. For example, Cloud Foundry only reads data under the cloudfoundry
key.
sidecar_for
: A list of types
that the command
uses for a sidecar process. Each type
requires a health check. The command
cannot run until each health check is passed. The more type
s that are listed, the more health checks are required. If any health check fails, the command
does not run.
Example launch.yml
file:
---
processes:
- type: "PROCESS-NAME"
command: "COMMAND"
limits:
memory: 10
platforms:
cloudfoundry:
sidecar_for: [ "TYPE-1", "TYPE-2", "TYPE-3"]
Where:
PROCESS-NAME
is the command that is mapped to the type
field.
COMMAND
is the command that is mapped to the command
field. For example, ./binary
or java -jar java-file.jar
.
TYPE-1
, TYPE-2
and TYPE-3
are the type
s that the command
uses for the sidecar process.
The following buildpack example functions as a supply buildpack, or the non final buildpack in a multi buildpack build. The only purpose for this function is to write the launch.yml
file to the buildpack’s deps
directory.
For the full sidecar buildpack, see example-sidecar-buildpack repository on GitHub.
The example-sidecar-buildpack
has the following directory structure:
bin/
bin/supply
manifest.yml
VERSION
The supply
script writes a launch.yml
file to a specific location, bin/supply
, as in the following example:
#!/bin/bash
set -euo pipefail
BUILD_DIR=$1
CACHE_DIR=$2
DEPS_DIR=$3
DEPS_IDX=$4
LAUNCH_CONTENTS='---
processes:
- type: "sidecar_process"
command: "while true; do echo hello from a sidecar process; sleep 10; done"
platforms:
cloudfoundry:
sidecar_for: [ "web"]
'
echo "-----> Running sidecar supply"
export BUILDPACK_DIR=`dirname $(readlink -f ${BASH_SOURCE%/*})`
pushd "$BUILDPACK_DIR"
echo "$LAUNCH_CONTENTS" > "$DEPS_DIR"/"$DEPS_IDX"/launch.yml
popd