Merge pull request #193 from dfreilich/101-builders-extension-spec

Add Builder extension spec
buildpacks · Jul 21, 2021 · 4d29e1e · 4d29e1e
2 parents a9f64de + cabe24f
commit 4d29e1e
Show file tree

Hide file tree

Showing 3 changed files with 183 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -45,6 +45,7 @@ When the specification refers to a path in the context of an OCI layer tar (e.g.
 - [Bindings Extension Specification](extensions/bindings.md)
 - [Buildpack Registry Extension Specification](extensions/buildpack-registry.md)
 - [Project Descriptor Extension Specification](extensions/project-descriptor.md)
+- [Builder Extension Specification](extensions/builder.md)
 
 ## API Versions
 

diff --git a/extensions/builder.md b/extensions/builder.md
@@ -0,0 +1,180 @@
+# Builder Specification <!-- omit in toc -->
+
+This document specified the artifact format for a builder.
+
+A builder is an OCI image that provides a distributable build environment.
+
+A [platform][platform-spec] supporting the builder extension specification SHOULD allow users to configure the build environment with a provided builder.
+
+## Table of Contents <!-- omit in toc -->
+- [General Requirements](#general-requirements)
+  - [Builder API Version](#builder-api-version)
+  - [Filesystem](#filesystem)
+  - [Environment Variables](#environment-variables)
+  - [Labels](#labels)
+- [Data Format](#data-format)
+  - [Labels](#labels-1)
+    - [`io.buildpacks.builder.metadata` (JSON)](#iobuildpacksbuildermetadata-json)
+    - [`io.buildpacks.buildpack.order` (JSON)](#iobuildpacksbuildpackorder-json)
+    - [`io.buildpacks.buildpack.layers` (JSON)](#iobuildpacksbuildpacklayers-json)
+    - [`io.buildpacks.lifecycle.apis` (JSON)](#iobuildpackslifecycleapis-json)
+
+## General Requirements
+A **builder** is an image that MUST contain an implementation of the lifecycle, and build-time environment, and MAY contain buildpacks. Platforms SHOULD use builders to ease the build process.
+
+### Builder API Version
+This document specifies Builder API version `0.1`.
+
+Builder API versions:
+- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
+- When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes
+
+### Filesystem
+A builder MUST have the following directories/files:
+- `/cnb/order.toml` &rarr; As defined in the [platform specification][order-toml-spec]
+- `/cnb/stack.toml` &rarr; As defined in the [platform specification][stack-toml-spec]
+- `/cnb/lifecycle/<lifecycle binaries>` &rarr; An implementation of the lifecycle, which contains the required lifecycle binaries for [building images][lifecycle-for-build].
+
+In addition, every buildpack blob contained on a builder MUST be stored at the following file path:
+- `<CNB_BUILDPACKS_DIR>/<buildpack ID>/<buildpack version>/`
+
+If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name.
+
+The `CNB_APP_DIR` and `CNB_LAYERS_DIR` MUST be writeable by the build environment's User.
+
+### Environment Variables
+A builder MUST be an extension of a build-image, and MUST retain all specified environment variables and labels set on the original build image, as specified in the [platform specifications][build-image-specs].
+
+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 | - |
+| `CNB_BUILDPACKS_DIR` | The directory where buildpacks are located | `/cnb/buildpacks` |
+
+### Labels
+The following labels MUST be set in the builder environment (through the image config's `Labels` field):
+
+| Label                             | Description                                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `io.buildpacks.builder.api`       | The [Builder API Version](#builder-api-version) this builder implements                                                  |
+| `io.buildpacks.builder.metadata`  | A JSON object representing [Builder Metadata](#iobuildpacksbuildermetadata)                                              |
+| `io.buildpacks.buildpack.order`   | A JSON object representing the [order of the buildpacks stored on the builder](#iobuildpacksbuildpackorder)              |
+| `io.buildpacks.buildpack.layers`  | A JSON object representing the [buildpack layers](#iobuildpacksbuildpacklayers)                                          |
+| `io.buildpacks.lifecycle.version` | A string, representing the version of the lifecycle stored in the builder                                                |
+| `io.buildpacks.lifecycle.apis`    | A JSON object representing the [lifecycle APIs](#iobuildpackslifecycleapis) the lifecycle stored in the builder supports |
+
+## Data Format
+### Labels
+#### `io.buildpacks.builder.metadata` (JSON)
+
+```json
+{
+  "description": "<description>",
+  "stack": {
+    "runImage": {
+      "image": "<run image>",
+      "mirrors": [
+        "<run image mirror>"
+      ]
+    }
+  },
+  "buildpacks": [
+    {
+      "id": "<buildpack ID>",
+	  "version": "<buildpack version>",
+	  "homepage": "<buildpack homepage>"
+	}
+  ],
+  "createdBy": {
+    "name": "<tool name>",
+    "version": "<tool 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": "<buildpack ID>",
+			"version": "<buildpack version>",
+			"optional": false
+		  }
+		]
+	}
+]
+```
+
+#### `io.buildpacks.buildpack.layers` (JSON)
+
+```json
+{
+  "<buildpack ID>": {
+    "<buildpack version>": {
+      "api": "<buildpack API>",
+      "order": [
+        {
+          "group": [
+            {
+              "id": "<inner buildpack ID>",
+              "version": "<inner buildpack version>"
+            }
+          ]
+        }
+      ],
+      "layerDiffID": "<diff-ID>",
+	  "homepage": "<buildpack homepage>"
+    }
+  },
+  "<inner buildpack>": {
+    "<inner buildpack version>": {
+      "api": "<buildpack API>",
+      "stacks": [
+        {
+          "id": "<stack ID buildpack supports>",
+          "mixins": ["<list of mixins required>"]
+        }
+      ],
+      "layerDiffID": "<diff-ID>",
+	  "homepage": "<buildpack homepage>"
+    }
+  }
+}
+```
+
+#### `io.buildpacks.lifecycle.apis` (JSON)
+
+```json
+{
+  "buildpack": {
+    "deprecated": ["<list of versions>"],
+    "supported": ["<list of versions>"]
+  },
+  "platform": {
+    "deprecated": ["<list of versions>"],
+    "supported": ["<list of versions>"]
+  }
+}
+```
+
+[//]: <> (Links)
+[build-image-specs]: https://github.com/buildpacks/spec/blob/main/platform.md#build-image
+[platform-spec]: https://github.com/buildpacks/spec/blob/main/platform.md
+[order-toml-spec]: https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml
+[stack-toml-spec]: https://github.com/buildpacks/spec/blob/main/platform.md#stacktoml-toml
+[lifecycle-for-build]: https://github.com/buildpacks/spec/blob/main/platform.md#build
diff --git a/platform.md b/platform.md
@@ -179,6 +179,8 @@ The platform SHOULD ensure that:
 - The image config's `Label` field has the label `io.buildpacks.stack.description` set to the description of the stack.
 - The image config's `Label` field has the label `io.buildpacks.stack.metadata` set to additional metadata related to the stack.   
 
+A [builder](extensions/builder.md) MUST be an extension of a build image.
+
 ### Run Image
 
 The platform MUST ensure that: