diff --git a/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels/index.html b/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels/index.html index 74ce2d37b..91c89f98c 100644 --- a/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels/index.html +++ b/docs/for-buildpack-authors/how-to/write-buildpacks/add-labels/index.html @@ -897,8 +897,51 @@
This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+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. Images can have multiple labels; however, each key must be unique.
+A LABEL
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
+Taking the perspective of a buildpack author, labels are added to the launch.toml
file in the <layers>/<layer>
directory as follows:
[[labels]]
+key1 = "key1-string"
+value1 = "value1-string"
+
+[[labels]]
+key2 = "key2-string"
+value2 = "value2-string"
+
Going back to the example in the Buildpack Author’s Guide, this means writing to"${CNB_LAYERS_DIR}"/node-js/launch.toml
.
A shell
example looks as follows:
cat << EOF > "${CNB_LAYERS_DIR}"/node-js/launch.toml
+[[labels]]
+key = "key"
+value = "value"
+EOF
+
While a Go
example would set the Labels
field in a libcnb.BuildResult
as returned by the build
binary:
func (b Build) Build(context libcnb.BuildContext) (libcnb.BuildResult, error) {
+ result := libcnb.BuildResult{}
+
+ 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.
The buildpacks exec.d
interface 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.
1. Location and Naming: Scripts are placed in the `<layer>/exec.d/` directory within a launch layer and must be executable. They can have any name.
-
-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.
-* **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.
-
-Location and Naming: Scripts are placed in the <layer>/exec.d/
directory within a launch layer and must be executable. They can have any name.
Script Behavior:
+0
to indicate success. A non-zero exit code will indicate an error and prevent the application from launching.<layer>/exec.d/
directory.