From 5b8e1268f1ab3981eda3ebd1e86b1d92ff84212b Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Wed, 15 Apr 2026 18:57:09 +0530 Subject: [PATCH 1/8] Create 0316-launcher-decoupling Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling | 73 +++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 text/0316-launcher-decoupling diff --git a/text/0316-launcher-decoupling b/text/0316-launcher-decoupling new file mode 100644 index 000000000..dd142c724 --- /dev/null +++ b/text/0316-launcher-decoupling @@ -0,0 +1,73 @@ +# Meta +[meta]: #meta +- Name: Launcher in Run Image +- Start Date: 2026-04-15 +- Author(s): Hemant28codes +- Status: Draft +- RFC Pull Request: (leave blank) +- CNB Pull Request: (leave blank) +- CNB Issue: (leave blank) +- Supersedes: N/A + +# Summary +[summary]: #summary + +This RFC proposes a mechanism to allow the launcher binary to be provided by the run image instead of being unconditionally injected by the lifecycle's exporter phase. By introducing a specific flag, the exporter can be instructed to skip the creation of the launcher binary layer, relying instead on a pre-existing binary or symlink at the designated path in the run image. + +# Definitions +[definitions]: #definitions + +- Launcher: The binary that acts as the container entrypoint, responsible for setting up the environment and executing the application process. +- Exporter: The lifecycle phase responsible for creating the final application image, which currently adds a launcher layer unconditionally. +- Run Image: The base image used for the final application container. +- CNB_LAUNCHER_PATH: The path where the platform expects the launcher to reside (e.g., /cnb/lifecycle/launcher). + +# Motivation +[motivation]: #motivation + +The current exporter implementation unconditionally creates a fresh file-based layer to include the launcher binary, which overwrites any existing files or symlinks at that path in the run image. This prevents platforms from providing a customized launcher directly within their base images, which is necessary for certain environments or security configurations. + +# What it is +[what-it-is]: #what-it-is + +This feature allows a platform to signal that the run image already contains a valid launcher. + +- Target Persona: Platform implementors and operators. +- Example: A platform builds a run image with a symlink at /cnb/lifecycle/launcher pointing to a platform-specific binary. During the export phase, the platform passes a flag to skip the launcher installation, preserving the existing symlink. + +# How it Works +[how-it-works]: #how-it-works + +A new flag (e.g., --launcher-in-run-image) will be added to the exporter phase. + +When the flag is set, the exporter MUST skip the launcher binary layer but MUST still export the configuration and process-types layers. +The platform asserts that the run image contains a valid launcher at the location defined by CNB_LAUNCHER_PATH. + +# Migration +[migration]: #migration + +This change requires a Platform API spec update, as the current spec mandates that the exporter install the launcher. + +- Platform Developers: Will need to update their implementations to support and pass the new flag when appropriate. +- Compatibility: Since this is an opt-in flag, existing platforms and images will continue to function as they do today by default. + +# Drawbacks +[drawbacks]: #drawbacks + +- Validation Risk: If the flag is set but the run image does not actually contain a valid launcher, the resulting application image will fail at runtime. +- Complexity: Adds a conditional path to the exporter's image construction logic. + +# Unresolved Questions +[unresolved-questions]: #unresolved-questions + +- Should the exporter perform a check to verify the existence of the launcher at CNB_LAUNCHER_PATH before completing the export? +- What should the exact naming of the flag be to ensure clarity across different platform implementations? + +# Spec. Changes (OPTIONAL) +[spec-changes]: #spec-changes +The Platform API specification must be updated to include the new flag and define the behavior where the launcher binary layer is skipped if the platform asserts its presence in the run image. + +# History +[history]: #history + +- 2026-04-15: Initial draft proposed by Hemant Goyal based on community discussion. From ed8dbeb4a2c706197780abb987e8b225bf565341 Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Wed, 15 Apr 2026 19:26:48 +0530 Subject: [PATCH 2/8] Update 0316-launcher-decoupling Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/text/0316-launcher-decoupling b/text/0316-launcher-decoupling index dd142c724..463fbd19e 100644 --- a/text/0316-launcher-decoupling +++ b/text/0316-launcher-decoupling @@ -25,7 +25,13 @@ This RFC proposes a mechanism to allow the launcher binary to be provided by the # Motivation [motivation]: #motivation -The current exporter implementation unconditionally creates a fresh file-based layer to include the launcher binary, which overwrites any existing files or symlinks at that path in the run image. This prevents platforms from providing a customized launcher directly within their base images, which is necessary for certain environments or security configurations. +Why should we do this? Currently, the exporter phase replaces any existing file or symlink at the launcher path with a new file-based layer, preventing platforms from providing their own launcher in the base image. + +What use cases does it support? +- Security Patching via Rebase: This is a critical driver for the proposal. By making the launcher part of the run image, platforms can update the launcher to patch vulnerabilities (e.g., Go CVEs reported by security scanners in the binary) simply by updating the run image and performing a rebase. This eliminates the need to trigger a full build for thousands of applications just to update a shared launcher binary. +- Customized Launchers: Platforms that require specialized or environment-specific launcher logic can bake it directly into their base image infrastructure. + +What is the expected outcome? Platforms can opt-out of the automatic launcher installation, ensuring that the launcher binary is managed as a run-time dependency that can be updated independently of the application build lifecycle. # What it is [what-it-is]: #what-it-is From 35a8fe77380ed87847de3b31b9c74ca04275987c Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Wed, 15 Apr 2026 22:21:25 +0530 Subject: [PATCH 3/8] Update 0316-launcher-decoupling Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/text/0316-launcher-decoupling b/text/0316-launcher-decoupling index 463fbd19e..ad15c9fda 100644 --- a/text/0316-launcher-decoupling +++ b/text/0316-launcher-decoupling @@ -41,6 +41,7 @@ This feature allows a platform to signal that the run image already contains a v - Target Persona: Platform implementors and operators. - Example: A platform builds a run image with a symlink at /cnb/lifecycle/launcher pointing to a platform-specific binary. During the export phase, the platform passes a flag to skip the launcher installation, preserving the existing symlink. + # How it Works [how-it-works]: #how-it-works @@ -49,6 +50,14 @@ A new flag (e.g., --launcher-in-run-image) will be added to the exporter phase. When the flag is set, the exporter MUST skip the launcher binary layer but MUST still export the configuration and process-types layers. The platform asserts that the run image contains a valid launcher at the location defined by CNB_LAUNCHER_PATH. +Just to give you an idea of what our usecase is: + +- Current Setup +Source code + Builder(contains lifecycle) -----(Build)----> Application image(contains launcher from lifecycle in builder + run image) + +- Proposed Setup +Source code + Builder(contains lifecycle) -----(Build)----> Application image(contains run image), Run image -> will have launcher installed + # Migration [migration]: #migration From 92011ca2856c34160400dc8869b3fb8d441451e3 Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Mon, 20 Apr 2026 21:54:31 +0530 Subject: [PATCH 4/8] Update 0316-launcher-decoupling Updated the detailed working section for this. Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/text/0316-launcher-decoupling b/text/0316-launcher-decoupling index ad15c9fda..7361c25ce 100644 --- a/text/0316-launcher-decoupling +++ b/text/0316-launcher-decoupling @@ -12,8 +12,14 @@ # Summary [summary]: #summary -This RFC proposes a mechanism to allow the launcher binary to be provided by the run image instead of being unconditionally injected by the lifecycle's exporter phase. By introducing a specific flag, the exporter can be instructed to skip the creation of the launcher binary layer, relying instead on a pre-existing binary or symlink at the designated path in the run image. - +RFC: Launcher in Run Image + +Name Launcher in Run Image +Start Date 2026-04-15 +Author(s) Hemant28codes +Status Draft +Summary +This RFC proposes a mechanism to allow the launcher binary to be provided by the run image instead of being unconditionally injected by the lifecycle's exporter phase. By introducing a specific flag, the exporter can be instructed to replace the standard launcher binary with a symlink in the "Buildpacks Application Launcher" layer, pointing to a path in the run image. This ensures that the application image structure remains consistent while decoupling the launcher's lifecycle from the application build. # Definitions [definitions]: #definitions @@ -47,10 +53,29 @@ This feature allows a platform to signal that the run image already contains a v A new flag (e.g., --launcher-in-run-image) will be added to the exporter phase. -When the flag is set, the exporter MUST skip the launcher binary layer but MUST still export the configuration and process-types layers. -The platform asserts that the run image contains a valid launcher at the location defined by CNB_LAUNCHER_PATH. +### Layer Preservation +The "Buildpacks Application Launcher" layer must always be present in the application image to maintain OCI artifact compatibility. The difference lies in whether this layer contains the binary itself or a symlink. + +| Feature | Before (Current) | After (Proposed) | +| :--- | :--- | :--- | +| **Launcher Path** | `/cnb/lifecycle/launcher` | `/cnb/lifecycle/launcher` | +| **Content Type** | Self-contained executable (~2.8 MB) | Symlink to run image path | +| **Dependency** | None (Independent layer) | Explicit dependency on Run Image layer | + +### Rebaser Responsibilities +With symlink-based launchers, the rebaser gains a new validation duty. It must verify that the target run image actually contains a valid launcher binary at the expected path. Failure to do so would result in a broken application at runtime. + +#### Metadata Changes +The `io.buildpacks.lifecycle.metadata` label will be updated to include: +* `launcher.type`: "binary" or "symlink" +* `launcher.target`: The absolute path in the run image (only if type is symlink). + +#### Run Image Advertising +Run images that provide a launcher should advertise this capability via a label: +`io.buildpacks.run.launcher.path=/usr/local/bin/launcher` + -Just to give you an idea of what our usecase is: +Just to give an idea of what our usecase is: - Current Setup Source code + Builder(contains lifecycle) -----(Build)----> Application image(contains launcher from lifecycle in builder + run image) From 81c7caa010fc52f282e54f6db38f3996c8abd061 Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:42:19 +0530 Subject: [PATCH 5/8] Rename 0316-launcher-decoupling to 0316-launcher-decoupling.md Updated RFC name Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/{0316-launcher-decoupling => 0316-launcher-decoupling.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0316-launcher-decoupling => 0316-launcher-decoupling.md} (100%) diff --git a/text/0316-launcher-decoupling b/text/0316-launcher-decoupling.md similarity index 100% rename from text/0316-launcher-decoupling rename to text/0316-launcher-decoupling.md From 2a89738dc91e5f6467c397359e57667d29ea573e Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:43:44 +0530 Subject: [PATCH 6/8] Update 0316-launcher-decoupling.md Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/text/0316-launcher-decoupling.md b/text/0316-launcher-decoupling.md index 7361c25ce..be586487d 100644 --- a/text/0316-launcher-decoupling.md +++ b/text/0316-launcher-decoupling.md @@ -14,11 +14,6 @@ RFC: Launcher in Run Image -Name Launcher in Run Image -Start Date 2026-04-15 -Author(s) Hemant28codes -Status Draft -Summary This RFC proposes a mechanism to allow the launcher binary to be provided by the run image instead of being unconditionally injected by the lifecycle's exporter phase. By introducing a specific flag, the exporter can be instructed to replace the standard launcher binary with a symlink in the "Buildpacks Application Launcher" layer, pointing to a path in the run image. This ensures that the application image structure remains consistent while decoupling the launcher's lifecycle from the application build. # Definitions [definitions]: #definitions From 149864ed024dad43e9cfb35c09199ab309bc1a3c Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:45:48 +0530 Subject: [PATCH 7/8] Update 0316-launcher-decoupling.md Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0316-launcher-decoupling.md b/text/0316-launcher-decoupling.md index be586487d..8bad57cd4 100644 --- a/text/0316-launcher-decoupling.md +++ b/text/0316-launcher-decoupling.md @@ -106,3 +106,4 @@ The Platform API specification must be updated to include the new flag and defin [history]: #history - 2026-04-15: Initial draft proposed by Hemant Goyal based on community discussion. +- 2026-04-20: Updated based on RFC discussions. From 446a230a591bc3269a67d3df0484aa7bcdbaeedd Mon Sep 17 00:00:00 2001 From: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> Date: Tue, 21 Apr 2026 16:03:45 +0530 Subject: [PATCH 8/8] Update 0316-launcher-decoupling.md Signed-off-by: Hemant Goyal <87599584+Hemant28codes@users.noreply.github.com> --- text/0316-launcher-decoupling.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0316-launcher-decoupling.md b/text/0316-launcher-decoupling.md index 8bad57cd4..bfde396a7 100644 --- a/text/0316-launcher-decoupling.md +++ b/text/0316-launcher-decoupling.md @@ -97,6 +97,8 @@ This change requires a Platform API spec update, as the current spec mandates th - Should the exporter perform a check to verify the existence of the launcher at CNB_LAUNCHER_PATH before completing the export? - What should the exact naming of the flag be to ensure clarity across different platform implementations? +- Can we have a custom launcher or do we need to depend on the launcher provided by buildpacks, or maybe add on top of the buildpacks launcher? +- Will the launcher going to be a seperate binary which doesn't depend on spec - buildpack API, platform API, lifecycle version, libcnb version and will be decoupled from these? # Spec. Changes (OPTIONAL) [spec-changes]: #spec-changes