Merge branch 'main' into ste-review

Author: AidanDelaney

.github/workflows/main.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install pack
         uses: buildpacks/github-actions/setup-pack@v5.2.0
         with:
-          pack-version: '0.30.0-rc1'
+          pack-version: '0.30.0-rc1' # FIXME: update to 0.30.0 when available
       - name: Test
         run: make test
         env:

content/docs/app-developer-guide/run-an-app.md

@@ -50,6 +50,8 @@ Base Image:
 Run Images:
   cnbs/sample-stack-run:alpine
 
+Rebasable: true
+
 Buildpacks:
   ID                             VERSION           HOMEPAGE
   samples/java-maven             0.0.1             https://github.com/buildpacks/samples/tree/main/buildpacks/java-maven

content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md

@@ -10,6 +10,7 @@ One of the benefits of buildpacks is they can also populate the app image with m
 * The process types that are available and the commands associated with them
 * The run-image the app image was based on
 * The buildpacks were used to create the app image
+* Whether the run-image can be rebased with a new version through the `Rebasable` label or not
 * And more...!
 
 You can find some of this information using `pack` via its `inspect-image` command.  The bill-of-materials information will be available using `pack sbom download`.

content/docs/extension-guide/create-extension/_index.md

@@ -24,7 +24,7 @@ This is a step-by-step tutorial for creating and using CNB image extensions.
 - [See a build that requires base image extension in order to succeed](/docs/extension-guide/create-extension/why-dockerfiles)
 - [Building blocks of an extension](/docs/extension-guide/create-extension/building-blocks-extension)
 - [Generating a build.Dockerfile for your application](/docs/extension-guide/create-extension/build-dockerfile)
-- [Generating a run.Dockerfile for your application](/docs/extension-guide/create-extension/run-dockerfile)
+- [Generating a run.Dockerfile for your application](/docs/extension-guide/create-extension/run-dockerfile-switch)
 
 <!--+if false+-->
 ---

content/docs/extension-guide/create-extension/build-dockerfile.md

