Documenting known issue: `failed to get platform API version`

[natalieparellano]

Summary

In lifecycle 0.17.x and earlier, it is possible to run CNB-built images with the following command:

docker run –entrypoint /cnb/lifecycle/launcher <image> /cnb/lifecycle/launcher (note that /cnb/lifecycle/launcher - or a symlink to it - is the default entrypoint, and is only included here for completeness)

In lifecycle 0.18.x and later, the above command will result in:

failed to get platform API version; please set 'CNB_PLATFORM_API' to specify the desired platform API version

Worth noting, this isn’t a recommended workflow in the CNB specification. We tell end-users to override the entrypoint with a symlink to the launcher in order to specify the process type, e.g., docker run –entrypoint /cnb/process/web <image> process-arg1 process-arg2.

---

Context

lifecycle version

What changed: CNB_PLATFORM_API was made required in lifecycle 0.18.x to avoid surprising users when we removed support for old APIs as Platform API 0.3 (the oldest version, now removed) was the former default.

CNB_PLATFORM_API is always set (in the image config) on CNB-built images; however the first launcher (–entrypoint /cnb/lifecycle/launcher) strips this variable from the environment when invoking the second launcher, so the second launcher does not see it.

Impact

See see here, here, and here for instances where this change has caused confusion

Why would anyone call the launcher with the launcher? There are a few reasons:

• They perhaps don’t know that /cnb/lifecycle/launcher is already the default entrypoint
• They can’t override the entrypoint (e.g., aws ecs run_task doesn’t allow it)
• They are trying to inject custom logic before starting the application

There are a few workarounds:

• Don’t do this, it isn’t necessary
• Call the second launcher as a script and explicitly pass the CNB_PLATFORM_API environment variable: docker run --entrypoint /cnb/lifecycle/launcher <image> 'CNB_PLATFORM_API=0.12 /cnb/lifecycle/launcher'
• Write a custom buildpack that encodes custom logic as an exec.d executable that the launcher will run before the application starts up (requires extra work at build time)