From 314c19f5d8e2ac01cffcfa9b511e908f506fe93f Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 20 Sep 2023 17:31:04 -0400 Subject: [PATCH] Clarify and expand on implications of upgrading to Platform API 0.10 Signed-off-by: Natalie Arellano --- .../spec/migration/buildpack-api-0.8-0.9.md | 2 +- .../spec/migration/platform-api-0.9-0.10.md | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md b/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md index 1f2a68a2d..59fdded88 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md @@ -22,7 +22,7 @@ Hand-in-hand with shell removal is the introduction of overridable process argum In `launch.toml`, `command` is now a list. The first element in `command` is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The `args` list now designates arguments that can be overridden by the end user - if supported by the platform (Platform API version 0.10 and above). For further details, see the platform [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10). -For older platforms (Platform API version 0.9 and below), arguments in `args` will be appended to arguments in `command`, negating the new functionality (but preserving compatibility). +For older platforms (Platform API version 0.9 and below), arguments in `command` will be prepended to arguments in `args`, negating the new functionality (but preserving compatibility). ### Image extensions are supported (experimental) diff --git a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md index f652b1f57..cacddcd4c 100644 --- a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md +++ b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md @@ -38,6 +38,18 @@ docker run --entrypoint from-newer-buildpack my-image user-1 user-2 will result in the following command invocation: `some-command always-1 always-2 user-1 user-2`. +#### Implications of upgrading + +For processes from newer buildpacks, upgrading the platform (without changing anything else) will change the command invocation for end-users. + +As an example, the following on Platform API version 0.9: + +``` +docker run --entrypoint from-newer-buildpack my-image user-1 user-2 +``` + +will result in the following command invocation: `some-command always-1 always-2 override-1 override-2 user-1 user-2`, where overridable arguments are treated like regular arguments, and user-provided arguments are always appended. Upgrading the platform will cause `override-1` and `override-2` to be dropped, as shown above. + #### Older buildpacks Process types contributed by older buildpacks (Buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml: @@ -51,7 +63,7 @@ args = ["always-1", "always-2"] The `command` list will never have more than one element. `always-1` and `always-2` are arguments that are always provided to `some-command`. If no user-provided arguments are specified when the application image is launched, `always-1` and `always-2` will be provided only. If user-provided arguments are specified, these will be **appended** to the `args` list. Example: ``` -docker run --entrypoint from-newer-buildpack my-image +docker run --entrypoint from-older-buildpack my-image ``` will result in the following command invocation: `some-command always-1 always-2`. However: @@ -62,6 +74,10 @@ docker run --entrypoint from-older-buildpack my-image user-1 user-2 will result in the following command invocation: `some-command always-1 always-2 user-1 user-2`. +#### Implications of upgrading + +For processes from older buildpacks, upgrading the platform will not change the command invocation. + ### Image extensions are supported (experimental) Platform 0.10 introduces image extensions as experimental components for customizing build and run-time base images (see [here](/docs/features/dockerfiles) for more information). Image extensions output Dockerfiles which are applied by the lifecycle using [kaniko][https://github.com/GoogleContainerTools/kaniko], a tool for building container images in Kubernetes, as a library.