This guide is most relevant to platform operators.

See the spec release for Platform API 0.10 for the full list of changes and further details.

Platform Operator

The launcher supports overridable process arguments

The way user-provided arguments are handled by the launcher depends on the Buildpack API of the buildpack that created the process definition.

Newer buildpacks

Process types contributed by newer buildpacks (Buildpack API 0.9 and above) may have overridable process arguments. Looking at metadata.toml:

[[processes]]
type = "from-newer-buildpack"
command = ["some-command", "always-1", "always-2"]
args = ["override-1", "override-2"]

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, override-1 and override-2 will also be provided. If user-provided arguments are specified, these will be provided instead of override-1 and override-2. Example:

docker run --entrypoint from-newer-buildpack my-image

will result in the following command invocation: some-command always-1 always-2 override-1 override-2. However:

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:

[[processes]]
type = "from-older-buildpack"
command = ["some-command"]
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-older-buildpack my-image

will result in the following command invocation: some-command always-1 always-2. However:

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 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.

Note: image extensions are not supported for Windows container images.

• To create a builder with extensions, ensure the pack version in use is at least 0.28.0 and enable experimental features: pack config experimental.
• Enable experimental features in the lifecycle by setting CNB_EXPERIMENTAL_MODE=warn or CNB_EXPERIMENTAL_MODE=silent in the lifecycle execution environment for ALL lifecycle phases
• Invoke analyzer as usual
• Invoke detector with a new optional flag: -generated, to specify the directory where Dockerfiles generated by image extensions will be output (defaults to <layers>/generated) and include image extensions in order.toml
  • Dockerfiles for customizing the build image can be found in <generated>/build/<image extension ID>/Dockerfile
  • Dockerfiles for customizing the run image can be found in <generated>/run/<image extension ID>/Dockerfile
    • The new run image will be written to analyzed.toml
• Invoke restorer with a new required flag (when using extensions): -build-image, a tag reference to the builder image in use
  • A new volume mount is introduced with target /kaniko; this volume must be writable by the restorer user
• Invoke extender (new lifecycle binary), instead of builder; the extender will use kaniko to apply the relevant generated Dockerfiles to the build image and then drop privileges to run the build phase
  • The same volume from restore should be mounted at /kaniko
  • The extender user should have sufficient permissions to execute all RUN instructions in each Dockerfile - typically, it should run as root
  • Consult the platform specification for the full list of configuration options for the extender
• Invoke exporter as usual
  • If Dockerfiles for customizing the run image were output by extensions, the exporter will use the run image designated by the extension process

Extensions workflows are not currently supported when using the creator binary, though support may be added in the future.

---