From b9b93960299088c831fe57baa08ee474b081c474 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Mon, 15 Nov 2021 21:32:24 +0530 Subject: [PATCH 01/10] feat: buildpacks builder distribution specs Signed-off-by: Jimil Desai --- distribution.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/distribution.md b/distribution.md index a3a1cf4a..69e795ad 100644 --- a/distribution.md +++ b/distribution.md @@ -228,3 +228,72 @@ The Run Image SHOULD contain the following Labels on the image configuration: Where, `` is an identifier specified on the runtime image that MAY be used to apply target-specific logic. +### Builder + +The following specifies the artifact format for a buildpacks builder. + +A Builder is an OCI Image that provides a distributable build environment. + +A platform supporting the builder SHOULD allow users to configure the build environment with a provided builder. + +#### General Requirements + +The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and [build-time](#build-image) environment and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process. + +#### Environment Variables + +A Builder MUST be an extension of a build-image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. + +#### Labels + +A Builder MUST be an extension of a build-image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications. + +A Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications. + +A Builder image MAY contain [buildpacks](#buildpackage), and MAY retain all the specified Labels set on the original buildpackage, as specified in the buildpackage specifications. + +The following labels MUST be set in the builder environment (through the image config's `Labels` field): + +| Label | Description +| -------- | -------- +| `io.buildpacks.builder.metadata` | A JSON object representing Builder metadata +| `io.buildpacks.buildpack.order` | A JSON object representing the order of the buildpacks stored on the builder + +`io.buildpacks.builder.metadata` (JSON) + +```json +{ + "description": "", + "buildpacks": [ + { + "id": "", + "version": "", + "homepage": "", + } + ], + "createdBy": { + "name": "", + "version": "", + } +} +``` + +The `createdBy` metadata is meant to contain the name and version of the tool that created the builder. + +`io.buildpacks.buildpack.order` (JSON) + +```json +[ + { + "group": + [ + { + "id": "", + "version": "", + "optional": false + } + ] + } +] + +``` From 0e8bfd6d094ab990dd7fb0cbce4376a3aa7e8da8 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Tue, 30 Nov 2021 13:46:32 +0530 Subject: [PATCH 02/10] fix: avoid hyphenating Signed-off-by: Jimil Desai --- distribution.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/distribution.md b/distribution.md index 69e795ad..6fb0ae0f 100644 --- a/distribution.md +++ b/distribution.md @@ -242,11 +242,11 @@ The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), #### Environment Variables -A Builder MUST be an extension of a build-image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. +A Builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. #### Labels -A Builder MUST be an extension of a build-image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications. +A Builder MUST be an extension of a Build Image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications. A Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications. From 5b920df0e5134c19b1f4b02c23ac587982f344aa Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Mon, 6 Dec 2021 21:36:45 +0530 Subject: [PATCH 03/10] add buildpacks path variation Signed-off-by: Jimil Desai --- distribution.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/distribution.md b/distribution.md index 6fb0ae0f..611bf280 100644 --- a/distribution.md +++ b/distribution.md @@ -48,6 +48,8 @@ Each buildpack layer blob MUST contain a single [buildpack](./buildpack.md) at t /cnb/buildpacks/// ``` +If the buildpack ID contains a `/`, it must be replaced with `_` in the directory name. + A buildpack MUST contain a `buildpack.toml` file at its root directory. #### Labels From 1418e4aac2600ecc087935364b03ba38bacf5b29 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Mon, 6 Dec 2021 21:50:20 +0530 Subject: [PATCH 04/10] feat: add builder environment variables Signed-off-by: Jimil Desai --- distribution.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/distribution.md b/distribution.md index 611bf280..03805f9f 100644 --- a/distribution.md +++ b/distribution.md @@ -246,6 +246,21 @@ The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), A Builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. +The following environment variables MUST be set on the builder (through the image config's `Env` field): + +| Env Variable | Description | Default +| -------- | -------- |----------- +| `CNB_APP_DIR` | Application directory of the build environment | `/workspace` +| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment | `/layers` +| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment | `/platform` + +The following variables MAY be set on the builder (through the image config's `Env` field): + +| Env Variable | Description | Default +| -------- | -------- |----------- +| `SERVICE_BINDING_ROOT` | The directory where services are bound | - + + #### Labels A Builder MUST be an extension of a Build Image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications. From f6c99de4e068cbdd10dd74269538defa2913a8c1 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Fri, 10 Dec 2021 12:56:04 +0530 Subject: [PATCH 05/10] update env vars from MUST to MAY Signed-off-by: Jimil Desai --- distribution.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/distribution.md b/distribution.md index 03805f9f..3619cc08 100644 --- a/distribution.md +++ b/distribution.md @@ -246,19 +246,14 @@ The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), A Builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. -The following environment variables MUST be set on the builder (through the image config's `Env` field): +The following environment variables MAY be set on the builder (through the image config's `Env` field): | Env Variable | Description | Default | -------- | -------- |----------- | `CNB_APP_DIR` | Application directory of the build environment | `/workspace` | `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment | `/layers` | `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment | `/platform` - -The following variables MAY be set on the builder (through the image config's `Env` field): - -| Env Variable | Description | Default -| -------- | -------- |----------- -| `SERVICE_BINDING_ROOT` | The directory where services are bound | - +| `SERVICE_BINDING_ROOT` | The directory where services are bound | - #### Labels From 9369ccd4b4aa1deb2f4e05d5445e5e673d420183 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Wed, 22 Dec 2021 18:01:30 +0530 Subject: [PATCH 06/10] minor tweaks Signed-off-by: Jimil Desai --- distribution.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/distribution.md b/distribution.md index 3619cc08..b2472870 100644 --- a/distribution.md +++ b/distribution.md @@ -230,17 +230,18 @@ The Run Image SHOULD contain the following Labels on the image configuration: Where, `` is an identifier specified on the runtime image that MAY be used to apply target-specific logic. + ### Builder The following specifies the artifact format for a buildpacks builder. A Builder is an OCI Image that provides a distributable build environment. -A platform supporting the builder SHOULD allow users to configure the build environment with a provided builder. +A platform supporting builders SHOULD allow users to configure the build environment for a provided builder. #### General Requirements -The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and [build-time](#build-image) environment and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process. +The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and a [build-time](#build-image) environment, and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process. #### Environment Variables From 928840b9a87417157cef9619203173ea0b8c5735 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Wed, 22 Dec 2021 18:08:08 +0530 Subject: [PATCH 07/10] add order.toml in the builder fs Signed-off-by: Jimil Desai --- distribution.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/distribution.md b/distribution.md index b2472870..f6a79e82 100644 --- a/distribution.md +++ b/distribution.md @@ -243,6 +243,12 @@ A platform supporting builders SHOULD allow users to configure the build environ The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and a [build-time](#build-image) environment, and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process. +#### Filesystem + +A builder MUST have the following directories/files: + +* `/cnb/order.toml` → As defined in the [platform specification](https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml) + #### Environment Variables A Builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. From 14cbc7b3b2b6c8e0a1f3a256bcc836e343890a07 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Thu, 6 Jan 2022 11:32:15 +0530 Subject: [PATCH 08/10] change builder case to smaller case Signed-off-by: Jimil Desai --- distribution.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/distribution.md b/distribution.md index f6a79e82..9e9ce5cd 100644 --- a/distribution.md +++ b/distribution.md @@ -235,13 +235,13 @@ Where, The following specifies the artifact format for a buildpacks builder. -A Builder is an OCI Image that provides a distributable build environment. +A builder is an OCI Image that provides a distributable build environment. A platform supporting builders SHOULD allow users to configure the build environment for a provided builder. #### General Requirements -The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and a [build-time](#build-image) environment, and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process. +The builder image MUST contain an implementation of the [lifecycle](#lifecycle), and a [build-time](#build-image) environment, and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process. #### Filesystem @@ -251,7 +251,7 @@ A builder MUST have the following directories/files: #### Environment Variables -A Builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. +A builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications. The following environment variables MAY be set on the builder (through the image config's `Env` field): @@ -265,17 +265,17 @@ The following environment variables MAY be set on the builder (through the image #### Labels -A Builder MUST be an extension of a Build Image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications. +A builder MUST be an extension of a Build Image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications. -A Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications. +A builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications. -A Builder image MAY contain [buildpacks](#buildpackage), and MAY retain all the specified Labels set on the original buildpackage, as specified in the buildpackage specifications. +A builder image MAY contain [buildpacks](#buildpackage), and MAY retain all the specified Labels set on the original buildpackage, as specified in the buildpackage specifications. The following labels MUST be set in the builder environment (through the image config's `Labels` field): | Label | Description | -------- | -------- -| `io.buildpacks.builder.metadata` | A JSON object representing Builder metadata +| `io.buildpacks.builder.metadata` | A JSON object representing builder metadata | `io.buildpacks.buildpack.order` | A JSON object representing the order of the buildpacks stored on the builder `io.buildpacks.builder.metadata` (JSON) From eee0b60fb76ac0504c4ebdb821c986c0228cc9b4 Mon Sep 17 00:00:00 2001 From: Jimil Desai Date: Thu, 6 Jan 2022 11:33:44 +0530 Subject: [PATCH 09/10] minor nit Signed-off-by: Jimil Desai --- distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/distribution.md b/distribution.md index 9e9ce5cd..b88162aa 100644 --- a/distribution.md +++ b/distribution.md @@ -48,7 +48,7 @@ Each buildpack layer blob MUST contain a single [buildpack](./buildpack.md) at t /cnb/buildpacks/// ``` -If the buildpack ID contains a `/`, it must be replaced with `_` in the directory name. +If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name. A buildpack MUST contain a `buildpack.toml` file at its root directory. From 35e5cce6acb83cfa018f61dc0bc90019375b8702 Mon Sep 17 00:00:00 2001 From: Javier Romero Date: Wed, 26 Jan 2022 13:08:53 +0000 Subject: [PATCH 10/10] Changes to labels, remove defaults from Env Var - Rename `io.buildpacks.buildpackages` => `io.buildpacks.buildpack` - Remove `io.buildpacks.builder.metadata`.`buildpacks` - Duplicate data from `io.buildpacks.buildpack.layers` - Unset `io.buildpacks.buildpack.metadata` on builder - Update TOC Signed-off-by: Javier Romero --- distribution.md | 215 +++++++++++++++++++++++++----------------------- 1 file changed, 111 insertions(+), 104 deletions(-) diff --git a/distribution.md b/distribution.md index b88162aa..b3cc07c9 100644 --- a/distribution.md +++ b/distribution.md @@ -2,27 +2,46 @@ This document specifies the artifact format and the delivery mechanism for the buildpacks core components. - ## Table of Contents - -- [Distribution Specification](#distribution-specification) - - [Table of Contents](#table-of-contents) - - [Distribution API Version](#distribution-api-version) - - [Artifact Format](#artifact-format) - - [Buildpackage](#buildpackage) - - [Lifecycle](#lifecycle) - - [Build Image](#build-image) - - [Run Image](#run-image) + + +- [Table of Contents](#table-of-contents) +- [Distribution API Version](#distribution-api-version) +- [Artifact Format](#artifact-format) + - [Buildpackage](#buildpackage) + - [Labels](#labels) + - [`io.buildpacks.buildpack.metadata` (JSON)](#iobuildpacksbuildpackmetadata-json) + - [`io.buildpacks.buildpack.layers` (JSON)](#iobuildpacksbuildpacklayers-json) + - [Lifecycle](#lifecycle) + - [Filesystem](#filesystem) + - [Labels](#labels) + - [Build Image](#build-image) + - [Image Configuration](#image-configuration) + - [Environment Variables](#environment-variables) + - [Labels](#labels) + - [Run Image](#run-image) + - [Image Configuration](#image-configuration) + - [Environment Variables](#environment-variables) + - [Labels](#labels) + - [Builder](#builder) + - [General Requirements](#general-requirements) + - [Filesystem](#filesystem) + - [Environment Variables](#environment-variables) + - [Labels](#labels) + - [`io.buildpacks.builder.metadata` (JSON)](#iobuildpacksbuildermetadata-json) + + ## Distribution API Version This document specifies Distribution API version `0.3`. Distribution API versions: - - MUST be in form `.` or ``, where `` is equivalent to `.0` - - When `` is greater than `0` increments to `` SHALL exclusively indicate additive changes - - Each Distributable artifact MUST contain the label `io.buildpacks.distribution.api` denoting the distribution API + +- MUST be in form `.` or ``, where `` is equivalent to `.0` +- When `` is greater than `0` increments to `` SHALL exclusively indicate additive changes +- Each Distributable artifact MUST contain the label `io.buildpacks.distribution.api` denoting the distribution API ## Artifact Format @@ -37,7 +56,6 @@ A buildpackage MUST exist in one of the following formats: * An uncompressed tar archive in [oci-layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format. * The file SHOULD have the extension `.cnb`. - [†](README.md#linux-only)For Linux buildpackages, all FS layers MUST be buildpack layers. [‡](README.md#windows-only)For Windows buildpackages, all FS layers MUST be either buildpack or OS layers. @@ -54,58 +72,61 @@ A buildpack MUST contain a `buildpack.toml` file at its root directory. #### Labels -For each buildpack layer, the buildpack ID and the buildpack version MUST be provided in `io.buildpacks.buildpackage.layers` - The following labels MUST be set in the buildpack image(through the image config's `Labels` field): -| Label | Description | -| -------- | -------- -| `io.buildpacks.buildpackage.metadata` | A JSON object representing Buildpack Metadata | -| `io.builpacks.buildpackage.layers`| A JSON object representing the buildpack layers | +| Label | Description | +| ------------------------------------ | ------------------------------------------------------------------------------------------------- | +| `io.buildpacks.buildpack.metadata` | A JSON object representing information about the packaged entrypoint buildpack | +| `io.buildpacks.buildpack.layers` | A JSON object representing information about all packaged buildpacks and their associated layers. | +##### `io.buildpacks.buildpack.metadata` (JSON) -`io.buildpacks.buildpackage.metadata` (JSON) ```json { - "id": "", - "name": "", - "version": "", - "homepage": "", + "name": "", + "version": "", + "homepage": "", } ``` -`io.buildpacks.buildpackage.layers` (JSON) +##### `io.buildpacks.buildpack.layers` (JSON) + ```json { - "": { - "": { - "api": "", + # schema of a meta-buildpack + "": { + "": { + "api": "", "order": [ { "group": [ { - "id": "", - "version": "" + "id": "", + "version": "" } ] } ], - "layerDiffID": "", - "homepage": "", - "name": "", + "layerDiffID": "", + "homepage": "", + "name": "" } }, - "": { - "": { - "api": "", - "layerDiffID": "", - "homepage": "", - "name": "", + # schema of a regular buildpack + "": { + "": { + "api": "", + "layerDiffID": "", + "homepage": "", + "name": "" } } } ``` +For each buildpack layer, the buildpack ID and the buildpack version MUST be provided in `io.buildpacks.buildpack.layers`. + The buildpack ID and version MUST match a buildpack provided by a layer blob. For a buildpackage to be valid, each `buildpack.toml` describing a buildpack implementation MUST have all listed targets. @@ -128,12 +149,12 @@ A lifecycle image MUST have the following directories/files #### Labels -| Label | Description -| -------- | -------- -| `io.buildpacks.lifecycle.version` | A string, representing the semver version of the lifecycle. -| `io.buildpacks.lifecycle.apis` | A JSON object representing the APIs the lifecycle supports. +| Label | Description | +| --------------------------------- | ----------------------------------------------------------- | +| `io.buildpacks.lifecycle.version` | A string, representing the semver version of the lifecycle. | +| `io.buildpacks.lifecycle.apis` | A JSON object representing the APIs the lifecycle supports. | -`io.buildpacks.lifecycle.apis` (JSON) +##### `io.buildpacks.lifecycle.apis` (JSON) ```json { @@ -147,18 +168,20 @@ A lifecycle image MUST have the following directories/files } } ``` + Where: * `supported`: - * contains an array of support API versions: - * for versions `1.0+`, version `x.n` implies support for [`x.0`, `x.n`] - * should be a superset of `deprecated` - * should only contain APIs that correspond to a spec release + * contains an array of support API versions: + * for versions `1.0+`, version `x.n` implies support for [`x.0`, `x.n`] + * should be a superset of `deprecated` + * should only contain APIs that correspond to a spec release * `deprecated`: - * contain an array of deprecated APIs: - * should only contain `0.x` or major versions - * should only contain APIs that correspond to a spec release + + * contain an array of deprecated APIs: + * should only contain `0.x` or major versions + * should only contain APIs that correspond to a spec release ### Build Image @@ -168,7 +191,7 @@ The image configuration refers to the OCI Image configuration as mentioned [here #### Image Configuration - The Build Image MUST contain the following configurations: +The Build Image MUST contain the following configurations: * Image Config's `config.User` field MUST be set to the user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID with a writable home directory. * Image Config's `os` field MUST be set to the underlying operating system used by the build image. @@ -186,10 +209,10 @@ The Build Image MUST contain the following Environment Variables: The Build Image SHOULD contain the following Labels on the image configuration: -| Label | Description -|------- |------------ -| `io.buildpacks.distribution.name` | A string denoting the operating system distribution -| `io.buildpacks.distribution.version` | A string denoting the operating system version +| Label | Description | +| ------------------------------------ | --------------------------------------------------- | +| `io.buildpacks.distribution.name` | A string denoting the operating system distribution | +| `io.buildpacks.distribution.version` | A string denoting the operating system version | ### Run Image @@ -221,11 +244,11 @@ The Run Image MUST contain the following Environment Variables: The Run Image SHOULD contain the following Labels on the image configuration: -| Label | Description -| -------- | -------- -| `io.buildpacks.distribution.name` | A string denoting the Operating System distribution -| `io.buildpacks.distribution.version` | A string denoting the Operating System distribution version -| `io.buildpacks.id` | `` +| Label | Description | +| ------------------------------------ | ----------------------------------------------------------- | +| `io.buildpacks.distribution.name` | A string denoting the Operating System distribution | +| `io.buildpacks.distribution.version` | A string denoting the Operating System distribution version | +| `io.buildpacks.id` | `` | Where, @@ -247,7 +270,7 @@ The builder image MUST contain an implementation of the [lifecycle](#lifecycle), A builder MUST have the following directories/files: -* `/cnb/order.toml` → As defined in the [platform specification](https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml) +* `/cnb/order.toml` → As defined in the [platform specification](https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml). #### Environment Variables @@ -255,13 +278,14 @@ A builder MUST be an extension of a Build Image, and MUST retain all the specifi The following environment variables MAY be set on the builder (through the image config's `Env` field): -| Env Variable | Description | Default -| -------- | -------- |----------- -| `CNB_APP_DIR` | Application directory of the build environment | `/workspace` -| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment | `/layers` -| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment | `/platform` -| `SERVICE_BINDING_ROOT` | The directory where services are bound | - +| Env Variable | Description | +| ---------------------- | ---------------------------------------------------------------------------------- | +| `CNB_APP_DIR` | Application directory of the build environment. | +| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment. | +| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment. | +| `SERVICE_BINDING_ROOT` | The directory where services are bound. | +If any environment variable defined above is set on the builder, the specified path MUST be present and writable by the Build Image user. #### Labels @@ -269,50 +293,33 @@ A builder MUST be an extension of a Build Image, and MUST retain all the specifi A builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications. -A builder image MAY contain [buildpacks](#buildpackage), and MAY retain all the specified Labels set on the original buildpackage, as specified in the buildpackage specifications. +A builder image MAY contain buildpacks, and MAY retain all the specified Labels set on the original buildpackage, as specified in the [buildpackage](#buildpackage) specification with the following exceptions: + +- `io.buildpacks.buildpack.metadata` MUST not be set. +- `io.buildpacks.buildpack.layers` on the builder SHOULD be a merged version based on all buildpackages combined and thereby have of all packaged buildpacks represented. -The following labels MUST be set in the builder environment (through the image config's `Labels` field): +In addition to all inherited labels above, the following labels MUST be set in the builder environment (through the image config's `Labels` field): -| Label | Description -| -------- | -------- -| `io.buildpacks.builder.metadata` | A JSON object representing builder metadata -| `io.buildpacks.buildpack.order` | A JSON object representing the order of the buildpacks stored on the builder +| Label | Description | +| -------------------------------- | ------------------------------------------------------------- | +| `io.buildpacks.builder.metadata` | A JSON object representing builder metadata. | +| `io.buildpacks.buildpack.order` | A JSON object representation of the `/cnb/order.toml` file. | -`io.buildpacks.builder.metadata` (JSON) +##### `io.buildpacks.builder.metadata` (JSON) ```json { - "description": "", - "buildpacks": [ - { - "id": "", - "version": "", - "homepage": "", - } - ], + "description": "", "createdBy": { - "name": "", - "version": "", + "name": "", + "version": "", } } ``` -The `createdBy` metadata is meant to contain the name and version of the tool that created the builder. - -`io.buildpacks.buildpack.order` (JSON) - -```json -[ - { - "group": - [ - { - "id": "", - "version": "", - "optional": false - } - ] - } -] +Where: -``` +- `description` (optional) is a human readable description of the builder. +- `createdBy` (optional) is information about the tool that created the builder. + - `name` (optional) is the name of the tool that created the builder. + - `version` (optional) is the version of the tool that created the builder.