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

fix typo to image extension link

README.md

@@ -50,6 +50,6 @@ When the specification refers to a path in the context of an OCI layer tar (e.g.
 
 These documents currently specify:
 
-- Buildpack API: `0.9`
+- Buildpack API: `0.10`
 - Distribution API: `0.3`
-- Platform API: `0.10`
+- Platform API: `0.14`

buildpack.md

@@ -24,7 +24,6 @@ This document specifies the interface between a lifecycle program and one or mor
   - [Phase #1: Detection](#phase-1-detection)
     - [Purpose](#purpose)
     - [Process](#process)
-      - [Mixin Satisfaction](#mixin-satisfaction)
       - [Order Resolution](#order-resolution)
   - [Phase #2: Analysis](#phase-2-analysis)
     - [Purpose](#purpose-1)
@@ -51,6 +50,7 @@ This document specifies the interface between a lifecycle program and one or mor
     - [Process](#process-5)
   - [Environment](#environment)
     - [Provided by the Lifecycle](#provided-by-the-lifecycle)
+      - [Targets](#targets)
       - [Layer Paths](#layer-paths)
     - [Provided by the Platform](#provided-by-the-platform)
     - [Provided by the Buildpacks](#provided-by-the-buildpacks)
@@ -71,17 +71,18 @@ This document specifies the interface between a lifecycle program and one or mor
     - [Buildpack Plan (TOML)](#buildpack-plan-toml)
     - [Layer Content Metadata (TOML)](#layer-content-metadata-toml)
     - [buildpack.toml (TOML)](#buildpacktoml-toml)
-      - [Stacks](#stacks)
+      - [Targets](#targets-1)
       - [Order](#order)
     - [Exec.d Output (TOML)](#execd-output-toml)
   - [Deprecations](#deprecations)
+    - [buildpack.toml (TOML) `stacks` Array](#buildpacktoml-toml-stacks-array)
     - [Positional Arguments to `detect` and `build` Executables](#positional-arguments-to-detect-and-build-executables)
     - [launch.toml (TOML) `bom` Array](#launchtoml-toml-bom-array)
     - [build.toml (TOML) `bom` Array](#buildtoml-toml-bom-array)
     - [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key)
 
 ## Buildpack API Version
-This document specifies Buildpack API version `0.9`
+This document specifies Buildpack API version `0.10`
 
 Buildpack API versions:
  - MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
@@ -102,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.
 
@@ -132,10 +133,6 @@ A **layer directory** is a directory created by a component buildpack that conta
   * a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build
 Any combination of the three layer types are valid for a particular layer directory.
 
-A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to component buildpacks through the `CNB_STACK_ID` environment variable, enabling each component buildpack to modify its behavior when executed on different stacks.
-
-A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. Buildpacks can express their required mixins in `buildpack.toml`.
-
 ## Buildpack Interface
 
 The following specifies the interface implemented by component buildpacks.
@@ -164,14 +161,14 @@ The lifecycle MAY return an error to the platform if two or more buildpacks with
 
 Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 
-| Input                    | Attributes | Description                                   |
-|--------------------------|------------|-----------------------------------------------|
-| `$0`                     |            | Absolute path of `/bin/detect` executable     |
-| `$CNB_BUILD_PLAN_PATH`   | E          | Absolute path of the build plan               |
-| `$CNB_BUILDPACK_DIR`     | ER         | Absolute path of the buildpack root directory |
-| `$CNB_PLATFORM_DIR`      | AR         | Absolute path of the platform directory       |
-| `$CNB_PLATFORM_DIR/env/` | AR         | User-provided environment variables for build |
-| `$CNB_PLATFORM_DIR/#`    | AR         | Platform-specific extensions                  |
+| Input                    | Attributes | Description                                       |
+|--------------------------|------------|---------------------------------------------------|
+| `$0`                     |            | Absolute path of `/bin/detect` executable         |
+| `$CNB_BUILD_PLAN_PATH`   | E          | Absolute path of the build plan                   |
+| `$CNB_BUILDPACK_DIR`     | ER         | Absolute path of the buildpack root directory     |
+| `$CNB_PLATFORM_DIR`      | AR         | Absolute path of the platform directory           |
+| `$CNB_PLATFORM_DIR/env/` | AR         | User-provided environment variables for build     |
+| `$CNB_PLATFORM_DIR/#`    | AR         | Platform-specific extensions                      |
 
 | Output                 | Description                                 |
 |------------------------|---------------------------------------------|
@@ -372,10 +369,13 @@ For each image extension ("extension") or component buildpack ("buildpack") in e
 The selected group MUST be filtered to only include extensions and buildpacks with exit status zero.
 The order of the extensions and buildpacks in the group MUST otherwise be preserved.
 
+For each `/bin/detect` executable in each extension or buildpack, the lifecycle:
+
+- MUST configure the environment as described in the [Environment](#environment) section.
+
 The `/bin/detect` executable in each extension or buildpack, when executed:
 
 - MAY read the app directory.
-- MAY read the detect environment as described in the [Environment](#environment) section.
 - MAY emit error, warning, or debug messages to `stderr`.
 - MAY augment the Build Plan by writing TOML to `<plan>`.
 - MUST set an exit status code as described in the [Buildpack Interface](#buildpack-interface) section.
@@ -400,21 +400,8 @@ For each trial,
 
 The lifecycle MAY execute each `/bin/detect` within a group in parallel.
 
-The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using common stack with a common set of mixins.
-The lifecycle MUST fail detection if any of the buildpacks does not list that stack in `buildpack.toml`.
-The lifecycle MUST fail detection if any of the buildpacks specifies a mixin associated with that stack in `buildpack.toml` that is not satisfied, see [Mixin Satisfaction](#mixin-satisfaction) below.
-
-#### Mixin Satisfaction
-
-A buildpack's mixin requirements must be satisfied by the stack in one of the following scenarios.
-
-1) the stack provides the mixin `run:<mixin>` and the buildpack requires `run:<mixin>`
-2) the stack provides the mixin `build:<mixin>` and the buildpack requires `build:<mixin>`
-3) the stack provides the mixin `<mixin>` and the buildpack requires `<mixin>`
-4) the stack provides the mixin `<mixin>` and the buildpack requires `build:<mixin>`
-5) the stack provides the mixin `<mixin>` and the buildpack requires `run:<mixin>`
-6) the stack provides the mixin `<mixin>` and the buildpack requires both `run:<mixin>` and `build:<mixin>`
-7) the stack provides the mixins `build:<mixin>` and `run:<mixin>` the buildpack requires `<mixin>`
+The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using a common build environment.
+If any non-optional buildpack in a group fails to declare a target in `buildpack.toml` matching the build-time and runtime base images, and in the case that no targets are declared and the [inferred target](#targets-1) does not match, the lifecycle MUST fail detection for the group. For matching criteria, see [buildpack.toml](#buildpacktoml-toml).
 
 #### Order Resolution
 
@@ -513,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)
 
@@ -687,7 +674,7 @@ The purpose of export is to create a new OCI image using a combination of remote
 - The `<layers>` directories provided to each buildpack during the build phase,
 - The `<app>` directory processed by the buildpacks during the build phase,
 - The buildpack IDs associated with the buildpacks used during the build phase, in order of execution,
-- A reference to the most recent version of the run image associated with the stack and mixins,
+- A reference to the most recent version of the run image,
 - A reference to the old OCI image processed during the analysis phase, if available, and
 - A tag for a new OCI image,
 
@@ -760,9 +747,21 @@ The purpose of launch is to modify the running app environment using app-provide
 
 ### Provided by the Lifecycle
 
+#### Targets
+
+The following environment variables MUST be set by the lifecycle during the `detect` and `build` phases to describe the target runtime image, if inputs are provided.
+
+| Env Variable                | Description                                |
+|-----------------------------|--------------------------------------------|
+| `CNB_TARGET_OS`             | Target OS                                  |
+| `CNB_TARGET_ARCH`           | Target architecture                        |
+| `CNB_TARGET_ARCH_VARIANT`   | Target architecture variant (optional)     |
+| `CNB_TARGET_DISTRO_NAME`    | Target OS distribution name (optional)     |
+| `CNB_TARGET_DISTRO_VERSION` | Target OS distribution version (optional)  |
+
 #### Layer Paths
 
-The following layer path environment variables MUST be set by the lifecycle during the build and launch phases in order to make buildpack dependencies accessible.
+The following layer path environment variables MUST be set by the lifecycle during the `build` and `launch` phases in order to make buildpack dependencies accessible.
 
 During the build phase, each variable designated for build MUST contain absolute paths of all previous buildpacks’ `<layers>/<layer>/` directories that are designated for build.
 
@@ -782,19 +781,18 @@ In either case,
 | `CPATH`                                    | `/include`   | header files     | [x]   |        |
 | `PKG_CONFIG_PATH`                          | `/pkgconfig` | pc files         | [x]   |        |
 
-
 ### Provided by the Platform
 
 The following additional environment variables MUST NOT be overridden by the lifecycle.
 
-| Env Variable    | Description                                    | Detect | Build | Launch
-|-----------------|------------------------------------------------|--------|-------|--------
-| `CNB_STACK_ID`  | Chosen stack ID                                | [x]    | [x]   |
-| `BP_*`          | User-provided variable for buildpack           | [x]    | [x]   |
-| `BPL_*`         | User-provided variable for exec.d              |        |       | [x]
-| `HOME`          | Current user's home directory                  | [x]    | [x]   | [x]
+| Env Variable           | Description                                       | Detect | Build | Launch |
+|------------------------|---------------------------------------------------|--------|-------|--------|
+| `BP_*`                 | User-provided variable for buildpack              | [x]    | [x]   |        |
+| `BPL_*`                | User-provided variable for exec.d                 |        |       | [x]    |
+| `HOME`                 | Current user's home directory                     | [x]    | [x]   | [x]    |
 
-During the detection and build phases, the lifecycle MUST provide any user-provided environment variables as files in `<platform>/env/` with file names and contents matching the environment variable names and contents.
+During the detection and build phases, the lifecycle MUST provide as environment variables any user-provided files in `<platform>/env/` with environment variable names and contents matching the file names and contents.
+During the detection and build phases, the lifecycle MUST provide as environment variables any operator-provided files in `<build-config>/env` with environment variable names and contents matching the file names and contents. This applies for all values of `clear-env` or if `clear-env` is undefined in `buildpack.toml`.
 
 When `clear-env` in `buildpack.toml` is set to `true` for a given buildpack, the lifecycle MUST NOT set user-provided environment variables in the environment of `/bin/detect` or `/bin/build`.
 
@@ -802,8 +800,6 @@ When `clear-env` in `buildpack.toml` is not set to `true` for a given buildpack,
 1. For layer path environment variables, user-provided values are prepended before any existing values and are delimited by the OS path list separator.
 2. For all other environment variables, user-provided values override any existing values.
 
-Buildpacks MAY use the value of `CNB_STACK_ID` to modify their behavior when executed on different stacks.
-
 The environment variable prefix `CNB_` is reserved.
 It MUST NOT be used for environment variables that are not defined in this specification or approved extensions.
 
@@ -1059,9 +1055,13 @@ id = "<buildpack ID>"
 version = "<buildpack version>"
 optional = false
 
-[[stacks]]
-id = "<stack ID>"
-mixins = ["<mixin name>"]
+[[targets]]
+os = "<OS name>"
+arch = "<architecture>"
+variant = "<architecture variant>"
+[[targets.distros]]
+name = "<OS distribution name>"
+version = "<OS distribution version>"
 
 [metadata]
 # buildpack-specific data
@@ -1081,8 +1081,6 @@ Buildpack authors MUST choose a globally unique ID, for example: "io.buildpacks.
    - Each element MUST increase numerically.
    - Buildpack authors will define what changes will increment `X`, `Y`, and `Z`.
 
-If an `order` is specified, then `stacks` MUST NOT be specified.
-
 **The buildpack API:**
 
 *Key: `api = "<buildpack API version>"`*
@@ -1102,17 +1100,24 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa
 *Key: `sbom-formats = [ "<string>" ]`*
  - MUST be supported SBOM media types as described in [Software-Bill-of-Materials](#software-bill-of-materials).
 
-#### Stacks
+#### Targets
 
-A buildpack descriptor may specify `stacks`.
+A buildpack descriptor SHOULD specify `targets`.
 
-Each stack in `stacks` either:
-- MUST identify a compatible stack:
-   - `id` MUST be set to a [valid stack ID](https://github.com/buildpacks/spec/blob/main/platform.md#stack-id).
-   - `mixins` MAY contain one or more mixin names.
-- Or MUST indicate compatibility with any stack:
-   - `id` MUST be set to the special value `"*"`.
-   - `mixins` MUST be empty.
+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.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:
+  - `os = "linux"` and `arch = <matches any>` if `./bin/build` is present
+  - `os = "windows"` and `arch = <matches any>` if `./bin/build.bat` or `./bin/build.exe` are present
+
+Metadata specified in `[[targets]]` is validated against the runtime and build-time base images.
+* A buildpack target satisfies a base image target when `os`, `arch`, and `variant` match and at least one distribution in `distros` (if provided) matches
    
 #### Order
 
@@ -1135,6 +1140,41 @@ Each `key`:
 ## Deprecations
 This section describes all the features that are deprecated.
 
+### buildpack.toml (TOML) `stacks` Array
+
+_Deprecated in Buildpack API 0.10._
+
+The `stacks` array is deprecated.
+
+```toml
+[[stacks]]
+id = "<stack ID>"
+mixins = ["<mixin name>"]
+```
+
+Each stack in `stacks` either:
+- MUST identify a compatible stack:
+    - `id` MUST be set to a [valid stack ID](https://github.com/buildpacks/spec/blob/main/platform.md#stack-id).
+    - `mixins` MAY contain one or more mixin names.
+- Or MUST indicate compatibility with any stack:
+    - `id` MUST be set to the special value `"*"`.
+    - `mixins` MUST be empty.
+
+If an `order` is specified, then `stacks` MUST NOT be specified.
+
+Tools reading `buildpack.toml` will translate any section that sets `stacks.id = "io.buildpacks.stacks.bionic"` to:
+
+```toml
+[[targets]]
+os = "linux"
+arch = "amd64"
+[[targets.distros]]
+name = "ubuntu"
+version = "18.04"
+```
+
+Furthermore, any buildpack that contains `[[stacks]]` with `id = "*"` will match any target.
+
 ### Positional Arguments to `detect` and `build` Executables
 
 _Deprecated in Buildpack API 0.8._
@@ -1202,48 +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>"
-```

extensions/project-descriptor.md

@@ -29,8 +29,8 @@ This document specifies Project Descriptor Schema Version `0.2`.
 
 The Schema Version format follows the form of the [Buildpack API Version](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-api-version):
 
-* 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
+* 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
 
 ## Special Value Types
 

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.
 
@@ -21,7 +21,7 @@ This document specifies the interface between a lifecycle program and one or mor
 
 ## Image Extension API Version
 
-This document accompanies Buildpack API version `0.9`.
+This document accompanies Buildpack API version `0.10`.
 
 ## Image Extension Interface
 
@@ -89,15 +89,40 @@ 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`
 
 - MAY contain a single `FROM` instruction
-- MUST NOT contain any other instructions
+- MUST NOT contain any other `FROM` instructions
+- MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
+- SHOULD NOT contain any other instructions
+- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability)
+- SHOULD NOT edit `<app>`, `<layers>`, or `<platform>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
+- SHOULD use the `user_id` and `group_id` build args to reset the image config's `User` field to its original value if any `USER` instructions are employed
+- SHOULD set the label `io.buildpacks.rebasable` to `true` to indicate that any new run image layers are safe to rebase on top of new runtime base images
+  - For the final image to be rebasable, all applied Dockerfiles must set this label to `true`
 
 A `build.Dockerfile`
 
@@ -110,7 +135,8 @@ FROM ${base_image}
 - MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
 - SHOULD NOT contain any other instructions
 - SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability)
-- SHOULD NOT edit `<app>`, `<layers>`, or `<workspace>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
+- SHOULD NOT edit `<app>`, `<layers>`, or `<platform>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
+- SHOULD use the `user_id` and `group_id` build args to reset the image config's `User` field to its original value if any `USER` instructions are employed
 
 ## Phase: Extension
 
@@ -132,6 +158,9 @@ For each Dockerfile in the group in order, the lifecycle MUST apply the Dockerfi
     - When there are multiple Dockerfiles, the value MUST be the intermediate image generated from the application of the previous Dockerfile.
 - A `build_id` build arg
     - The value MUST be a UUID
+- `user_id` and `group_id` build args
+    - For the first Dockerfile, the values MUST be the original `uid` and `gid` from the `User` field of the config for the original base image.
+    - When there are multiple Dockerfiles, the values MUST be the `uid` and `gid` from the `User` field of the config for the intermediate image generated from the application of the previous Dockerfile.
 
 ## Data Format
 
@@ -155,24 +184,45 @@ keywords = [ "<string>" ]
 [[extension.licenses]]
 type = "<string>"
 uri = "<uri>"
+
+[[targets]]
+os = "<OS name>"
+arch = "<architecture>"
+variant = "<architecture variant>"
+[[targets.distros]]
+name = "<OS distribution name>"
+version = "<OS distribution version>"
+
+[metadata]
+# extension-specific data
 ```
 
 Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt".
 
 The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
 
+An extension descriptor MAY specify `targets` following the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+
 ### extend-config.toml (TOML)
 
 ```toml
 [[build.args]]
 name = "<build arg name>"
 value = "<build arg value>"
+
+[[run.args]]
+name = "<build arg name>"
+value = "<build arg value>"
 ```
 
 The image extension MAY specify any number of args.
 
-For each arg, the image extension:
-- MUST specify a `name` to be the name of a build argument that will be provided to any output build.Dockerfile when extending the build base image.
+For each `[[build.args]]`, the image extension:
+- MUST specify a `name` to be the name of a build argument that will be provided to any output `build.Dockerfile` when extending the build base image.
+- MUST specify a `value` to be the value of the build argument that is provided.
+
+For each `[[run.args]]`, the image extension:
+- MUST specify a `name` to be the name of a build argument that will be provided to any output `run.Dockerfile` when extending the runtime base image.
 - MUST specify a `value` to be the value of the build argument that is provided.
 
 ### Build Plan (TOML)