Merge pull request #413 from devigned/fix-image-ex-typo

fix typo to image extension link
2025-02-24 11:46:23 -05:00 · 2024-12-09 14:55:38 -05:00 · 2024-07-17 09:48:52 -04:00 · 2024-07-09 12:36:55 -04:00 · 2024-07-09 12:33:20 -04:00 · 2024-07-04 12:30:56 +02:00
4 changed files with 139 additions and 144 deletions
--- a/README.md
+++ b/README.md
@ -52,4 +52,4 @@ These documents currently specify:

 - Buildpack API: `0.10`
 - Distribution API: `0.3`
- Platform API: `0.12`
+- Platform API: `0.14`
--- a/buildpack.md
+++ b/buildpack.md
@ -103,7 +103,7 @@ A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/buil

 A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables. They MUST be [resolvable](#order-resolution) into a collection of component buildpacks.

-An **image extension** (**experimental**) is a directory containing an `extension.toml`. Extensions generate Dockerfiles that can be used to define the runtime base image, prior to buildpack execution. Extensions implement the [Image Extension Interface](image-extension.md). Extensions are always "component": their `extension.toml` cannot contain an order definition.
+An **image extension** is a directory containing an `extension.toml`. Extensions generate Dockerfiles that can be used to define the runtime base image, prior to buildpack execution. Extensions implement the [Image Extension Interface](image_extension.md). Extensions are always "component": their `extension.toml` cannot contain an order definition.

 **Resolving an order** is the process by which an order (which may contain image extensions, component buildpacks, or composite buildpacks) is evaluated together with application source code to produce an optional group of image extensions and a required group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each image extension (if present) and the `/bin/detect` executable for each component buildpack is invoked.

@ -500,7 +500,7 @@ The purpose of the generation phase is to generate Dockerfiles that can be used

 ### Process

-See the [Image Extension Specification](#image-extension.md).
+See the [Image Extension Specification](#image_extension.md).

 ## Phase #4: Extension (image extensions only)

@ -1108,8 +1108,8 @@ Each target in `targets`:
 - MUST identify a compatible runtime environment:
   - `os`, `arch`, and `variant` if provided MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md)
   - `distros` if provided MUST describe the OS distributions supported by the buildpack
-     - For Linux-based images, `distros.name` and `distros.versions` SHOULD contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information
-     - For Windows-based images, `distros.name` SHOULD be empty; `distros.versions` SHOULD contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`)
+     - For Linux-based images, `distros.name` and `distros.version` SHOULD contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information
+     - For Windows-based images, `distros.name` SHOULD be empty; `distros.version` SHOULD contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`)
   - Any field not provided will be interpreted as `<matches any>`

 If the `targets` list is empty, tools reading `buildpack.toml` will assume:
@ -1242,47 +1242,3 @@ If the `bom` array is used, the buildpack:
 When the build is complete, a legacy build BOM describing the build container MAY be generated for auditing purposes.

 If generated, this legacy build BOM MUST contain all `bom` entries in each `build.toml` at the end of each `/bin/build` execution, in adherence with the process and data format outlined in the [Platform Interface Specification](platform.md) for legacy BOM formats.
-
-### Build Plan (TOML) `requires.version` Key
-
-_Deprecated in Buildpack API 0.3._
-
-The `requires.version` and `or.requires.version` keys are deprecated.
-
-```toml
-[[requires]]
-name = "<dependency name>"
-version = "<dependency version>"
-
-[[or.requires]]
-name = "<dependency name>"
-version = "dependency version>"
-```
-
-To upgrade, buildpack authors SHOULD set `requires.version` as `requires.metadata.version` and `or.requires.version` as `or.requires.metadata.version`.
-
-```toml
-[[requires]]
-name = "<dependency name>"
-
-[requires.metadata]
-version = "<dependency version>"
-
-[[or.requires]]
-name = "<dependency name>"
-
-[or.requires.metadata]
-version = "<dependency version>"
-```
-
-If `requires.version` and `requires.metadata.version` or `or.requires.version` and `or.requires.metadata.version` are both defined then lifecycle will fail.
-
-For backwards compatibility, the lifecycle will produce a Buildpack Plan (TOML) that puts `version` in `entries.metadata` as long as `version` does not exist in `requires.metadata`.
-
-```toml
-[[entries]]
-name = "<dependency name>"
-
-[entries.metadata]
-version = "<dependency version>"
-```
--- a/image_extension.md
+++ b/image_extension.md
@ -1,4 +1,4 @@
-# Image Extension Interface Specification (**experimental**)
+# Image Extension Interface Specification

 This document specifies the interface between a lifecycle program and one or more image extensions.

@ -89,9 +89,27 @@ Correspondingly, each `/bin/generate` executable:
 - MAY log output from the build process to `stdout`.
 - MAY emit error, warning, or debug messages to `stderr`.
 - MAY write either or both of `build.Dockerfile` and `run.Dockerfile` to the `<output>` directory. This file MUST adhere to the requirements listed below.
+- MAY create the following folders in the `<output>` directory with an arbitrary content:
+  
+  either:
+
+  - `context`
+
+  or the image-specific folders:
+
+  - `context.run`
+  - `context.build`
 - MAY write key-value pairs to `<output>/extend-config.toml` that are provided as build args to build.Dockerfile when extending the build image.
 - MUST NOT write SBOM (Software-Bill-of-Materials) files as described in the [Software-Bill-of-Materials](#software-bill-of-materials) section.

+#### Context Folders
+
+- The `<output>/context` folder MUST NOT be created together with any combination of the image-specific folders.
+- If the folder `<output>/context` is present it will be set as the build context during the `extend` phase of the build and run images.
+- If the folder `<output>/context.run` is present it will be set as the build context during the `extend` phase of the run image only.
+- If the folder `<output>/context.build` is present it will be set as the build context during the `extend` phase of the build image only.
+- If none of these folders is not present, the build context defaults to the `<app>` folder.
+
 #### Dockerfile Requirements

 A `run.Dockerfile`
--- a/platform.md
+++ b/platform.md
@ -40,7 +40,7 @@ Examples of a platform might include:
        - [Inputs](#inputs-2)
        - [Outputs](#outputs-2)
        - [Layer Restoration](#layer-restoration)
-      - [`extender` (optional and **experimental**)](#extender-optional-and-experimental)
+      - [`extender` (optional)](#extender-optional)
        - [Inputs](#inputs-3)
        - [Outputs](#outputs-3)
      - [`builder`](#builder)
@ -77,6 +77,7 @@ Examples of a platform might include:
      - [Launch Environment](#launch-environment)
    - [Caching](#caching)
    - [Build Reproducibility](#build-reproducibility)
+    - [Map an image reference to a path in the layout directory](#map-an-image-reference-to-a-path-in-the-layout-directory)
  - [Data Format](#data-format)
    - [Files](#files)
      - [`analyzed.toml` (TOML)](#analyzedtoml-toml)
@ -97,7 +98,7 @@ Examples of a platform might include:

 ## Platform API Version

-This document specifies Platform API version `0.12`.
+This document specifies Platform API version `0.14`.

 Platform API versions:
 - MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
@ -245,7 +246,7 @@ A single app image build* consists of the following phases:
 1. Analysis
 2. Detection
 3. Cache Restoration
-4. (Optional and Experimental) Base Image Extension
+4. (Optional) Base Image Extension
 5. Build*
 6. Export

@ -253,7 +254,7 @@ A platform MUST execute these phases either by invoking the following phase-spec
 1. `/cnb/lifecycle/analyzer`
 2. `/cnb/lifecycle/detector`
 3. `/cnb/lifecycle/restorer`
-4. `/cnb/lifecycle/extender` (Optional and [Experimental](#experimental-features)) 
+4. `/cnb/lifecycle/extender` (Optional) 
 5. `/cnb/lifecycle/builder`
 6. `/cnb/lifecycle/exporter`

@ -300,6 +301,7 @@ Usage:
  [-cache-image <cache-image>] \
  [-daemon] \ # sets <daemon>
  [-gid <gid>] \
+  [-insecure-registry <insecure-registry>...] \
  [-launch-cache <launch-cache>] \
  [-layers <layers>] \
  [-layout] \ # sets <layout>
@ -316,24 +318,25 @@ Usage:

 ##### Inputs

-| Input              | Environment Variable   | Default Value            | Description                                                                                                           |
-|--------------------|------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| `<analyzed>`       | `CNB_ANALYZED_PATH`    | `<layers>/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml)                                           |
-| `<cache-image>`    | `CNB_CACHE_IMAGE`      |                          | Reference to a cache image in an OCI registry                                                                         |
-| `<daemon>`         | `CNB_USE_DAEMON`       | `false`                  | Analyze image from docker daemon                                                                                      |
-| `<gid>`            | `CNB_GROUP_ID`         |                          | Primary GID of the build image `User`                                                                                 |
-| `<layers>`         | `CNB_LAYERS_DIR`       | `/layers`                | Path to layers directory                                                                                              |
-| `<layout>`         | `CNB_USE_LAYOUT`       | false                    | (**[experimental](#experimental-features)**) Analyze image from disk in OCI layout format                             |
-| `<layout-dir>`     | `CNB_LAYOUT_DIR`       |                          | (**[experimental](#experimental-features)**) Path to a root directory where the images are saved in OCI layout format |
-| `<image>`          |                        |                          | Tag reference to which the app image will be written                                                                  |
-| `<launch-cache>`   | `CNB_LAUNCH_CACHE_DIR` |                          | Path to a cache directory containing launch layers                                                                    |
-| `<log-level>`      | `CNB_LOG_LEVEL`        | `info`                   | Log Level                                                                                                             |
-| `<previous-image>` | `CNB_PREVIOUS_IMAGE`   | `<image>`                | Image reference to be analyzed (usually the result of the previous build)                                             |
-| `<run>`            | `CNB_RUN_PATH`         | `/cnb/run.toml`          | Path to run file (see [`run.toml`](#runtoml-toml))                                                                    |
-| `<run-image>`      | `CNB_RUN_IMAGE`        | resolved from `<run>`    | Run image reference                                                                                                   |
-| `<skip-layers>`    | `CNB_SKIP_LAYERS`      | `false`                  | Do not restore SBOM layer from previous image                                                                         |
-| `<tag>...`         |                        |                          | Additional tag to apply to exported image                                                                             |
-| `<uid>`            | `CNB_USER_ID`          |                          | UID of the build image `User`                                                                                         |
+| Input                    | Environment Variable      | Default Value            | Description                                                                                                           |
+|--------------------------|---------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `<analyzed>`             | `CNB_ANALYZED_PATH`       | `<layers>/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml)                                           |
+| `<cache-image>`          | `CNB_CACHE_IMAGE`         |                          | Reference to a cache image in an OCI registry                                                                         |
+| `<daemon>`               | `CNB_USE_DAEMON`          | `false`                  | Analyze image from docker daemon                                                                                      |
+| `<gid>`                  | `CNB_GROUP_ID`            |                          | Primary GID of the build image `User`                                                                                 |
+| `<insecure-registry>...` | `CNB_INSECURE_REGISTRIES` |                          | When fetching images from this registry, do not use TLS encryption or certificate verification                        |
+| `<layers>`               | `CNB_LAYERS_DIR`          | `/layers`                | Path to layers directory                                                                                              |
+| `<layout>`               | `CNB_USE_LAYOUT`          | false                    | (**[experimental](#experimental-features)**) Analyze image from disk in OCI layout format                             |
+| `<layout-dir>`           | `CNB_LAYOUT_DIR`          |                          | (**[experimental](#experimental-features)**) Path to a root directory where the images are saved in OCI layout format |
+| `<image>`                |                           |                          | Tag reference to which the app image will be written                                                                  |
+| `<launch-cache>`         | `CNB_LAUNCH_CACHE_DIR`    |                          | Path to a cache directory containing launch layers                                                                    |
+| `<log-level>`            | `CNB_LOG_LEVEL`           | `info`                   | Log Level                                                                                                             |
+| `<previous-image>`       | `CNB_PREVIOUS_IMAGE`      | `<image>`                | Image reference to be analyzed (usually the result of the previous build)                                             |
+| `<run>`                  | `CNB_RUN_PATH`            | `/cnb/run.toml`          | Path to run file (see [`run.toml`](#runtoml-toml))                                                                    |
+| `<run-image>`            | `CNB_RUN_IMAGE`           | resolved from `<run>`    | Run image reference                                                                                                   |
+| `<skip-layers>`          | `CNB_SKIP_LAYERS`         | `false`                  | Do not restore SBOM layer from previous image                                                                         |
+| `<tag>...`               |                           |                          | Additional tag to apply to exported image                                                                             |
+| `<uid>`                  | `CNB_USER_ID`             |                          | UID of the build image `User`                                                                                         |

 -`<image>` MUST be a valid image reference
 - **If** the platform provides one or more `<tag>` inputs, each `<tag>` MUST be a valid image reference.
@ -397,8 +400,8 @@ Usage:
 | `<app>`          | `CNB_APP_DIR`          | `/workspace`                                           | Path to application directory                                                                                                                                |
 | `<build-config>` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config`                                    | Path to build config directory                                                                                                                               |
 | `<buildpacks>`   | `CNB_BUILDPACKS_DIR`   | `/cnb/buildpacks`                                      | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout))                                                               |
-| `<extensions>`^  | `CNB_EXTENSIONS_DIR`   | `/cnb/extensions`                                      | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) |
-| `<generated>`^   | `CNB_GENERATED_DIR`    | `<layers>/generated`                                   | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles                                                              |
+| `<extensions>`^  | `CNB_EXTENSIONS_DIR`   | `/cnb/extensions`                                      | Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) |
+| `<generated>`^   | `CNB_GENERATED_DIR`    | `<layers>/generated`                                   | Path to output directory for generated Dockerfiles                                                              |
 | `<group>`        | `CNB_GROUP_PATH`       | `<layers>/group.toml`                                  | Path to output group definition                                                                                                                              |
 | `<layers>`       | `CNB_LAYERS_DIR`       | `/layers`                                              | Path to layers directory                                                                                                                                     |
 | `<log-level>`    | `CNB_LOG_LEVEL`        | `info`                                                 | Log Level                                                                                                                                                    |
@ -440,12 +443,9 @@ The lifecycle:
 - SHALL write the resolved build plan from the detected group to `<plan>`
 - SHALL provide `run-image.target` data in `<analyzed>` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md).

-When image extensions are present in the order (optional and **[experimental](#experimental-features)**), the lifecycle:
+When image extensions are present in the order (optional), the lifecycle:
 - SHALL execute all image extensions in the order defined in `<group>` according to the process outlined in the [Buildpack Interface Specification](buildpack.md).
 - SHALL filter the build plan with dependencies provided by image extensions.
- SHALL copy any generated run.Dockerfiles to `<generated>/run/<image extension ID>/Dockerfile`.
- SHALL copy any generated build.Dockerfiles to `<generated>/build/<image extension ID>/Dockerfile`.
- SHALL copy any generated `<extend-config>` files to `<generated>/build/<image extension ID>/<extend-config>`.
 - SHALL replace `run-image` in `<analyzed>` with the selected run image. To select the run image, the lifecycle SHALL inspect each `run.Dockerfile` output by image extensions, in the order defined in `<group>`:
  - **If** all `run.Dockerfile`s declare `FROM ${base_image}`, the selected run image SHALL be the original run image in `<analyzed>`, with `extend = true`
  - **Else** the selected run image SHALL be the last image referenced in the `FROM` statement of the last `run.Dockerfile` not to declare `FROM ${base_image}`
@ -457,6 +457,11 @@ When image extensions are present in the order (optional and **[experimental](#e
    - **Else**
      - `run-image.extend` SHALL be `true`
 - SHALL warn if the selected run image is not found in `<run>`
+- SHALL record `build-image` in `<analyzed>`
+  - **If** there are no `build.Dockerfile`s:
+    - `build-image.extend` SHALL be `false`
+  - **Else**
+    - `build-image.extend` SHALL be `true`

 #### `restorer`

@ -470,33 +475,38 @@ Usage:
  [-daemon] \ # sets <daemon>
  [-gid <gid>] \
  [-group <group>] \
+  [-insecure-registry <insecure-registry>...] \
  [-layers <layers>] \
  [-log-level <log-level>] \
  [-skip-layers <skip-layers>] \
-  [-uid <uid>]
+  [-uid <uid>] \
+  [-run <run> ]
 ```

 ##### Inputs

-| Input            | Environment Variable | Default Value            | Description                                                                                       |
-|------------------|----------------------|--------------------------|---------------------------------------------------------------------------------------------------|
-| `<analyzed>`     | `CNB_ANALYZED_PATH`  | `<layers>/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml)                       |
-| `<build-image>`* | `CNB_BUILD_IMAGE`    |                          | Reference to the current build image in an OCI registry (if used `<kaniko-dir>` must be provided) |
-| `<cache-dir>`    | `CNB_CACHE_DIR`      |                          | Path to a cache directory                                                                         |
-| `<cache-image>`  | `CNB_CACHE_IMAGE`    |                          | Reference to a cache image in an OCI registry                                                     |
-| `<daemon>`^      | `CNB_USE_DAEMON`     | `false`                  | Read additional target data for run image from docker daemon                                      |
-| `<gid>`          | `CNB_GROUP_ID`       |                          | Primary GID of the build image `User`                                                             |
-| `<group>`        | `CNB_GROUP_PATH`     | `<layers>/group.toml`    | Path to group definition (see [`group.toml`](#grouptoml-toml))                                    |
-| `<kaniko-dir>`^  |                      |                          | Kaniko directory (must be `/kaniko`)                                                              |
-| `<layers>`       | `CNB_LAYERS_DIR`     | `/layers`                | Path to layers directory                                                                          |
-| `<log-level>`    | `CNB_LOG_LEVEL`      | `info`                   | Log Level                                                                                         |
-| `<skip-layers>`  | `CNB_SKIP_LAYERS`    | `false`                  | Do not perform [layer restoration](#layer-restoration)                                            |
-| `<uid>`          | `CNB_USER_ID`        |                          | UID of the build image `User`                                                                     |
-
+| Input                    | Environment Variable      | Default Value            | Description                                                                                       |
+|--------------------------|---------------------------|--------------------------|---------------------------------------------------------------------------------------------------|
+| `<analyzed>`             | `CNB_ANALYZED_PATH`       | `<layers>/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml)                       |
+| `<build-image>`*         | `CNB_BUILD_IMAGE`         |                          | Reference to the current build image in an OCI registry (if used `<kaniko-dir>` must be provided) |
+| `<cache-dir>`            | `CNB_CACHE_DIR`           |                          | Path to a cache directory                                                                         |
+| `<cache-image>`          | `CNB_CACHE_IMAGE`         |                          | Reference to a cache image in an OCI registry                                                     |
+| `<daemon>`^              | `CNB_USE_DAEMON`          | `false`                  | Read additional target data for run image from docker daemon                                      |
+| `<gid>`                  | `CNB_GROUP_ID`            |                          | Primary GID of the build image `User`                                                             |
+| `<group>`                | `CNB_GROUP_PATH`          | `<layers>/group.toml`    | Path to group definition (see [`group.toml`](#grouptoml-toml))                                    |
+| `<insecure-registry>...` | `CNB_INSECURE_REGISTRIES` |                          | When fetching images from this registry, do not use TLS encryption or certificate verification    |
+| `<kaniko-dir>`^          |                           |                          | Kaniko directory (must be `/kaniko`)                                                              |
+| `<layers>`               | `CNB_LAYERS_DIR`          | `/layers`                | Path to layers directory                                                                          |
+| `<log-level>`            | `CNB_LOG_LEVEL`           | `info`                   | Log Level                                                                                         |
+| `<skip-layers>`          | `CNB_SKIP_LAYERS`         | `false`                  | Do not perform [layer restoration](#layer-restoration)                                            |
+| `<uid>`                  | `CNB_USER_ID`             |                          | UID of the build image `User`                                                                     |
+| `<run>`**                | `CNB_RUN_PATH`            | `/cnb/run.toml`          | Path to run file (see [`run.toml`](#runtoml-toml))                                                |
 > ^ Only needed when using image extensions

 > \* Only needed when using image extensions to extend the build image

+> \** Only needed when using image extensions to extend the run image
+
 ##### Outputs

 | Output                                      | Description                                                                                                                               |
@ -522,11 +532,11 @@ Usage:
 - For each buildpack in `<group>`, if persistent metadata for that buildpack exists in the analysis metadata, lifecycle MUST write a toml representation of the persistent metadata to `<layers>/<buildpack-id>/store.toml`
 - **If** `<skip-layers>` is `true` the lifecycle MUST NOT perform layer restoration.
 - **Else** the lifecycle MUST perform [layer restoration](#layer-restoration) for any app image layers or cached layers created by any buildpack present in the provided `<group>`.
- When `<build-image>` is provided (optional and **[experimental](#experimental-features)**), the lifecycle:
+- When `<build-image>` is provided (optional), the lifecycle:
  - MUST record the digest reference to the provided `<build-image>` in `<analyzed>`
  - MUST copy the OCI manifest and config file for `<build-image>` to `<kaniko-dir>/cache`
 - The lifecycle:
-  - MUST resolve `run-image.reference` to a digest reference in `<analyzed>` if not present
+  - MUST [resolve mirrors](#run-image-resolution) for the `run-image.reference` in `<analyzed>` and resolve it to a digest reference
  - MUST populate `run-image.target` data in `<analyzed>` if not present
  - **If** `<analyzed>` has `run-image.extend = true`, the lifecycle:
    - MUST download from the registry and save in OCI layout format the `run-image` in `<analyzed>` to `<kaniko-dir>/cache`
@ -535,7 +545,7 @@ Usage:

 lifeycle MUST use the provided `cache-dir` or `cache-image` to retrieve cache contents. The [rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#layer-types) for restoration MUST be followed when determining how and when to store cache layers.

-#### `extender` (optional and **[experimental](#experimental-features)**)
+#### `extender` (optional)

 If using `extender`, the platform MUST execute `extender` in either or both of: the **build environment**, the **run environment**

@ -567,7 +577,7 @@ Usage:
 | `<build-config>`     | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config`      | Path to build config directory                                                                  |
 | `<buildpacks>`*      | `CNB_BUILDPACKS_DIR`   | `/cnb/buildpacks`        | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout))  |
 | `<extended>`**       | `CNB_EXTENDED_DIR`     | `<layers>/extended`      | Path to output directory for extended run image layers                                          |
-| `<generated>`        | `CNB_GENERATED_DIR`    | `<layers>/generated`     | (**[experimental](#experimental-features)**) Path to directory containing generated Dockerfiles |
+| `<generated>`        | `CNB_GENERATED_DIR`    | `<layers>/generated`     | Path to directory containing generated Dockerfiles |
 | `<gid>`*             | `CNB_GROUP_ID`         |                          | Primary GID of the build image `User`                                                           |
 | `<group>`            | `CNB_GROUP_PATH`       | `<layers>/group.toml`    | Path to group definition (see [`group.toml`](#grouptoml-toml))                                  |
 | `<kaniko-cache-ttl>` | `CNB_KANIKO_CACHE_TTL` | 2 weeks                  | Kaniko cache TTL                                                                                |
@ -605,14 +615,15 @@ When extending the build image:
 | `1-10`, `13-19` | Generic lifecycle errors            |
 | `100-109`       | Extension-specific lifecycle errors |

- For each extension in `<group>` in order, if a Dockerfile exists in `<generated>/<kind>/<buildpack-id>`, the lifecycle:
+- For each extension in `<group>` in order, if a Dockerfile exists in `<generated>/<buildpack-id>/<kind>.Dockerfile`, the lifecycle:
  - SHALL apply the Dockerfile to the environment according to the process outlined in the [Image Extension Specification](image-extension.md).
+  - SHALL set the build context to the folder according to the process outlined in the [Image Extension Specification](image-extension.md).
 - The extended image MUST be an extension of:
  - The `build-image` in `<analyzed>` when `<kind>` is `build`, or
  - The `run-image` in `<analyzed>` when `<kind>` is `run`
- When extending the build image, after all `build.Dockefile`s are applied, the lifecycle:
+- When extending the build image, after all `build.Dockerfile`s are applied, the lifecycle:
  - SHALL proceed with the `build` phase using the provided `<gid>` and `<uid>`
- When extending the run image, after all `run.Dockefile`s are applied, the lifecycle:
+- When extending the run image, after all `run.Dockerfile`s are applied, the lifecycle:
  - **If** any `run.Dockerfile` set the label `io.buildpacks.rebasable` to `false` or left the label unset:
    - SHALL set the label `io.buildpacks.rebasable` to `false` on the extended run image
  - **If** after the final `run.Dockerfile` the run image user is `root`,
@ -691,6 +702,7 @@ Usage:
  [-extended <extended>] \
  [-gid <gid>] \
  [-group <group>] \
+  [-insecure-registry <insecure-registry>...] \
  [-launch-cache <launch-cache> ] \
  [-launcher <launcher> ] \
  [-launcher-sbom <launcher-sbom> ] \
@ -698,6 +710,7 @@ Usage:
  [-layout] \ # sets <layout>
  [-layout-dir] \ # sets <layout-dir>
  [-log-level <log-level>] \
+  [-parallel] \
  [-process-type <process-type> ] \
  [-project-metadata <project-metadata> ] \
  [-report <report> ] \
@ -708,31 +721,33 @@ Usage:

 ##### Inputs

-| Input                           | Environment Variable        | Default Value                    | Description                                                                                |
-|---------------------------------|-----------------------------|----------------------------------|--------------------------------------------------------------------------------------------|
-| `<analyzed>`                    | `CNB_ANALYZED_PATH`         | `<layers>/analyzed.toml`         | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml)                       |
-| `<app>`                         | `CNB_APP_DIR`               | `/workspace`                     | Path to application directory                                                              |
-| `<cache-dir>`                   | `CNB_CACHE_DIR`             |                                  | Path to a cache directory                                                                  |
-| `<cache-image>`                 | `CNB_CACHE_IMAGE`           |                                  | Reference to a cache image in an OCI registry                                              |
-| `<daemon>`                      | `CNB_USE_DAEMON`            | `false`                          | Export image to docker daemon                                                              |
-| `<extended>`**                  | `CNB_EXTENDED_DIR`          | `<layers>/extended`              | Path to directory containing extended run image layers                                     |
-| `<gid>`                         | `CNB_GROUP_ID`              |                                  | Primary GID of the build image `User`                                                      |
-| `<group>`                       | `CNB_GROUP_PATH`            | `<layers>/group.toml`            | Path to group file (see [`group.toml`](#grouptoml-toml))                                   |
-| `<image>`                       |                             |                                  | Tag reference to which the app image will be written                                       |
-| `<launch-cache>`                | `CNB_LAUNCH_CACHE_DIR`      |                                  | Path to a cache directory containing launch layers                                         |
-| `<launcher-sbom>`               |                             | `/cnb/lifecycle`                 | Path to directory containing SBOM files describing the `launcher` executable               |
-| `<launcher>`                    |                             | `/cnb/lifecycle/launcher`        | Path to the `launcher` executable                                                          |
-| `<layers>/config/metadata.toml` |                             |                                  | Build metadata (see [`metadata.toml`](#metadatatoml-toml)                                  |
-| `<layers>`                      | `CNB_LAYERS_DIR`            | `/layers`                        | Path to layer directory                                                                    |
-| `<layout>`                      | `CNB_USE_LAYOUT`            | false                            | (**[experimental](#experimental-features)**) Export image to disk in OCI layout format     |
+| Input                           | Environment Variable        | Default Value                    | Description                                                                                                           |
+|---------------------------------|-----------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `<analyzed>`                    | `CNB_ANALYZED_PATH`         | `<layers>/analyzed.toml`         | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml)                                                  |
+| `<app>`                         | `CNB_APP_DIR`               | `/workspace`                     | Path to application directory                                                                                         |
+| `<cache-dir>`                   | `CNB_CACHE_DIR`             |                                  | Path to a cache directory                                                                                             |
+| `<cache-image>`                 | `CNB_CACHE_IMAGE`           |                                  | Reference to a cache image in an OCI registry                                                                         |
+| `<daemon>`                      | `CNB_USE_DAEMON`            | `false`                          | Export image to docker daemon                                                                                         |
+| `<extended>`**                  | `CNB_EXTENDED_DIR`          | `<layers>/extended`              | Path to directory containing extended run image layers                                                                |
+| `<gid>`                         | `CNB_GROUP_ID`              |                                  | Primary GID of the build image `User`                                                                                 |
+| `<group>`                       | `CNB_GROUP_PATH`            | `<layers>/group.toml`            | Path to group file (see [`group.toml`](#grouptoml-toml))                                                              |
+| `<image>`                       |                             |                                  | Tag reference to which the app image will be written                                                                  |
+| `<insecure-registry>...`        | `CNB_INSECURE_REGISTRIES`   |                                  | When fetching images from this registry, do not use TLS encryption or certificate verification                        |
+| `<launch-cache>`                | `CNB_LAUNCH_CACHE_DIR`      |                                  | Path to a cache directory containing launch layers                                                                    |
+| `<launcher-sbom>`               |                             | `/cnb/lifecycle`                 | Path to directory containing SBOM files describing the `launcher` executable                                          |
+| `<launcher>`                    |                             | `/cnb/lifecycle/launcher`        | Path to the `launcher` executable                                                                                     |
+| `<layers>/config/metadata.toml` |                             |                                  | Build metadata (see [`metadata.toml`](#metadatatoml-toml)                                                             |
+| `<layers>`                      | `CNB_LAYERS_DIR`            | `/layers`                        | Path to layer directory                                                                                               |
+| `<layout>`                      | `CNB_USE_LAYOUT`            | false                            | (**[experimental](#experimental-features)**) Export image to disk in OCI layout format                                |
 | `<layout-dir>`                  | `CNB_LAYOUT_DIR`            |                                  | (**[experimental](#experimental-features)**) Path to a root directory where the images are saved in OCI layout format |
-| `<log-level>`                   | `CNB_LOG_LEVEL`             | `info`                           | Log Level                                                                                  |
-| `<process-type>`                | `CNB_PROCESS_TYPE`          |                                  | Default process type to set in the exported image                                          |
-| `<project-metadata>`            | `CNB_PROJECT_METADATA_PATH` | `<layers>/project-metadata.toml` | Path to a project metadata file (see [`project-metadata.toml`](#project-metadatatoml-toml) |
-| `<report>`                      | `CNB_REPORT_PATH`           | `<layers>/report.toml`           | Path to report (see [`report.toml`](#reporttoml-toml)                                      |
-| `<run>`                         | `CNB_RUN_PATH`              | `/cnb/run.toml`                  | Path to run file (see [`run.toml`](#runtoml-toml)                                          |
-| `<uid>`                         | `CNB_USER_ID`               |                                  | UID of the build image `User`                                                              |
-|                                 | `SOURCE_DATE_EPOCH`         |                                  | Timestamp for `created` time in app image config                                           |
+| `<log-level>`                   | `CNB_LOG_LEVEL`             | `info`                           | Log Level                                                                                                             |
+| `<parallel>`                    | `CNB_PARALLEL_EXPORT`       | false                            | Export app image and cache in parallel                                                                                |
+| `<process-type>`                | `CNB_PROCESS_TYPE`          |                                  | Default process type to set in the exported image                                                                     |
+| `<project-metadata>`            | `CNB_PROJECT_METADATA_PATH` | `<layers>/project-metadata.toml` | Path to a project metadata file (see [`project-metadata.toml`](#project-metadatatoml-toml)                            |
+| `<report>`                      | `CNB_REPORT_PATH`           | `<layers>/report.toml`           | Path to report (see [`report.toml`](#reporttoml-toml)                                                                 |
+| `<run>`                         | `CNB_RUN_PATH`              | `/cnb/run.toml`                  | Path to run file (see [`run.toml`](#runtoml-toml)                                                                     |
+| `<uid>`                         | `CNB_USER_ID`               |                                  | UID of the build image `User`                                                                                         |
+|                                 | `SOURCE_DATE_EPOCH`         |                                  | Timestamp for `created` time in app image config                                                                      |

 > ** Only needed when extending the run image

@ -830,6 +845,7 @@ Usage:
  [-cache-image <cache-image>] \
  [-daemon] \ # sets <daemon>
  [-gid <gid>] \
+  [-insecure-registry <insecure-registry>...] \
  [-launch-cache <launch-cache> ] \
  [-launcher <launcher> ] \
  [-layers <layers>] \
@ -854,11 +870,11 @@ Usage:

 Running `creator` SHALL be equivalent to running `detector`, `analyzer`, `restorer`, `builder` and `exporter` in order with identical inputs where they are accepted, with the following exceptions.

-| Input             | Environment Variable| Default Value| Description
-|-------------------|---------------------|--------------|----------------------
-| `<previous-image>`| `CNB_PREVIOUS_IMAGE`| `<image>`    | Image reference to be analyzed (usually the result of the previous build)
-| `<skip-restore>`  | `CNB_SKIP_RESTORE`  | `false`      | Prevent buildpacks from reusing layers from previous builds, by skipping the restoration of any data to each buildpack's layers directory, with the exception of `store.toml`.
-| `<tag>...`        |                     |              | Additional tag to apply to exported image
+| Input              | Environment Variable | Default Value | Description                                                                                                                                                                    |
+|--------------------|----------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<previous-image>` | `CNB_PREVIOUS_IMAGE` | `<image>`     | Image reference to be analyzed (usually the result of the previous build)                                                                                                      |
+| `<skip-restore>`   | `CNB_SKIP_RESTORE`   | `false`       | Prevent buildpacks from reusing layers from previous builds, by skipping the restoration of any data to each buildpack's layers directory, with the exception of `store.toml`. |
+| `<tag>...`         |                      |               | Additional tag to apply to exported image                                                                                                                                      |

 - **If** `<skip-restore>` is `true` the `creator` SHALL skip the restoration of any data to each buildpack's layers directory, with the exception of `store.toml`.
 - **If** the platform provides one or more `<tag>` inputs they SHALL be treated as additional `<image>` inputs to the `exporter`
@ -887,6 +903,7 @@ Usage:
  [-daemon] \ # sets <daemon>
  [-force] \
  [-gid <gid>] \
+  [-insecure-registry <insecure-registry>...] \
  [-log-level <log-level>] \
  [-previous-image <previous-image>] \
  [-report <report> ] \
@ -897,17 +914,18 @@ Usage:

 ##### Inputs

-| Input              | Environment Variable | Default Value          | Description                                           |
-|--------------------|----------------------|------------------------|-------------------------------------------------------|
-| `<daemon>`         | `CNB_USE_DAEMON`     | `false`                | Export image to docker daemon                         |
-| `<force>`          | `CNB_FORCE_REBASE`   | `false`                | Allow unsafe rebase                                   |
-| `<gid>`            | `CNB_GROUP_ID`       |                        | Primary GID of the build image `User`                 |
-| `<image>`          |                      |                        | App image to rebase                                   |
-| `<log-level>`      | `CNB_LOG_LEVEL`      | `info`                 | Log Level                                             |
-| `<previous-image>` |                      | derived from `<image>` | Previous image reference                              |
-| `<report>`         | `CNB_REPORT_PATH`    | `<layers>/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) |
-| `<run-image>`      | `CNB_RUN_IMAGE`      | derived from `<image>` | Run image reference                                   |
-| `<uid>`            | `CNB_USER_ID`        |                        | UID of the build image `User`                         |
+| Input                    | Environment Variable      | Default Value          | Description                                                                                    |
+|--------------------------|---------------------------|------------------------|------------------------------------------------------------------------------------------------|
+| `<daemon>`               | `CNB_USE_DAEMON`          | `false`                | Export image to docker daemon                                                                  |
+| `<force>`                | `CNB_FORCE_REBASE`        | `false`                | Allow unsafe rebase                                                                            |
+| `<gid>`                  | `CNB_GROUP_ID`            |                        | Primary GID of the build image `User`                                                          |
+| `<image>`                |                           |                        | App image to rebase                                                                            |
+| `<insecure-registry>...` | `CNB_INSECURE_REGISTRIES` |                        | When fetching images from this registry, do not use TLS encryption or certificate verification |
+| `<log-level>`            | `CNB_LOG_LEVEL`           | `info`                 | Log Level                                                                                      |
+| `<previous-image>`       |                           | derived from `<image>` | Previous image reference                                                                       |
+| `<report>`               | `CNB_REPORT_PATH`         | `<layers>/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml)                                          |
+| `<run-image>`            | `CNB_RUN_IMAGE`           | derived from `<image>` | Run image reference                                                                            |
+| `<uid>`                  | `CNB_USER_ID`             |                        | UID of the build image `User`                                                                  |

 - At least one `<image>` must be provided
 - **If** `<image>` has the label `io.buildpacks.rebasable` set to `false`, the lifecycle SHALL fail unless `<force>` is `true`
@ -952,7 +970,7 @@ Usage:
 - **If** `<force>` is `true` and the provided `<run-image>` is not found in `runImage.image` or `runImage.mirrors`:
  - `run-image.image` SHALL be the provided `<run-image>`
  - `run-image.mirrors` SHALL be omitted
- **Else if** `<force> is `false`, the provided `<run-image>` MUST be found in `runImage.image` or `runImage.mirrors`
+- **Else if** `<force>` is `false`, the provided `<run-image>` MUST be found in `runImage.image` or `runImage.mirrors`
 - To ensure [build reproducibility](#build-reproducibility), the lifecycle:
    - SHOULD set the `created` time in image config to a constant
 - The lifecycle SHALL write a [report](#reporttoml-toml) to `<report>` describing the rebased app image
@ -1359,7 +1377,7 @@ Where:
 - `entries` MAY be empty
 - Each entry:
    - MUST contain at least one buildpack or image extension in `providers`
-      - If the provider is an image extension (optional and **[experimental](#experimental-features)**), `extension` MUST be `true`; the value of `extension` MUST default to `false` if not specified
+      - If the provider is an image extension (optional), `extension` MUST be `true`; the value of `extension` MUST default to `false` if not specified
    - MUST contain at least one dependency requirement in `requires`
    - MUST exclusively contain dependency requirements with the same `<dependency name>`

@ -1555,10 +1573,13 @@ _Deprecated in Platform API 0.12._

 For compatibility with older platforms and older buildpacks, base image authors SHOULD ensure for build images and run images:

- The image config's `Env` field has the environment variable `CNB_STACK_ID` set to the stack ID.
 - The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID.
 - The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image.

+And for build images:
+
+- The image config's `Env` field has the environment variable `CNB_STACK_ID` set to the stack ID.
+
 Where `CNB_STACK_ID` SHALL be directly inherited by buildpacks without modification.

 To upgrade, the platform SHOULD upgrade all buildpacks to use Buildpack API `0.10` or greater.
Author	SHA1	Message	Date
Natalie Arellano	d29ba81518	Merge pull request #413 from devigned/fix-image-ex-typo fix typo to image extension link	2025-02-24 11:46:23 -05:00
David Justice	bdcac26a7d	fix typo to image extension link Signed-off-by: David Justice <david@devigned.com>	2024-12-09 14:55:38 -05:00
Natalie Arellano	f3fd7555c8	Merge pull request #410 from buildpacks/platform/0.14 Finalize Platform 0.14	2024-07-17 09:48:52 -04:00
Natalie Arellano	f8b60dc65c	Update version Signed-off-by: Natalie Arellano <narellano@vmware.com>	2024-07-09 12:36:55 -04:00
Natalie Arellano	08ee76ee4b	Merge pull request #408 from sap-contributions/add-run-flag-restorer Add `-run` flag to the `restorer` binary	2024-07-09 12:33:20 -04:00
Pavel Busko	7f44395c97	clarify run image resolution during restore phase Signed-off-by: Pavel Busko <pavel.busko@sap.com>	2024-07-04 12:30:56 +02:00
Pavel Busko	664e7a0eb3	Add -run flag to the restorer binary Signed-off-by: Pavel Busko <pavel.busko@sap.com>	2024-07-03 12:32:39 +02:00
Natalie Arellano	7207c7dd71	Merge pull request #405 from ryanbrainard/patch-1 Close code fence	2024-04-19 09:53:47 -04:00
Ryan Brainard	c995c549f7	Close code fence Add closing backtick of code fence to fix rendering Signed-off-by: Ryan Brainard <966764+ryanbrainard@users.noreply.github.com>	2024-04-18 10:20:47 -04:00
Natalie Arellano	b341177441	Merge pull request #402 from edmorley/fix-distros.version-field-name Correct name of `distros.version` field in `buildpack.toml`	2024-04-09 09:28:02 -04:00
Ed Morley	7c68e77461	Correct name of `distros.version` field in `buildpack.toml` The correct name for the field is `distros.version` (singular), rather than `distros.versions`. The former is what is used elsewhere in the spec, and in the lifecycle implementation. The plural form looks like a leftover from the rename in: `8652ec5e49` Fixes #401. Signed-off-by: Ed Morley <501702+edmorley@users.noreply.github.com>	2024-04-08 16:15:33 +01:00
Natalie Arellano	87dc65b961	Merge pull request #397 from edmorley/patch-1 Correct specification for deprecated `CNB_STACK_ID`	2024-03-27 15:52:27 -04:00
Ed Morley	551833d3d1	Correct specification for deprecated `CNB_STACK_ID` Restores the specification for `CNB_STACK_ID` to the definition that was used prior to the docs refactor in #335. Fixes #396. Signed-off-by: Ed Morley <501702+edmorley@users.noreply.github.com>	2024-03-27 16:39:42 +00:00
Natalie Arellano	bd040abaf6	Merge pull request #392 from buildpacks/platform/0.13 Finalize Platform/0.13	2024-03-05 15:52:46 -05:00
Natalie Arellano	a5abebae3f	Merge branch 'main' into platform/0.13	2024-03-05 13:04:21 -05:00
Natalie Arellano	0389b50d7b	Merge pull request #393 from buildpacks/buildpack/0.11 Finalize Buildpack/0.11	2024-03-05 13:04:03 -05:00
Natalie Arellano	f56c8db7bb	Merge branch 'main' into buildpack/0.11	2024-03-05 11:21:52 -05:00
Natalie Arellano	15ddfc8027	Merge branch 'main' into platform/0.13	2024-03-05 11:21:14 -05:00
Natalie Arellano	a762860c1e	Merge pull request #394 from buildpacks/buildpack/v0.11 Combine Buildpack/v0.11 branches	2024-03-05 11:20:43 -05:00
Natalie Arellano	b2fd486066	Merge pull request #385 from buildpacks/insecure-registries Add insecure registries flags and env var	2024-03-04 12:42:45 -05:00
Natalie Arellano	845d862394	Merge branch 'platform/0.13' into insecure-registries	2024-03-04 12:42:11 -05:00
Natalie Arellano	cc0925b862	Merge pull request #387 from loewenstein/extensions-buildpack Remove `experimental` mark on extensions	2024-03-01 09:42:01 -05:00
Natalie Arellano	2ff96c2b34	Merge pull request #377 from buildpacks/remove-glue Remove backwards compatible glue for unsupported buildpack API 0.2	2024-03-01 09:41:46 -05:00
Natalie Arellano	296f8becfb	Merge pull request #386 from loewenstein/extensions-platform Remove `experimental` mark on extensions	2024-03-01 09:40:53 -05:00
Natalie Arellano	347a977e79	Merge pull request #380 from kritkasahni-google/main Platform API changes to enable exporting app image and cache image in parallel	2024-03-01 09:40:36 -05:00
Natalie Arellano	29d53ac429	Merge pull request #390 from thiunuwan/patch-1 Update buildpack.md	2024-03-01 09:40:01 -05:00
Ravindu Thiunuwan	d13cf5f53e	Update buildpack.md Signed-off-by: Ravindu Thiunuwan <83197833+thiunuwan@users.noreply.github.com>	2024-03-01 10:18:38 +05:30
Jan von Löwenstein	ae39fb0367	Remove `experimental` mark on extensions Signed-off-by: Jan von Löwenstein <jan.von.loewenstein@sap.com>	2024-02-05 18:16:54 +00:00
Jan von Löwenstein	88050e72d5	Remove `experimental` mark on extensions Signed-off-by: Jan von Löwenstein <jan.von.loewenstein@sap.com>	2024-02-05 18:16:21 +00:00
Natalie Arellano	e7f547c3c0	Merge pull request #383 from sap-contributions/extension-contexts-extension-md Changes for image extension build contexts	2024-02-01 13:03:22 -05:00
Natalie Arellano	f4778c7805	Merge pull request #384 from sap-contributions/extension-contexts-platform-md Platform API changes for image extension build contexts	2024-02-01 13:03:14 -05:00
Natalie Arellano	334893105d	Add insecure registries flags and env var Signed-off-by: Natalie Arellano <narellano@vmware.com>	2024-01-17 15:00:51 -05:00
Ralf Pannemans	3bb19203e3	Add recoring of build-image.extend Signed-off-by: Ralf Pannemans <ralf.pannemans@sap.com> Co-authored-by: Philipp Stehle <philipp.stehle@sap.com>	2024-01-09 13:09:03 +01:00
Ralf Pannemans	b19fdbdaa8	Platform API changes for image extension build contexts Signed-off-by: Ralf Pannemans <ralf.pannemans@sap.com> Co-authored-by: Philipp Stehle <philipp.stehle@sap.com> Co-authored-by: Ralf Pannemans <ralf.pannemans@sap.com> Co-authored-by: Pavel Busko <pavel.busko@sap.com>	2024-01-09 12:52:18 +01:00
Ralf Pannemans	43c7cd9950	Changes for image extension build contexts Signed-off-by: Ralf Pannemans <ralf.pannemans@sap.com> Co-authored-by: Philipp Stehle <philipp.stehle@sap.com> Co-authored-by: Pavel Busko <pavel.busko@sap.com> Co-authored-by: Ralf Pannemans <ralf.pannemans@sap.com>	2024-01-09 12:47:48 +01:00
Natalie Arellano	36695bacab	Update platform.md Signed-off-by: Natalie Arellano <narellano@vmware.com>	2023-11-15 10:48:22 -05:00
kritka sahni	cd8843b8b4	Platform API changes to enable exporting app image and cache image in parallel Signed-off-by: kritka sahni <kritkasahni@google.com>	2023-11-15 05:07:28 +00:00
Natalie Arellano	0f5d7f2332	Remove backwards compatible glue for unsupported buildpack API 0.2 Signed-off-by: Natalie Arellano <narellano@vmware.com>	2023-08-23 15:02:47 -04:00