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 same type keys, the launch.yml 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, 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 the cloudfoundry key.

• sidecar_for: A list of types that the command is a sidecar process for.

  Note: 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.

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 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 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