From bfbdfeb408288bfea6488b9fb82c66801e523be6 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Thu, 27 Aug 2020 17:22:01 -0400 Subject: [PATCH 1/4] Changes default env var behavior to override Signed-off-by: Emily Casey --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 73f53727..cd23a22e 100644 --- a/buildpack.md +++ b/buildpack.md @@ -697,7 +697,6 @@ If multiple operations apply to the same environment variable, all operations fo ##### Prepend -If the environment variable file name has no period-delimited suffix, then the value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable delimited by the OS path list separator. If the environment variable file name ends in `.prepend`, then the value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable. In either case, within that environment variable value, - Later buildpacks' environment variable file contents MUST precede earlier buildpacks' environment variable file contents. @@ -714,6 +713,7 @@ Within that environment variable value, ##### Override +If the environment variable file name has no period-delimited suffix, then the value of the environment variable MUST be the file contents. If the environment variable file name ends in `.override`, then the value of the environment variable MUST be the file contents. For that environment variable value, - Later buildpacks' environment variable file contents MUST override earlier buildpacks' environment variable file contents. From dc25c479dba8425706041a39bf6a0526eed5eed3 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Fri, 28 Aug 2020 12:23:48 -0400 Subject: [PATCH 2/4] Move env file suffix -> type mapping into a tabel * Alphatbetize modification types * Improves readability/navigation Signed-off-by: Emily Casey --- buildpack.md | 58 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 24 deletions(-) diff --git a/buildpack.md b/buildpack.md index cd23a22e..06053528 100644 --- a/buildpack.md +++ b/buildpack.md @@ -55,11 +55,11 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th - [Provided by the Platform](#provided-by-the-platform) - [Provided by the Buildpacks](#provided-by-the-buildpacks) - [Environment Variable Modification Rules](#environment-variable-modification-rules) - - [Delimiter](#delimiter) - - [Prepend](#prepend) - [Append](#append) - - [Override](#override) - [Default](#default) + - [Delimiter](#delimiter) + - [Override](#override) + - [Prepend](#prepend) - [Security Considerations](#security-considerations) - [Assumptions of Trust](#assumptions-of-trust) - [Requirements](#requirements) @@ -689,44 +689,54 @@ For each file written to `//env.launch/` by `/bin/build`, the lif The lifecycle MUST consider the name of the environment variable to be the name of the file up to the first period (`.`) or to the end of the name if no periods are present. In all cases, file contents MUST NOT be evaluated by a shell or otherwise modified before inclusion in environment variable values. -##### Delimiter +For each environment variable file the period-delimited suffix SHALL determine the modification behavior as follows. -If the environment variable file name ends in `.delim`, then the file contents MUST be used to delimit any concatenation within the same layer involving that environment variable. -This delimiter MUST override the delimiters below. -If multiple operations apply to the same environment variable, all operations for a given layer containing environment variable files MUST be applied before subsequent layers are considered. - -##### Prepend - -If the environment variable file name ends in `.prepend`, then the value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable. -In either case, within that environment variable value, -- Later buildpacks' environment variable file contents MUST precede earlier buildpacks' environment variable file contents. -- Environment variable file contents originating from the same buildpack MUST be sorted alphabetically descending by associated layer name. -- **Environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env.launch//` precede file contents in `//env.launch/` or `//env.build/`, which must precede `//env/`.** +| Suffix | Modification Behavior +|------------|------------------------------------------- +| none | [Override](#override) +| `.append` | [Append](#append) +| `.default` | [Default](#default) +| `.delim` | [Delimeter](#delimiter) +| `.override`| [Override](#override) +| `.prepend` | [Prepend](#prepend) ##### Append -If the environment variable file name ends in `.append`, then the value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable. +The value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable. Within that environment variable value, - Earlier buildpacks' environment variable file contents MUST precede later buildpacks' environment variable file contents. - Environment variable file contents originating from the same buildpack MUST be sorted alphabetically ascending by associated layer name. - **Environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env/` precede file contents in `//env.build/` or `//env.launch/` which must precede file contents in `//env.launch//`.** +##### Default + +The value of the environment variable MUST only be the file contents if the environment variable is empty. +For that environment variable value, +- Earlier buildpacks' environment default variable file contents MUST override later buildpacks' environment variable file contents. +- For default environment variable file contents originating from the same buildpack, file contents that are earlier (when sorted alphabetically ascending by associated layer name) MUST override file contents that are later. +- **Default environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env/` override file contents in `//env.build/` or `//env.launch/` which override file contents in `//env.launch//`.** + +##### Delimiter + +The file contents MUST be used to delimit any concatenation within the same layer involving that environment variable. +This delimiter MUST override the delimiters below. +If multiple operations apply to the same environment variable, all operations for a given layer containing environment variable files MUST be applied before subsequent layers are considered. + ##### Override -If the environment variable file name has no period-delimited suffix, then the value of the environment variable MUST be the file contents. -If the environment variable file name ends in `.override`, then the value of the environment variable MUST be the file contents. +The environment variable MUST be the file contents. For that environment variable value, - Later buildpacks' environment variable file contents MUST override earlier buildpacks' environment variable file contents. - For environment variable file contents originating from the same buildpack, file contents that are later (when sorted alphabetically ascending by associated layer name) MUST override file contents that are earlier. - **Environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env.launch//` override file contents in `//env.build/` or `//env.launch/` which override file contents in `//env/`.** -##### Default +##### Prepend -If the environment variable file name ends in `.default`, then the value of the environment variable MUST only be the file contents if the environment variable is empty. -For that environment variable value, -- Earlier buildpacks' environment default variable file contents MUST override later buildpacks' environment variable file contents. -- For default environment variable file contents originating from the same buildpack, file contents that are earlier (when sorted alphabetically ascending by associated layer name) MUST override file contents that are later. -- **Default environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env/` override file contents in `//env.build/` or `//env.launch/` which override file contents in `//env.launch//`.** +The value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable. +In either case, within that environment variable value, +- Later buildpacks' environment variable file contents MUST precede earlier buildpacks' environment variable file contents. +- Environment variable file contents originating from the same buildpack MUST be sorted alphabetically descending by associated layer name. +- **Environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env.launch//` precede file contents in `//env.launch/` or `//env.build/`, which must precede `//env/`.** ## Security Considerations From ed92d429f7d6cd78122cb4eb6a3490b6552ddfde Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Tue, 8 Sep 2020 12:35:42 -0400 Subject: [PATCH 3/4] Update buildpack.md Signed-off-by: Emily Casey Co-authored-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 06053528..2578adac 100644 --- a/buildpack.md +++ b/buildpack.md @@ -724,7 +724,7 @@ If multiple operations apply to the same environment variable, all operations fo ##### Override -The environment variable MUST be the file contents. +The value of the environment variable MUST be the file contents. For that environment variable value, - Later buildpacks' environment variable file contents MUST override earlier buildpacks' environment variable file contents. - For environment variable file contents originating from the same buildpack, file contents that are later (when sorted alphabetically ascending by associated layer name) MUST override file contents that are earlier. From 1ac3fd7b96d41fb18bfbf238b9b29b2abe82fd9f Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Tue, 8 Sep 2020 12:40:51 -0400 Subject: [PATCH 4/4] Fix grammar Signed-off-by: Emily Casey --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 2578adac..55cd9e5e 100644 --- a/buildpack.md +++ b/buildpack.md @@ -733,7 +733,7 @@ For that environment variable value, ##### Prepend The value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable. -In either case, within that environment variable value, +Within that environment variable value, - Later buildpacks' environment variable file contents MUST precede earlier buildpacks' environment variable file contents. - Environment variable file contents originating from the same buildpack MUST be sorted alphabetically descending by associated layer name. - **Environment variable file contents originating in the same layer MUST be sorted such that file contents in `//env.launch//` precede file contents in `//env.launch/` or `//env.build/`, which must precede `//env/`.**