Idea: provide in-container env var interpolation for direct processes

[natalieparellano]

From RFC 0093 (see https://github.com/buildpacks/rfcs/pull/259/files for the full content):

Using Environment Variables in a Process

One upside to our previous execution strategy was that it enable users to include environment variable references in arguments that were later evaluated in the container. To preserve this feature we can instead adopt the Kubernetes strategy for environment variables interpolation. If a buildpack or user includes $(<env>) in the command or args and <env> is the name of an environment variable set in the launch environment, the launcher will replace this string with the value of the environment variable after apply buildpack-provided env modifications and before launching the process.

How it Works

Buildpack-provided process types

Example 1 - A Shell Process

The Paketo .Net Execute Buildpack may generates shell processes similar to the following:

[[processes]]
type = "web"
command = "dotnet my-app.dll --urls http://0.0.0.0:${PORT:-8080}"
direct = false

NOTE: the buildpack API used by this buildpack (0.5) predates the introduction of default.

Using the new API this process could look like:

[[processes]]
type = "web"
command = ["dotnet", "my-app.dll", "--urls", "http://0.0.0.0:$(PORT)"] # the default value of PORT would need to be provided in a layer
default = true

Things to note:

• In the above example I have eliminated the dependency on Bash instead of explicitly adding it to the command, because it is likely unnecessary.
• If the buildpack authors believed that --urls should be overridable they could set move the last two arguments from command to args.

User Provided Processes

Currently if the user can specify a custom process dynamically at runtime by setting the container entrypoint to launcher directly rather than using a symlink to the launcher, the providing a custom cmd. This custom command is executed directly if cmd is an array and the first element is --. Otherwise the custom command is assumed to be a shell process. In the interest of removing complexity we should do away with the special -- argument and execute all custom commands directly.

Example 1 - A Direct process

The follow direct commands:

docker run --entrypoint launcher <image> -- env
docker run --entrypoint launcher <image> -- echo hello '$WORLD' 

will become the following, using the new platform API

docker run --entrypoint launcher <image> env
docker run --entrypoint launcher <image> echo hello '$(WORLD)'

Previously, in the second command in this example, $WORLD would not have been interpolated because this is a direct process; instead the output would include the literal string $WORLD. With the changes proposed, $(WORLD) will now be evaluated, even though the process is direct.

Example 2 - A Shell Process

The follow custom shell command:

docker run --entrypoint launcher <image> echo hello '${WORLD}'
docker run --entrypoint launcher <image> echo hello '${WORLD:-world}'

will become the following, using the new platform API

docker run --entrypoint launcher <image> echo hello '$(WORLD)'
docker run --entrypoint launcher <image> bash -c 'echo hello "${WORLD:-world}"'

The first command in this example needed to adopt the new environment variable syntax to behave as expected with the new API. Previously it was necessary to use a shell process in order to evaluate ${WORLD}. Now, the shell is unnecessary.

If the user wishes, they may explicitly invoke a shell and let Bash handle the interpolation, which provides a richer feature set.

Example 4 - A Script Process in Kubernetes

Because we have adopted the Kubernetes environment variable notation here, users may need to escape some references in their PodSpec in specific situations. This is necessary only if all of the following are true:

• The user is providing a command or args which contain an environment variable reference.
• The variable is explicitly initialized in the env section of the PodSpec.
• The user wishes for the variable to be interpolated after build-provided env modifications have been applied.

apiVersion: v1
kind: Pod
metadata:
  name: env-example
spec:
  containers:
  - name: env-print-demo
    image: bash
    env:
    - name: IN_CONTAINER_1
      value: "k8s-val"
    - name: IN_K8S
      value: "val2"
    command: ["bash", "-c", "echo $$(IN_CONTAINER_1)) $(IN_CONTAINER_2) $(IN_K8S) ${IN_BASH}"]

In the above example the environment variables will be interpolated as follows:

• $IN_CONTAINER - Interpolated by the launcher after buildpack-provided modifications (e.g. k8s-val:buildpack-appended-val)
• $IN_CONTAINER_2 - Interpolated by the launcher after buildpack-provided modifications. No escaping is required here because $IN_CONTAINER_2 is not set in env.
• $IN_K8S - Interpolated by Kubernetes before the container runs. Buildpack-provided modifications will not affect the resulting value.
• $IN_BASH - Interpolated by Bash.