Buildpack API

This specification defines the interface between a buildpack and the environment that runs it. This API will be used by buildpack authors.

A buildpack must contain three files:

  • buildpack.toml
  • bin/detect
  • bin/build

The two files in bin/ must be executable. They can be shell scripts written in a language like Bash or they can be executables compiled from a language like Go.

bin/detect

Usage

bin/detect PLATFORM_DIR BUILD_PLAN

Summary

This entrypoint is used to determine if a buildpack should run against a given codebase. It will often check for the existence of a particular file or some configuration indicating what kind of application has been provided. It accepts two positional arguments:

  • PLATFORM_DIR - a directory containing platform provided configuration, such as environment variables.
  • BUILD_PLAN - a string containing the Build Plan.

In addition, the working directory is defined as the location of the codebase the buildpack will execute against.

The executable must return an exit code of 0 if the codebase can be serviced by this buildpack. If the exit code is 0, the script must print a human-readable name to stdout.

Example

This is a simple example of a buildpack that detects a Python application by checking for the presence of a requirements.txt file:

#!/bin/sh

if [ -f requirements.txt ]; then
  echo "Python Buildpack"
  exit 0
else
  exit 1
fi

bin/build

Usage

bin/build LAYERS_DIR PLATFORM_DIR BUILD_PLAN

This entrypoint transforms a codebase. It will often resolve dependencies, install binary packages, and compile code. It accepts three positional arguments:

  • LAYERS_DIR - a directory that may contain subdirectories representing each layer created by the buildpack in the final image or build cache.
  • PLATFORM_DIR - a directory containing platform provided configuration, such as environment variables.
  • BUILD_PLAN - a string containing the Build Plan.

In addition, the working directory is defined as the location of the codebase this buildpack will execute against.

All changes to the codebase in the working directory will be included in the final image, along with any launch layers created in the LAYERS_DIR.

Layers

Each directory created by the buildpack under the LAYERS_DIR can be used for any of the following purposes:

  • Launch - the directory will be included in the run image as a single layer
  • Cache - the directory will be included in the cache
  • Build - the directory will be accessible by subsequent buildpacks

A buildpack defines how a layer will by used by creating a <layer>.toml with a name matching the directory it describes in the LAYERS_DIR. For example, a buildpack might create a $LAYERS_DIR/python directory and a $LAYERS_DIR/python.toml with the following contents:

launch = true
cache = true
build = true

In this example, the python directory will be included in the run image, cached for future builds, and will be accessible to subsequent buildpacks.

Example

This is a simple example of a buildpack that runs Python’s pip package manager to resolve dependencies:

#!/bin/sh

LAYERS_DIR="$1"

PIP_LAYER="$LAYERS_DIR/pip"
mkdir -p "$PIP_LAYER/modules" "$PIP_LAYER/env"

pip install -r requirements.txt -t "$PIP_LAYER/modules" \
  --install-option="--install-scripts=$PIP_LAYER/bin" \
  --exists-action=w --disable-pip-version-check --no-cache-dir

echo "launch = true" > "$PIP_LAYER.toml"

buildpack.toml

A buildpack must contain a buildpack.toml file in its root directory.

Example

api = "0.2"

[buildpack]
id = "example.com/python"
version = "1.0"

[[stacks]]
id = "io.buildpacks.stacks.bionic"

Schema

The schema is as follows:

  • api (string, required, current: 0.2)
    The Buildpack API version the buildpack adheres to. Used to ensure compatibility against the lifecycle.

    Not to be confused with Cloud Foundry or Heroku buildpack versions. This version pertains to the interface between the buildpack and the lifecycle of Cloud Native Buildpacks.

  • buildpack (required)
    Information about the buildpack.

    • id (string, required)
      A globally unique identifier.

    • version (string, required)
      The version of the buildpack.

    • name (string, required)
      Human readable name.

    • clear-env (boolean, optional, default: false)
      Clears user-defined environment variables when true on executions of bin/detect and bin/build.

  • stacks (list, optional)
    A list of stacks supported by the buildpack. If omitted, order list must be present. Cannot be used in conjunction with order list.

    • id (string, required)
      The id of the supported stack.

    • mixins (string list, required)
      A list of mixins required on the stack images.

  • order (list, optional)
    A list of buildpack groups for the purpose of creating a meta-buildpack. This list determines the order in which groups of buildpacks will be tested during detection. If omitted, stacks list must be present. Cannot be used in conjunction with stacks list.

    • group (list, required)
      A list of buildpack references.

      • id (string, required)
        The identifier of a buildpack being referred to. Buildpacks with the same ID may appear in multiple groups at once but never in the same group.

      • version (string, required)
        The version of the buildpack being referred to.

      • optional (boolean, optional, default: false)
        Whether or not this buildpack is optional during detection.

  • metadata (any, optional)
    Arbitrary data for buildpack.

API Compatibility

Given the buildpack and lifecycle both declare a Buildpack API version in format:
<major>.<minor>

Then a buildpack and a lifecycle are considered compatible if all the following conditions are true:

  • If versions are pre-release, where <major> is 0, then <minor>s must match.
  • If versions are stable, where <major> is greater than 0, then <minor> of the buildpack must be less than or equal to that of the lifecycle.
  • <major>s must always match.

For example,

Buildpack implements Buildpack API Lifecycle implements Buildpack API Compatible?
0.2 0.2 yes
1.1 1.1 yes
1.2 1.3 yes
0.2 0.3 no
0.3 0.2 no
1.3 1.2 no
1.3 2.3 no
2.3 1.3 no

Further Reading

You can read the complete Buildpack API specification on Github.