From a72506b7a8df53ba5b071251721e4ff4510030be Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 17 Jul 2024 22:36:13 -0400 Subject: [PATCH 1/5] expands slice layers page Signed-off-by: Hanan Younes --- .../write-buildpacks/create-slice-layers.md | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md index 296e8a40b..f8f4e2014 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md @@ -3,8 +3,34 @@ title="Create slice layers" weight=99 +++ +A `Slice` represents a layer in the `` directory to be exported during the `export` phase. + -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. + A buildpack MAY specify sub-paths within `` as `slices` in `launch.toml`. Separate layers MUST be created during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice with one or more files or directories. + +## Key Points + +* For each `slice`, buildpacks MUST specify zero or more `path globs` such that each path is either: + * Relative to the root of the app directory without traversing outside of the app directory + * Absolute and contained within the app directory +* `Path globs` MUST: + * Follow the pattern syntax defined in the [Go standard library](https://golang.org/pkg/path/filepath/#Match) + * Match zero or more files or directories +* The `lifecycle` MUST convert the `` directory into one or more layers using slices in each `launch.toml` such that slices from earlier buildpacks are processed before slices from later buildpacks. +* The `lifecycle` MUST process each slice as if all files matched in preceding slices no longer exists in the app directory +* The `lifecycle` MUST accept slices that do not contain any files or directory; however, it MAY warn about such slices +* The `lifecycle` MUST include all unmatched files in the app directory in any number of additional layers in the `OCI image` + +## Use Cases + +* `Slices` aid in optimizing data transfer for files that are commonly shared across applications + +## Implementation Steps + +`Slices` are added to the [launch.toml](https://github.com/buildpacks/spec/blob/main/buildpack.md#launchtoml-toml) file in the `/` directory as follows: -If you are familiar with this content and would like to make a contribution, please feel free to open a PR :) +```toml +[[slices]] +paths = [""] +``` From aeb651bb540c4037a7cabc7bc2653c1a75a359c0 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Tue, 23 Jul 2024 11:53:43 -0400 Subject: [PATCH 2/5] fixes an indentation issue Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/create-slice-layers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md index f8f4e2014..22c3b8d32 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md @@ -7,7 +7,7 @@ A `Slice` represents a layer in the `` directory to be exported during the - A buildpack MAY specify sub-paths within `` as `slices` in `launch.toml`. Separate layers MUST be created during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice with one or more files or directories. +A buildpack MAY specify sub-paths within `` as `slices` in `launch.toml`. Separate layers MUST be created during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice with one or more files or directories. ## Key Points From d7b141a381dfdff216f412e213bd84bc705e6e38 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 24 Jul 2024 15:02:36 -0400 Subject: [PATCH 3/5] adds reviewer feedback Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/create-slice-layers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md index 22c3b8d32..24b1d0fb8 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md @@ -7,7 +7,7 @@ A `Slice` represents a layer in the `` directory to be exported during the -A buildpack MAY specify sub-paths within `` as `slices` in `launch.toml`. Separate layers MUST be created during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice with one or more files or directories. +A buildpack may specify sub-paths within `` as `slices` in `launch.toml`. The lifecycle will create separate layers during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice with one or more files or directories. ## Key Points From b0c28430ea1ede4230254fb36d4b34b1b4cf72e6 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 24 Jul 2024 20:30:34 -0400 Subject: [PATCH 4/5] adds more reviewer feedback Signed-off-by: Hanan Younes --- .../write-buildpacks/create-slice-layers.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md index 24b1d0fb8..5b3fd79e3 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md @@ -3,11 +3,11 @@ title="Create slice layers" weight=99 +++ -A `Slice` represents a layer in the `` directory to be exported during the `export` phase. +After all buildpacks have executed, the contents of the application directory will be included in the final application image as a single layer, OR as `slice` layers. A `slice` layer contains a portion of the application directory as defined by a `filepath` glob. -A buildpack may specify sub-paths within `` as `slices` in `launch.toml`. The lifecycle will create separate layers during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice with one or more files or directories. +`Slices` are useful to avoid re-uploading unchanged data to the image registry. For example, if the application directory is a monolithic repository containing code for both a web frontend and sever backend, buildpacks can slice the directory into separate layers. Thus developers iterating on one part of the code base don't have to wait for the entire directory to re-upload at the end of the build. ## Key Points @@ -17,14 +17,7 @@ A buildpack may specify sub-paths within `` as `slices` in `launch.toml`. T * `Path globs` MUST: * Follow the pattern syntax defined in the [Go standard library](https://golang.org/pkg/path/filepath/#Match) * Match zero or more files or directories -* The `lifecycle` MUST convert the `` directory into one or more layers using slices in each `launch.toml` such that slices from earlier buildpacks are processed before slices from later buildpacks. -* The `lifecycle` MUST process each slice as if all files matched in preceding slices no longer exists in the app directory -* The `lifecycle` MUST accept slices that do not contain any files or directory; however, it MAY warn about such slices -* The `lifecycle` MUST include all unmatched files in the app directory in any number of additional layers in the `OCI image` - -## Use Cases - -* `Slices` aid in optimizing data transfer for files that are commonly shared across applications +* `Slices` from earlier buildpacks are processed before `slices` from later buildpacks. When a file is included in a `slice`, it is seen as if it no longer exists in the application directory for processing future `slices`. ## Implementation Steps @@ -34,3 +27,5 @@ A buildpack may specify sub-paths within `` as `slices` in `launch.toml`. T [[slices]] paths = [""] ``` + +A buildpack may specify sub-paths within `` as `slices` in `launch.toml`. The lifecycle will create separate layers during the [export](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-5-export) phase for each slice containing one or more files or directories. Any files in the `` directory that are not included in buildpack-defined slices will be included in the image as a final slice layer. From d8f8def8add55f872ec4c81021067ec0226c4a04 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Tue, 30 Jul 2024 21:43:41 -0400 Subject: [PATCH 5/5] removes an extra word Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/create-slice-layers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md index 5b3fd79e3..db151286c 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers.md @@ -17,7 +17,7 @@ After all buildpacks have executed, the contents of the application directory wi * `Path globs` MUST: * Follow the pattern syntax defined in the [Go standard library](https://golang.org/pkg/path/filepath/#Match) * Match zero or more files or directories -* `Slices` from earlier buildpacks are processed before `slices` from later buildpacks. When a file is included in a `slice`, it is seen as if it no longer exists in the application directory for processing future `slices`. +* `Slices` from earlier buildpacks are processed before `slices` from later buildpacks. When a file is included in a `slice`, it is as if it no longer exists in the application directory for processing future `slices`. ## Implementation Steps