Skip to content

[Buildpack API] - Add Execution Enviroment definition #415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jkutner merged 8 commits into from
Nov 13, 2025
Merged

[Buildpack API] - Add Execution Enviroment definition #415

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
80a272e
Add Execution Enviroment
jjbustamante May 7, 2025
befbc55
fixing formatting issues
jjbustamante May 7, 2025
ffa953f
I've made the requested changes to address the feedback on PR #415. …
jjbustamante May 9, 2025
531f835
1. ✅ Added CNB_EXEC_ENV to the restorer phase
jjbustamante Jun 3, 2025
c5b227d
reverting changes in platform.md, this must be added in the other PR …
jjbustamante Jun 3, 2025
f0d3739
- Removed exec-env from the [[targets]] TOML example
jjbustamante Oct 26, 2025
bf7d6a1
- Added "AR" attribute to CNB_EXEC_ENV in detect and build tables (ma…
jjbustamante Oct 26, 2025
c7071cd
Merge branch 'main' into jjbustamante/0134-execution-env-buildpack
jkutner Nov 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion buildpack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

@natalieparellano natalieparellano May 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this in conflict with this part from the RFC? https://github.com/buildpacks/rfcs/pull/274/files#diff-5e1fecc151d09b271a5fd5407df8a4b069753c4b34b6687f5e1e7c2a29da7f33R71

Namely

An individual element can be any string with * having special meaning. Similar to the "any stack RFC", * will apply to all execution environments. ["*"] will be the default if not specified.

Copy link
Member

@natalieparellano natalieparellano May 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also add

In addition, the / character is reserved in case we need to introduce namespacing in the future.

Copy link
Member

@natalieparellano natalieparellano May 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there's ambiguity around how this should work, I suggest we follow the same pattern as "targets", where missing means "any".

Copy link
Member

@jkutner jkutner May 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yea, i think reserving the / now is a good idea.

i think we agreed in the rfc that default should be production, not *

- `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 `<buildpack API Version>` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle:
- MUST either conform to the matching version of this specification when interfacing with the buildpack or
Expand Down Expand Up @@ -166,6 +186,7 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
| `$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 |
Expand All @@ -187,6 +208,7 @@ Executable: `/bin/build`, Working Dir: `<app[AI]>`
| `$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 |
Expand Down Expand Up @@ -907,6 +929,7 @@ command = ["<command>"]
args = ["<arguments>"]
default = false
working-dir = "<working directory>"
exec-env = ["<execution environment>"] # Optional. If not specified, applies to all execution environments

[[slices]]
paths = ["<app sub-path glob>"]
Expand Down Expand Up @@ -1021,7 +1044,8 @@ name = "<dependency name>"
cache = false

[metadata]
# buildpack-specific data
exec-env = ["<execution environment>"] # Optional. If not specified, applies to all execution environments
Copy link
Member

@natalieparellano natalieparellano May 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to clarify on the platform side - if the previous image was built with a different value of exec-env do we do anything? Looking at the platform PR, it seems not. So do we expect buildpacks to inspect this value and re-create the layer if needed? If so we might want to call this out somewhere.

# other buildpack-specific data
```

For a given layer, the buildpack MAY specify:
Expand Down Expand Up @@ -1059,6 +1083,7 @@ optional = false
os = "<OS name>"
arch = "<architecture>"
variant = "<architecture variant>"
exec-env = ["<execution environment>"] # Optional. If not specified, applies to all execution environments
[[targets.distros]]
name = "<OS distribution name>"
version = "<OS distribution version>"
Expand Down Expand Up @@ -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`)
Expand Down