Sidecar Buildpacks
Page last updated:
This topic describes how buildpacks deploy sidecar processes alongside an app.
Overview
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.
How Buildpacks Specify Sidecar Processes
A buildpack can specify sidecar processes by writing a launch.yml
at the root of its deps
directory during the supply
phase. This 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
in more detail:
type
: A key that is mapped to a individual command.Note: It is possible for multiple buildpacks to write their own
launch.yml
files. If two of these files have the sametype
keys, thelaunch.yml
written last overwrites the previous commands of the sametype
.command
: The command to be run in the container. Container health is dependent on this command, and the container fails when the command is no longer running.limits
: Resource limits to be placed on the sidecar process.memory
: The memory limit in MB. If you are using the sidecar buildpack with a Java app, you must configure this field to allocate memory to the sidecar. If you do not, the Java buildpack allocates all of the available memory to the app.platforms
: A key specifying the data that should be read by a platform. For example, Cloud Foundry only reads data under thecloudfoundry
key.sidecar_for
: A list oftypes
that thecommand
is a sidecar process for.Note: Each
type
requires a health check, thecommand
cannot run until each health check is passed. The moretype
s that are listed, the more health checks are required. If any health check fails, thecommand
does not run.
See the example launch.yml
below:
---
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 thetype
field.COMMAND
is the command that is mapped to thecommand
field. For example,./binary
orjava -jar java-file.jar
.TYPE-1
,TYPE-2
andTYPE-3
are thetype
s that thecommand
is a sidecar process for.
Example Buildpack
This buildpack functions as a supply buildpack, or the non-final buildpack in a multi-buildpack build. Its only purpose is to write the launch.yml
file to the buildpack’s deps
directory.
For the full sidecar buildpack described below, see the 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 example below:
#!/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
Create a pull request or raise an issue on the source for this page in GitHub