@@ -8,6 +8,9 @@ aliases = [
 
 <!-- test:suite=dockerfiles;weight=4 -->
 
+Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies
+for the current application.
+
 ### Examine `vim` extension
 
 #### detect
@@ -28,7 +31,9 @@ cat $PWD/samples/extensions/vim/bin/generate
 
 The extension generates a `build.Dockerfile` that installs `vim` on the builder image.
 
-### Re-build the application image
+### Configure the `hello-extensions` buildpack to require `vim`
+
+Set the `BP_REQUIRES` build-time environment variable to configure the `hello-extensions` buildpack to require `vim` (review the `./bin/detect` script to see why this works).
 
 <!-- test:exec -->
 ```
@@ -47,6 +52,7 @@ Note that `--network host` is necessary when publishing to a local registry.
 You should see:
 
 ```
+...
 [detector] ======== Results ========
 [detector] pass: samples/vim@0.0.1
 [detector] pass: samples/hello-extensions@0.0.1
@@ -55,12 +61,12 @@ You should see:
 [detector] samples/hello-extensions 0.0.1
 [detector] Running generate for extension samples/vim@0.0.1
 ...
-[extender] Found build Dockerfile for extension 'samples/vim'
-[extender] Applying the Dockerfile at /layers/generated/build/samples_vim/Dockerfile...
+[extender (build)] Found build Dockerfile for extension 'samples/vim'
+[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_vim/Dockerfile...
 ...
-[extender] Running build command
-[extender] ---> Hello Extensions Buildpack
-[extender] vim v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro
+[extender (build)] Running build command
+[extender (build)] ---> Hello Extensions Buildpack
+[extender (build)] VIM - Vi IMproved 9.0 (2022 Jun 28, compiled May 19 2023 16:28:36)
 ...
 Successfully built image hello-extensions
 ```
@@ -85,5 +91,4 @@ Let's take a look at how the `samples/curl` extension fixes the error by switchi
 <!--+ if false+-->
 ---
 
-<a href="/docs/extension-guide/create-extension/run-dockerfile" class="button bg-pink">Next Step</a>
-<!--+ end +-->
+<a href="/docs/extension-guide/create-extension/run-dockerfile-switch" class="button bg-pink">Next Step</a>

content/docs/extension-guide/create-extension/building-blocks-extension.md

@@ -12,10 +12,10 @@ aliases = [
 
 <!-- test:exec -->
 ```bash
-vim --help
+tree $PWD/samples/extensions/vim
 ```
 
-(That's right, we're using the very tool we will later be installing!) You should see something akin to the following:
+You should see something akin to the following:
 
 ```
 .
@@ -38,11 +38,6 @@ vim --help
   * Only a limited set of Dockerfile instructions is supported - consult
     the [spec](https://github.com/buildpacks/spec/blob/main/image_extension.md)
     for further details.
-  * In the [initial implementation](/docs/features/dockerfiles#phased-approach), `run.Dockerfile` instructions are
-    limited to a single `FROM` instruction (effectively, it is only possible to switch the run-time base image to a
-    pre-created image i.e., no dynamic image modification is allowed). Consult
-    the [spec](https://github.com/buildpacks/spec/blob/main/image_extension.md)
-    for further details.
 
 We'll take a closer look at the executables for the `vim` extension in the next step.
 

content/docs/extension-guide/create-extension/run-dockerfile-extend.md

@@ -0,0 +1,107 @@
++++
+title="Generating a run.Dockerfile that extends the runtime base image"
+weight=406
++++
+
+<!-- test:suite=dockerfiles;weight=6 -->
+
+Run images can be kept lean if image extensions are used to dynamically install the needed dependencies
+for the current application.
+
+### Examine `cowsay` extension
+
+#### detect
+
+<!-- test:exec -->
+```bash
+cat $PWD/samples/extensions/cowsay/bin/detect
+```
+
+The extension always detects (because its exit code is `0`) and provides a dependency called `cowsay`.
+
+#### generate
+
+<!-- test:exec -->
+```bash
+cat $PWD/samples/extensions/cowsay/bin/generate
+```
+
+The extension generates a `run.Dockerfile` that installs `cowsay` on the current run image.
+
+### Configure the `hello-extensions` buildpack to require `cowsay`
+
+Set the `BP_REQUIRES` build-time environment variable to configure the `hello-extensions` buildpack to require both `vim` and `curl` (review the `./bin/detect` script to see why this works).
+
+<!-- test:exec -->
+```bash
+pack build hello-extensions \
+  --builder localhost:5000/extensions-builder \
+  --env BP_EXT_DEMO=1 \
+  --env BP_REQUIRES=vim,curl,cowsay \
+  --path $PWD/samples/apps/java-maven \
+  --pull-policy always \
+  --network host \
+  --verbose
+```
+
+Note that `--network host` is necessary when publishing to a local registry.
+
+You should see:
+
+```
+...
+[detector] ======== Results ========
+[detector] pass: samples/vim@0.0.1
+[detector] pass: samples/curl@0.0.1
+[detector] pass: samples/cowsay@0.0.1
+[detector] pass: samples/hello-extensions@0.0.1
+[detector] Resolving plan... (try #1)
+[detector] samples/vim             0.0.1
+[detector] samples/curl             0.0.1
+[detector] samples/cowsay           0.0.1
+[detector] samples/hello-extensions 0.0.1
+[detector] Running generate for extension samples/vim@0.0.1
+...
+[detector] Running generate for extension samples/curl@0.0.1
+...
+[detector] Running generate for extension samples/cowsay@0.0.1
+...
+[detector] Found a run.Dockerfile from extension 'samples/curl' setting run image to 'localhost:5000/run-image-curl'
+...
+[extender (build)] Found build Dockerfile for extension 'samples/vim'
+[extender (build)] Applying Dockerfile at /layers/generated/build/samples_vim/Dockerfile...
+[extender (run)] Found run Dockerfile for extension 'samples/curl'
+[extender (run)] Found run Dockerfile for extension 'samples/cowsay'
+[extender (run)] Applying Dockerfile at /layers/generated/run/samples_curl/Dockerfile...
+...
+[extender (run)] Applying Dockerfile at /layers/generated/run/samples_cowsay/Dockerfile
+...
+[extender (build)] Running build command
+[extender (build)] ---> Hello Extensions Buildpack
+[extender (build)] VIM - Vi IMproved 9.0 (2022 Jun 28, compiled May 19 2023 16:28:36)
+...
+Successfully built image hello-extensions
+```
+
+Note: build image extension and run image extension are done in parallel,
+so the log lines for those phases may print in a different order from that shown above.
+
+### See the image run successfully
+
+<!-- test:exec -->
+```bash
+docker run --rm --entrypoint cowsay hello-extensions
+```
+
+You should see something akin to:
+
+```
+ ________
+< MOOOO! >
+ --------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```

content/docs/extension-guide/create-extension/run-dockerfile.md renamed to content/docs/extension-guide/create-extension/run-dockerfile-switch.md

@@ -1,5 +1,5 @@
 +++
-title="Generating a run.Dockerfile"
+title="Generating a run.Dockerfile that switches the runtime base image"
 weight=405
 aliases = [
   "/docs/extension-author-guide/run-dockerfile/"
@@ -8,6 +8,10 @@ aliases = [
 
 <!-- test:suite=dockerfiles;weight=5 -->
 
+Platforms can have several run images available, each tailored to a specific language family - thus limiting the number
+of installed dependencies for each image to the minimum necessary to support the targeted language. Image extensions
+can be used to switch the run image to that most appropriate for the current application.
+
 ### Examine `curl` extension
 
 #### detect
@@ -26,7 +30,7 @@ The extension always detects (because its exit code is `0`) and provides a depen
 cat $PWD/samples/extensions/curl/bin/generate
 ```
 
-The extension generates a `run.Dockerfile` that switches the run image to reference `run-image-curl`.
+The extension generates a `run.Dockerfile` that switches the run image to reference `localhost:5000/run-image-curl`.
 
 ### Build a run image for `curl` extension to use
 
@@ -46,9 +50,13 @@ Build the run image:
 docker build \
   --file $PWD/samples/stacks/alpine/run/curl.Dockerfile \
   --tag localhost:5000/run-image-curl .
+
+docker push localhost:5000/run-image-curl
 ```
 
-### Re-build the application image
+### Configure the `hello-extensions` buildpack to require `curl`
+
+Set the `BP_REQUIRES` build-time environment variable to configure the `hello-extensions` buildpack to require both `vim` and `curl` (review the `./bin/detect` script to see why this works).
 
 <!-- test:exec -->
 ```bash
@@ -70,8 +78,11 @@ You should see:
 [detector] ======== Results ========
 [detector] pass: samples/vim@0.0.1
 [detector] pass: samples/curl@0.0.1
+[detector] pass: samples/cowsay@0.0.1
 [detector] pass: samples/hello-extensions@0.0.1
 [detector] Resolving plan... (try #1)
+[detector] skip: samples/cowsay@0.0.1 provides unused cowsay
+[detector] 3 of 4 buildpacks participating
 [detector] samples/vim             0.0.1
 [detector] samples/curl             0.0.1
 [detector] samples/hello-extensions 0.0.1
@@ -80,14 +91,14 @@ You should see:
 [detector] Running generate for extension samples/curl@0.0.1
 ...
 [detector] Checking for new run image
-[detector] Found a run.Dockerfile configuring image 'run-image-curl' from extension with id 'samples/curl'
+[detector] Found a run.Dockerfile from extension 'samples/curl' setting run image to 'localhost:5000/run-image-curl'
 ...
-[extender] Found build Dockerfile for extension 'samples/vim'
-[extender] Applying the Dockerfile at /layers/generated/build/samples_vim/Dockerfile...
+[extender (build)] Found build Dockerfile for extension 'samples/vim'
+[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_vim/Dockerfile...
 ...
-[extender] Running build command
-[extender] ---> Hello Extensions Buildpack
-[extender] vim v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro
+[extender (build)] Running build command
+[extender (build)] ---> Hello Extensions Buildpack
+[extender (build)] VIM - Vi IMproved 9.0 (2022 Jun 28, compiled May 19 2023 16:28:36)
 ...
 Successfully built image hello-extensions
 ```
@@ -108,20 +119,31 @@ curl 7.85.0-DEV (x86_64-pc-linux-musl) ... more stuff here ...
 What happened: now that `hello-extensions` requires both `vim` and `curl` in its build plan, both extensions are
   included in the build and provide the needed dependencies for build and launch, respectively
 * The `vim` extension installs `vim` at build time, as before
-* The `curl` extension switches the run image to `run-image-curl`, which has `curl` installed
+* The `curl` extension switches the run image to `localhost:5000/run-image-curl`, which has `curl` installed
 
 Now our `curl` process can succeed!
 
-## What's next?
+### Next steps
 
-The `vim` and `curl` examples are very simple, but we can unlock powerful new features with this functionality.
+Our `curl` process succeeded, but there is another process type defined on our image:
 
-Platforms could have several run images available, each tailored to a specific language family, thus limiting the number
-of installed dependencies for each image to the minimum necessary to support the targeted language. Image extensions
-could be used to switch the run image to that most appropriate for the current application.
+```
+docker run --rm --entrypoint cowsay hello-extensions
+```
+
+You should see:
+
+```
+ERROR: failed to launch: path lookup: exec: "cowsay": executable file not found in $PATH
+```
+
+Our run image, `localhost:5000/run-image-curl`, has `curl` installed, but it doesn't have `cowsay`.
+
+In general, we may not always have a preconfigured run image available with all the needed dependencies for the current application.
+Luckily, we can also use image extensions to dynamically install runtime dependencies at build time. Let's look at that next.
 
-Similarly, builder images could be kept lean if image extensions are used to dynamically install the needed dependencies
-for each application.
+<!--+ if false+-->
+---
 
-In the future, both run image switching and run image modification will be supported, opening the door to other use
-cases. Consult the [RFC](https://github.com/buildpacks/rfcs/pull/173) for further information.
+<a href="/docs/extension-guide/create-extension/run-dockerfile-extend" class="button bg-pink">Next Step</a>
+<!--+ end +-->

content/docs/extension-guide/create-extension/setup-local-environment.md

@@ -55,7 +55,7 @@ cd <your preferred workspace directory>
 pack version
 ```
 
-The version should be at least `0.28.0`
+The version should be at least `0.30.0`
 
 ### Update pack configuration