From 80a272e74ddecf1aa688ce1376a829c1f27f8110 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 6 May 2025 20:58:38 -0500 Subject: [PATCH 1/7] Add Execution Enviroment Signed-off-by: Juan Bustamante --- buildpack.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 69d6ade..1a8028f 100644 --- a/buildpack.md +++ b/buildpack.md @@ -138,6 +138,26 @@ Any combination of the three layer types are valid for a particular layer direct The following specifies the interface implemented by component buildpacks. The lifecycle MUST invoke executables in component buildpacks as described in the Phase sections. +### Execution Environments + +Execution environments define the context in which a buildpack-created application is intended to run. Standard values include: +- `production`: The default environment, optimized for running applications in production. +- `test`: Environment optimized for testing applications. +- `development`: Environment optimized for development workflows. + +Buildpacks SHOULD adapt their behavior based on the `CNB_EXEC_ENV` environment variable during detection and build phases. This may include: +- Installing different dependencies +- Configuring different build options +- Creating different launch processes +- Providing environment-specific layers + +Buildpacks MAY optimize their output based on the execution environment: +- A buildpack MAY mark processes as applicable only to specific execution environments +- A buildpack MAY create layers that are specific to certain execution environments +- A buildpack MAY use different build strategies depending on the execution environment + +When the `CNB_EXEC_ENV` environment variable is not set, buildpacks MUST assume the default value of `production`. + ### Buildpack API Compatibility Given a buildpack declaring `` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle: - MUST either conform to the matching version of this specification when interfacing with the buildpack or @@ -166,6 +186,7 @@ Executable: `/bin/detect`, Working Dir: `` | `$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_EXEC_ENV` | | Target execution environment ("production", "test", "development") | | `$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 | @@ -187,6 +208,7 @@ Executable: `/bin/build`, Working Dir: `` | `$CNB_LAYERS_DIR` | EIC | Absolute path of the buildpack layers directory | | `$CNB_BP_PLAN_PATH` | ER | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) | | `$CNB_BUILDPACK_DIR` | ER | Absolute path of the buildpack root directory | +| `$CNB_EXEC_ENV` | | Target execution environment ("production", "test", "development") | | `$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 | @@ -907,6 +929,7 @@ command = [""] args = [""] default = false working-dir = "" +exec-env = ["", ...] # Optional. If not specified, applies to all execution environments [[slices]] paths = [""] @@ -1021,7 +1044,8 @@ name = "" cache = false [metadata] -# buildpack-specific data + exec-env = ["", ...] # Optional. If not specified, applies to all execution environments + # other buildpack-specific data ``` For a given layer, the buildpack MAY specify: @@ -1059,6 +1083,7 @@ optional = false os = "" arch = "" variant = "" +exec-env = ["", ...] # Optional. If not specified, applies to all execution environments [[targets.distros]] name = "" version = "" @@ -1107,6 +1132,7 @@ A buildpack descriptor SHOULD specify `targets`. 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) + - `exec-env` if provided MUST specify one or more execution environments for which the buildpack is compatible (e.g., "production", "test", "development") - `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`) From befbc5566d51c35280873282bc9e7203b83b3460 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 6 May 2025 21:10:06 -0500 Subject: [PATCH 2/7] fixing formatting issues Signed-off-by: Juan Bustamante --- buildpack.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/buildpack.md b/buildpack.md index 1a8028f..e3be55a 100644 --- a/buildpack.md +++ b/buildpack.md @@ -929,7 +929,7 @@ command = [""] args = [""] default = false working-dir = "" -exec-env = ["", ...] # Optional. If not specified, applies to all execution environments +exec-env = [""] # Optional. If not specified, applies to all execution environments [[slices]] paths = [""] @@ -1044,7 +1044,7 @@ name = "" cache = false [metadata] - exec-env = ["", ...] # Optional. If not specified, applies to all execution environments + exec-env = [""] # Optional. If not specified, applies to all execution environments # other buildpack-specific data ``` @@ -1083,7 +1083,7 @@ optional = false os = "" arch = "" variant = "" -exec-env = ["", ...] # Optional. If not specified, applies to all execution environments +exec-env = [""] # Optional. If not specified, applies to all execution environments [[targets.distros]] name = "" version = "" From ffa953f1fbcaf2cc267082bc6ce0c6184aa7689c Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Fri, 9 May 2025 11:06:18 -0500 Subject: [PATCH 3/7] I've made the requested changes to address the feedback on PR #415. Specifically: 1. Added clarification about platform behavior when the execution environment differs between builds 2. Added a note prohibiting the / character in execution environment values as it's reserved Signed-off-by: Juan Bustamante --- buildpack.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/buildpack.md b/buildpack.md index e3be55a..b50fbe3 100644 --- a/buildpack.md +++ b/buildpack.md @@ -158,6 +158,10 @@ Buildpacks MAY optimize their output based on the execution environment: When the `CNB_EXEC_ENV` environment variable is not set, buildpacks MUST assume the default value of `production`. +The value of `CNB_EXEC_ENV` MUST NOT contain the character `/` as it is reserved for future use. + +When a platform builds an application with a different execution environment than was used in a previous build, the platform SHOULD NOT restore layers from the previous build's image. The lifecycle MAY ignore layer metadata from previous builds with different execution environments to ensure proper environment-specific behaviors are maintained. + ### Buildpack API Compatibility Given a buildpack declaring `` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle: - MUST either conform to the matching version of this specification when interfacing with the buildpack or From 531f835403cea4341b77277a88def65537dacd5f Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 3 Jun 2025 08:28:25 -0500 Subject: [PATCH 4/7] =?UTF-8?q?=20=201.=20=E2=9C=85=20Added=20CNB=5FEXEC?= =?UTF-8?q?=5FENV=20to=20the=20restorer=20phase=20=20=202.=20=E2=9C=85=20A?= =?UTF-8?q?dded=20CNB=5FEXEC=5FENV=20to=20the=20extender=20phase=20=20=203?= =?UTF-8?q?.=20=E2=9C=85=20Clarified=20buildpack/group=20skipping=20behavi?= =?UTF-8?q?or=20for=20environment=20mismatches=20in=20the=20detector=20sec?= =?UTF-8?q?tion=20=20=204.=20=E2=9C=85=20Updated=20metadata=20recording=20?= =?UTF-8?q?to=20include=20exec-env=20field=20with=20proper=20documentation?= =?UTF-8?q?=20about=20using=20["*"]=20for=20all=20environments?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The changes ensure that: - The execution environment is properly propagated through all relevant lifecycle phases - The behavior for environment mismatches is clearly defined - Process metadata properly records execution environment restrictions using ["*"] for universal processes Signed-off-by: Juan Bustamante --- platform.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/platform.md b/platform.md index 9bd174f..2edcdcc 100644 --- a/platform.md +++ b/platform.md @@ -409,6 +409,7 @@ Usage: | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | | ``^ | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | +| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | > ^Only needed when using image extensions @@ -442,6 +443,10 @@ The lifecycle: - SHALL detect a single group from `` and write it to `` using the [detection process](buildpack.md#phase-1-detection) outlined in the Buildpack Interface Specification - SHALL write the resolved build plan from the detected group to `` - SHALL provide `run-image.target` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). +- When `CNB_EXEC_ENV` is set and differs from a previous build's execution environment: + - The lifecycle SHALL skip buildpacks that do not support the current execution environment + - If all buildpacks in a group are skipped due to execution environment mismatch, the lifecycle SHALL continue to the next group in the order + - The lifecycle SHOULD NOT restore layers from previous builds with different execution environments When image extensions are present in the order (optional), the lifecycle: - SHALL execute all image extensions in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). @@ -501,6 +506,7 @@ Usage: | `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | | `` | `CNB_USER_ID` | | UID of the build image `User` | | ``** | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | +| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | > ^ Only needed when using image extensions > \* Only needed when using image extensions to extend the build image @@ -588,6 +594,7 @@ Usage: | ``* | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | | ``* | `CNB_USER_ID` | | UID of the build image `User` | +| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | > \* Only needed when extending the build image @@ -661,6 +668,7 @@ Usage: | `` | `CNB_LOG_LEVEL` | `info` | Log Level | | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | +| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | ##### Outputs @@ -1328,6 +1336,7 @@ command = [""] args = [""] direct = false working-dir = "" +exec-env = [""] [[slices]] paths = [""] @@ -1336,6 +1345,8 @@ paths = [""] Where: - `id`, `version`, and `api` MUST be present for each buildpack - `processes` contains the complete set of processes contributed by all buildpacks + - `exec-env` field MUST be set to `["*"]` if the process applies to all execution environments + - `exec-env` field MUST contain specific execution environment values if the process is restricted to certain environments - `slices` contains the complete set of slices defined by all buildpacks #### `order.toml` (TOML) @@ -1448,6 +1459,7 @@ Where: ], "direct": false, "working-dir": "", + "exec-env": [""], "buildpackID": "" } ], From c5b227d44178424ad64b743185a4ac9e9a80cb8c Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 3 Jun 2025 08:35:45 -0500 Subject: [PATCH 5/7] reverting changes in platform.md, this must be added in the other PR for plaform changes Signed-off-by: Juan Bustamante --- platform.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/platform.md b/platform.md index 2edcdcc..9bd174f 100644 --- a/platform.md +++ b/platform.md @@ -409,7 +409,6 @@ Usage: | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | | ``^ | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | -| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | > ^Only needed when using image extensions @@ -443,10 +442,6 @@ The lifecycle: - SHALL detect a single group from `` and write it to `` using the [detection process](buildpack.md#phase-1-detection) outlined in the Buildpack Interface Specification - SHALL write the resolved build plan from the detected group to `` - SHALL provide `run-image.target` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). -- When `CNB_EXEC_ENV` is set and differs from a previous build's execution environment: - - The lifecycle SHALL skip buildpacks that do not support the current execution environment - - If all buildpacks in a group are skipped due to execution environment mismatch, the lifecycle SHALL continue to the next group in the order - - The lifecycle SHOULD NOT restore layers from previous builds with different execution environments When image extensions are present in the order (optional), the lifecycle: - SHALL execute all image extensions in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). @@ -506,7 +501,6 @@ Usage: | `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | | `` | `CNB_USER_ID` | | UID of the build image `User` | | ``** | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | -| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | > ^ Only needed when using image extensions > \* Only needed when using image extensions to extend the build image @@ -594,7 +588,6 @@ Usage: | ``* | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | | ``* | `CNB_USER_ID` | | UID of the build image `User` | -| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | > \* Only needed when extending the build image @@ -668,7 +661,6 @@ Usage: | `` | `CNB_LOG_LEVEL` | `info` | Log Level | | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | -| | `CNB_EXEC_ENV` | `production` | Target execution environment ("production", "test", "development") | ##### Outputs @@ -1336,7 +1328,6 @@ command = [""] args = [""] direct = false working-dir = "" -exec-env = [""] [[slices]] paths = [""] @@ -1345,8 +1336,6 @@ paths = [""] Where: - `id`, `version`, and `api` MUST be present for each buildpack - `processes` contains the complete set of processes contributed by all buildpacks - - `exec-env` field MUST be set to `["*"]` if the process applies to all execution environments - - `exec-env` field MUST contain specific execution environment values if the process is restricted to certain environments - `slices` contains the complete set of slices defined by all buildpacks #### `order.toml` (TOML) @@ -1459,7 +1448,6 @@ Where: ], "direct": false, "working-dir": "", - "exec-env": [""], "buildpackID": "" } ], From f0d3739ef0d36c9d440860d6a02953f2dd318876 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Sun, 26 Oct 2025 17:25:09 -0500 Subject: [PATCH 6/7] - Removed exec-env from the [[targets]] TOML example - Added new [[buildpack.exec-env]] section with name field - Added documentation explaining that [[buildpack.exec-env]] is optional and lists supported execution environments - Removed exec-env documentation from the Targets section - Added exec-env field to [[order.group]] TOML example - Added documentation explaining that buildpack references in a group MAY contain an exec-env array Signed-off-by: Juan Bustamante --- buildpack.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index b50fbe3..b49a70c 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1077,17 +1077,20 @@ sbom-formats = [ "" ] type = "" uri = "" +[[buildpack.exec-env]] +name = "" + [[order]] [[order.group]] id = "" version = "" optional = false +exec-env = [""] [[targets]] os = "" arch = "" variant = "" -exec-env = [""] # Optional. If not specified, applies to all execution environments [[targets.distros]] name = "" version = "" @@ -1124,6 +1127,12 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa - `type` - This MAY use the SPDX 2.1 license expression, but is not limited to identifiers in the SPDX Licenses List. - `uri` - If this buildpack is using a nonstandard license, then this key MAY be specified in lieu of or in addition to `type` to point to the license. +**The buildpack execution environments:** + +The `[[buildpack.exec-env]]` table is optional and MAY contain a list of execution environments that the buildpack supports where: + +- `name` - This MUST specify an execution environment name (e.g., "production", "test", "development"). + **The buildpack SBOM:** *Key: `sbom-formats = [ "" ]`* @@ -1136,7 +1145,6 @@ A buildpack descriptor SHOULD specify `targets`. 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) - - `exec-env` if provided MUST specify one or more execution environments for which the buildpack is compatible (e.g., "production", "test", "development") - `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`) @@ -1153,6 +1161,8 @@ Metadata specified in `[[targets]]` is validated against the runtime and build-t A buildpack reference inside of a `group` MUST contain an `id` and `version`. The `order` MUST include only buildpacks and MUST NOT include image extensions. +A buildpack reference inside of a `group` MAY contain an `exec-env` array to specify the execution environments for which the buildpack applies. + ### Exec.d Output (TOML) ``` = "" From bf7d6a1363b3b0bf6fc4af640f3e2747f9c98563 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Sun, 26 Oct 2025 17:50:16 -0500 Subject: [PATCH 7/7] - Added "AR" attribute to CNB_EXEC_ENV in detect and build tables (marking it as platform-provided and read-only) - Added formal specification text for exec-env in processes - Added formal specification text for exec-env in layer metadata Signed-off-by: Juan Bustamante --- buildpack.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index b49a70c..42a3da4 100644 --- a/buildpack.md +++ b/buildpack.md @@ -190,7 +190,7 @@ Executable: `/bin/detect`, Working Dir: `` | `$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_EXEC_ENV` | | Target execution environment ("production", "test", "development") | +| `$CNB_EXEC_ENV` | AR | Target execution environment ("production", "test", "development") | | `$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 | @@ -212,7 +212,7 @@ Executable: `/bin/build`, Working Dir: `` | `$CNB_LAYERS_DIR` | EIC | Absolute path of the buildpack layers directory | | `$CNB_BP_PLAN_PATH` | ER | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) | | `$CNB_BUILDPACK_DIR` | ER | Absolute path of the buildpack root directory | -| `$CNB_EXEC_ENV` | | Target execution environment ("production", "test", "development") | +| `$CNB_EXEC_ENV` | AR | Target execution environment ("production", "test", "development") | | `$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 | @@ -962,6 +962,7 @@ For each process, the buildpack: - The `args` list is a default list of arguments that may be overridden by the user [^command-args]. - MAY specify a `default` boolean that indicates that the process type should be selected as the [buildpack-provided default](https://github.com/buildpacks/spec/blob/main/platform.md#outputs-4) during the export phase. - MAY specify a `working-dir` for the process. The `working-dir` defaults to the application directory if not specified. +- MAY specify an `exec-env` array to restrict the process to specific execution environments. If `exec-env` is not specified, the process applies to all execution environments. [^command-args]: For versions of the Platform API that do not support overridable arguments, the arguments in `command` and `args` are always applied together with any user-provided arguments. In general, the [Platform Interface Specification](platform.md) is ultimately responsible for launching processes; consult that specification for details. @@ -1056,6 +1057,7 @@ For a given layer, the buildpack MAY specify: - Whether the layer is cached, intended for build, and/or intended for launch. - Metadata that describes the layer contents. +- An `exec-env` array in the `[metadata]` section to restrict the layer to specific execution environments. If `exec-env` is not specified, the layer applies to all execution environments. ### buildpack.toml (TOML) This section describes the 'Buildpack descriptor'.