Skip to content

Commit

Permalink
adds more reviewers feedback
Browse files Browse the repository at this point in the history 
Signed-off-by: Hanan Younes <hanan.algazaley@gmail.com>
  • Loading branch information
@hyounes4560
hyounes4560 committed Aug 22, 2024
1 parent ab0b470 commit ad029b0
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 51 deletions.
6 changes: 3 additions & 3 deletions content/docs/for-buildpack-authors/how-to/write-buildpacks/clear-env.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ weight=99

<!--more-->

Buildpack authors may elect to clear user-defined environment variables when `bin/detect` and `bin/build` are executed. This is achieved by setting `clear-env` to `true` in [buildpack.toml](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpacktoml-toml); by default `clear-env` is set to `false`.
Buildpack authors may elect to clear user-provided environment variables when `bin/detect` and `bin/build` are executed. This is achieved by setting `clear-env` to `true` in [buildpack.toml](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpacktoml-toml); by default `clear-env` is set to `false`.

* When `clear-env` is set to `true` for a given buildpack, the `lifecycle` will not set user-provided environment variables when running `/bin/detect` or `/bin/build` for the given buildpack.
* If a buildpack does allow customization by the end-user through the environment (`clear-env` is `false`), there is a special convention for naming the available environment variables, shown in the following table:
* When `clear-env` is set to `true` for a given buildpack, the `lifecycle` will not set user-provided environment variables when running `/bin/detect` or `/bin/build`.
* If a buildpack does allow customization by the end-user through the environment (`clear-env` is `false`), there is a special convention for naming the environment variables recognized by the buildpack, shown in the following table:

| Env Variable | Description | Detect | Build | Launch |
|------------------------|---------------------------------------------------|--------|-------|--------|
Expand Down
62 changes: 14 additions & 48 deletions content/docs/for-buildpack-authors/how-to/write-buildpacks/specify-env.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ Environment variables are a common way to configure buildpacks at build-time and

### Preparing the environment at build time

When the `lifecycle` runs each buildpack, it first tears down any environment variables defined on the `build-time` base image of the environment. It only allows a [specific set](https://github.com/buildpacks/lifecycle/blob/a43d5993a4f2cc23c44b6480ba2ab09fe81d57ed/env/build.go#L9-L19) of pre-configured environment variables through.
When the `lifecycle` runs each buildpack, it first tears down any environment variables defined on the `build-time` base image. It only allows a [specific set](https://github.com/buildpacks/lifecycle/blob/a43d5993a4f2cc23c44b6480ba2ab09fe81d57ed/env/build.go#L9-L19) of pre-configured environment variables through.

For the detect phase, the lifecycle then applies user-provided environment variables. For more information, see [clearing the buildpack environment](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/clear-env/)
For the `detect` phase, the `lifecycle` then applies user-provided environment variables, followed by platform-provided environment variables. For more information, see the page for how to [customize buildpack behavior with build-time environment variables](https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/).

For the `build` phase, the process is more complex. Before applying user-provided environment variables, the `lifecycle` applies buildpack-provided environment variables, which is anything that a previous buildpack (a buildpack that ran earlier in the `build` phase) might have configured in its `layers` directory.

Expand Down Expand Up @@ -54,8 +54,7 @@ The full list of convenience directories is summarized in the table below:
| `CPATH` | `/include` | header files | [x] | |
| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | [x] | |

* If `env/SOME_VAR` and `env.build/SOME_VAR` have a conflict, a given procedure applies to figure out who "wins" when applying the environment [modification rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules).
* `User-defined` variables are then applied; meaning it's possible to override `buildpack-defined` variables.
* User-provided variables are then applied, meaning that it's possible for the end-user to override buildpack-provided variables.
* Finally, `platform-defined` variables are applied, which eventually override any previous values.

### Preparing the environment at runtime
Expand All @@ -75,40 +74,17 @@ launch = true

When multiple buildpacks define the same variable, the ["environment modification rules"](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) come into play.

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.
Let's say buildpack A (which runs first) defines `SOME_VAR=foo` and buildpack B defines `SOME_VAR=bar`. The `lifecycle` can perform different modifications when setting up the environment for buildpack C (which runs last).

For each environment variable file the period-delimited suffix SHALL determine the modification behavior as follows.
* The `lifecycle` can `append` the second value to the first, so that buildpack C sees something like `SOME_VAR=foo:bar`.
* The `lifecycle can` `prepend` the second value to the first, so that buildpack C sees something like `SOME_VAR=bar:foo`.
* The `lifecycle` can `override` the first value with the second value, so that buildpack C sees `SOME_VAR=bar`.
* The `lifecycle` can treat the second value as a `default` (the value to set when no other entity defines this variable), so that buildpack C sees `SOME_VAR=foo`.
* In all cases, the behavior of the `lifecycle` is governed by the file suffix for `<layers>/<layer>/<env>/SOME_VAR<.suffix>`. The suffix is optional, and the assumed behavior when no suffix is provided is `override`.

| Suffix | Modification Behavior |
|------------|-------------------------------------------|
| none | [Override](#override) |
| `.append` | [Append](#append) |
| `.default` | [Default](#default) |
| `.delim` | [Delimiter](#delimiter) |
| `.override`| [Override](#override) |
| `.prepend` | [Prepend](#prepend) |
>Note that whenever the suffix is `append` or `prepend` an additional file, `<layers>/<layer>/<env>/SOME_VAR.delim`, is needed to specify the delimiter used during concatenation. If no delimiter is provided, none will be used.
#### Append

The value of the environment variable MUST be a concatenation of the file contents and the contents of other files representing that environment variable.

#### Default

The value of the environment variable MUST only be the file contents if the environment variable is empty.

#### Delimiter

The file contents MUST be used to delimit any concatenation within the same layer involving that environment variable.

#### Override

The value of the environment variable MUST be the file contents.

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

To better understand the above modification rules, let's take a look at the tree below,
To better understand the above modification rules, let's take a look at the tree below:

```text
Expand All @@ -128,18 +104,8 @@ layers/
```

Assuming that `some-buildpack-id` comes before `some-other-buildpack-id` in the buildpack group, the final value of `SOME_VAR` shown above would be `foo:bar`

>For more information on modifying environment variables, see [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) specification.
Please note that when `clear-env` is not set to `true`, the `lifecycle` MUST set user-provided environment variables in the environment of `/bin/detect` or `/bin/build` such that:

* For layer path environment variables, user-provided values are prepended before any existing values and are delimited by the OS path list separator.
* For all other environment variables, user-provided values override any existing values.
* The environment variable prefix `CNB_` is reserved. It MUST NOT be used for environment variables that are not defined in this specification or approved extensions.

>For more information on clearing user-defined environment variables, see [Clear the buildpack environment](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/clear-env/) documentation.
Assuming that `some-buildpack-id` comes before `some-other-buildpack-id` in the buildpack group, the final value of `SOME_VAR` shown above would be `foo:bar`.

### Further reading
Note that the examples shown on this page are relatively simple. It is possible for a buildpack to double-specify the same variable (i.e., within two or more different layers), and for a buildpack to specify a variable for a particular phase (build or launch) when the layer has type both `build = true` and `launch = true`. In these cases, the lifecycle determines the final value of the variable according to a process outlined in the specification.

For more about environment variables, see the [customize buildpack behavior with build-time environment variables](https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/) documentation and the [Environment](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment) specification.
>For more information on modifying environment variables, see the [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) section of the specification.

0 comments on commit ad029b0

Please sign in to comment.