From da8b4ff6ac9a683e5518c6c727a2cae6a5c2c64d Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Tue, 18 Jun 2024 21:43:18 -0400 Subject: [PATCH 1/3] updates the exec.d docs Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/use-exec.d.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d.md index 6f6781c75..c09322391 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d.md @@ -7,22 +7,24 @@ weight=99 The [buildpacks `exec.d` interface](https://github.com/buildpacks/spec/blob/main/buildpack.md#execd) allows buildpack authors to execute custom scripts or binaries when the application image is started. This interface can be particularly useful for injecting dynamic behavior or environment variables into the runtime environment of an application. -## Key Points: +## Key Points - 1. Location and Naming: Scripts are placed in the `/exec.d/` directory within a launch layer and must be executable. They can have any name. +1. Location and Naming: Scripts are placed in the `/exec.d/` directory within a launch layer and must be executable. They can have any name. - 2. Script Behavior: +2. Script Behavior: * **Inputs** - * A third open file descriptor (in addition to stdout and stderr). The third open file descriptor is inherited from the calling process. + *A third open file descriptor. File descriptors are integers used by a process to uniquely identify opened files; pre-opened file descriptors are usually 0 for stdin, 1 for stdout and 2 for stderr. The third open file descriptor is inherited from the calling process. * **Outputs** * Valid TOML describing environment variables in the form of key=value pairs. These variables are added to the application's runtime environment. The content should be written to file descriptor 3 (see examples for how to do this). * Exit Code: The scripts should exit with a status code of `0` to indicate success. A non-zero exit code will indicate an error and prevent the application from launching. -## Use Cases: +## Use Cases + * Dynamic Configuration: Inject configuration values that are determined at runtime. * Service Bindings: Configure environment variables based on bound services. -## Implementation Steps: +## Implementation Steps + * Write Scripts: Create executable scripts within the `/exec.d/` directory. * Set Permissions: Ensure scripts have the appropriate execute permissions (chmod +x). * Environment Variables: Use scripts to print `key="value"` pairs to the third open file descriptor. @@ -32,6 +34,7 @@ The [buildpacks `exec.d` interface](https://github.com/buildpacks/spec/blob/main `exec.d` executables can be written in any language. We provide examples in bash, Go and Python that inject the `EXAMPLE="test"` into the runtime environment. It is important that environment variables are written to the third file descriptor which is inherited by the `exec.d` binary. A `bash` example looks as follows: + ```bash #!/bin/bash @@ -43,6 +46,7 @@ echo "EXAMPLE=\"test\"" >&$FD ``` And a `Go` example is: + ```Go package main @@ -66,7 +70,9 @@ func main() { } } ``` + Finally, we provide a short Python example: + ```Python import os import sys @@ -82,4 +88,4 @@ if __name__ == "__main__": main() ``` -The `exec.d` interface provides a powerful mechanism for dynamically configuring runtime environments in a flexible and programmable manner, enhancing the customization capabilities available to application programmers using buildpacks. \ No newline at end of file +The `exec.d` interface provides a powerful mechanism for dynamically configuring runtime environments in a flexible and programmable manner, enhancing the customization capabilities available to application programmers using buildpacks. From 77199f0b16ad6e2bc1c0efd992618bbdce35f966 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 19 Jun 2024 01:18:06 -0400 Subject: [PATCH 2/3] adds image labels info Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/add-labels.md | 54 ++++++++++++++++++- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md index 3d9d75ebc..dcaf9f4c3 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md @@ -5,6 +5,56 @@ weight=99 -This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon. +Labels are key-value pairs, stored as strings, that are attached to an image (i.e., arbitrary metadata). Labels are used to add helpful descriptions or attributes to an application image, which are meaningful to users. -If you are familiar with this content and would like to make a contribution, please feel free to open a PR :) +Labels are usually added at the time an image is created and can also be modified at a later time. Images can have multiple labels; however, each key must be unique. + +## Key Points + +A `LABEL` + +* MUST specify a unique key for a given image +* MUST specify a value to be set in the image label +* MUST be added as an image label on the created image metadata +* If one key is given multiple values, the last value overwrites + +## Use Cases + +Since adding labels to application images is optional and not needed to run containers, this property is often overlooked. The following are few reasons to why labels should be widely adopted + +* Documenting versioning +* Record licensing information +* Including information about a project maintainer +* Including a description of the image and additional metadata related to the image +* Labels can also be used to organize images + +## Implementation Steps + +* General syntax of `LABEL` instruction is as follows: + + `LABEL =` + + `LABEL version="1.0"` + +### Examples + +1. A `run.Dockerfile` SHOULD set the label `io.buildpacks.rebasable` to `true` to indicate that any new run image layers are safe to rebase on top of new runtime base images + + * For the final image to be rebasable, all applied Dockerfiles must set this label to `true` + +2. A buildpack ID, buildpack version, and at least one stack MUST be provided in the OCI image config as a Label. + + Label: `io.buildpacks.buildpackage.metadata` + +```json +{ + "id": "", + "version": "", + "stacks": [ + { + "id": "", + "mixins": [""] + } + ] +} +``` From 3c70136918043db43aaf89d02fb623dec1860a6d Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 19 Jun 2024 19:31:18 -0400 Subject: [PATCH 3/3] adds reviewers feedback Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/add-labels.md | 47 ++++++++++++------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md index dcaf9f4c3..0f7dfeed3 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels.md @@ -7,7 +7,7 @@ weight=99 Labels are key-value pairs, stored as strings, that are attached to an image (i.e., arbitrary metadata). Labels are used to add helpful descriptions or attributes to an application image, which are meaningful to users. -Labels are usually added at the time an image is created and can also be modified at a later time. Images can have multiple labels; however, each key must be unique. +Labels are usually added at the time an image is created. Images can have multiple labels; however, each key must be unique. ## Key Points @@ -30,31 +30,42 @@ Since adding labels to application images is optional and not needed to run cont ## Implementation Steps -* General syntax of `LABEL` instruction is as follows: +Taking the perspective of a buildpack author, labels are added to the `launch.toml` file in the `/` directory as follows: - `LABEL =` +```toml +[[labels]] +key1 = "key1-string" +value1 = "value1-string" - `LABEL version="1.0"` +[[labels]] +key2 = "key2-string" +value2 = "value2-string" +``` + +Going back to the example in the [Buildpack Author's Guide](/docs/for-buildpack-authors/tutorials/basic-buildpack/01_setup-local-environment), this means writing to`"${CNB_LAYERS_DIR}"/node-js/launch.toml`. ### Examples -1. A `run.Dockerfile` SHOULD set the label `io.buildpacks.rebasable` to `true` to indicate that any new run image layers are safe to rebase on top of new runtime base images +A `shell` example looks as follows: - * For the final image to be rebasable, all applied Dockerfiles must set this label to `true` +```shell +cat << EOF > "${CNB_LAYERS_DIR}"/node-js/launch.toml +[[labels]] +key = "key" +value = "value" +EOF +``` -2. A buildpack ID, buildpack version, and at least one stack MUST be provided in the OCI image config as a Label. +While a `Go` example would set the `Labels` field in a `libcnb.BuildResult` as returned by the `build` binary: - Label: `io.buildpacks.buildpackage.metadata` +```Go +func (b Build) Build(context libcnb.BuildContext) (libcnb.BuildResult, error) { + result := libcnb.BuildResult{} -```json -{ - "id": "", - "version": "", - "stacks": [ - { - "id": "", - "mixins": [""] - } - ] + result.Labels = append(result.Labels, libcnb.Label{Key: "key", Value: "value"}) + + return result } ``` + +The `libcnb` library will automatically take care of writing the `launch.toml` file to the right place.