Sidecar buildpacks

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.

Specifying sidecar processes

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 types 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 types that the command uses for the sidecar process.

Buildpack example

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