Merge branch 'main' into feat/test-lifecycle-orchastration

Signed-off-by: Aidan Delaney <[email protected]>

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install Dependencies
         run: sudo apt-get install make curl jq
       - name: Install pack
-        uses: buildpacks/github-actions/setup-pack@v5.7.4
+        uses: buildpacks/github-actions/setup-pack@v5.8.2
         with:
           pack-version: '0.31.0'
       - name: Test

content/docs/app-journey.md

@@ -63,7 +63,7 @@ cd samples/apps/java-maven
 
 3. Build the app using [`pack`][pack-docs]
 ```
-pack build myapp --builder cnbs/sample-builder:jammy
+pack build myapp --builder cnbs/sample-builder:noble
 ```
 <!--+- "{{execute}}"+-->
 

content/docs/for-app-developers/concepts/build.md

@@ -23,5 +23,4 @@ Builders provide a convenient way to distribute buildpacks.
 [build-time base image]: /docs/for-app-developers/concepts/base-images/build/
 [builder]: /docs/for-platform-operators/concepts/builder
 [buildpack]: /docs/for-app-developers/concepts/buildpack/
-[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/
 [runtime base image]: /docs/for-app-developers/concepts/base-images/run/

content/docs/for-app-developers/concepts/builder.md

@@ -10,7 +10,7 @@ a [build-time base image], a [lifecycle] binary, and a reference to a [runtime b
 <!--more-->
 
 The [build-time base image] provides the base environment for the `builder`
-(e.g., an Ubuntu Jammy OS image with build tooling) and
+(e.g., an Ubuntu Noble OS image with build tooling) and
 a [runtime base image] provides the base environment for the `app image` during runtime.
 
 ![builder](/images/builder.svg)

content/docs/for-app-developers/concepts/experimental-features.md

@@ -0,0 +1,36 @@
++++
+title="What are experimental features?"
+weight=8
++++
+
+Certain features are considered `experimental` and susceptible to change in future API versions.
+
+<!--more-->
+
+This means users will need to enable the `experimental` mode in order to use one of these features.
+
+If using `pack`, run `pack config experimental true`, or add `experimental = true` to your `~/.pack/config.toml` file to enable experimental features.
+
+If using the `lifecycle` directly, set the `CNB_EXPERIMENTAL_MODE` [environment variable](https://github.com/buildpacks/spec/blob/main/platform.md#experimental-features).
+
+The following features are experimental for `pack`:
+
+* building for [Windows containers][windows]
+* exporting to [OCI layout][oci-layout] format on disk
+* Interacting with the [buildpack registry][registry]
+* `pack manifest` commands
+* `pack buildpack --flatten`
+* `pack build --interactive`
+* When building, reading project metadata version & source URL from [project.toml][project-descriptor]
+
+The following features are experimental for `lifecycle`:
+
+* Building for [Windows containers][windows]
+* Exporting to [OCI layout][oci-layout] format on disk
+
+For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][oci-layout].
+
+[oci-layout]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/export-to-oci-layout/
+[project-descriptor]: https://buildpacks.io/docs/reference/config/project-descriptor/
+[registry]: https://buildpacks.io/docs/for-buildpack-authors/how-to/distribute-buildpacks/publish-buildpack/
+[windows]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/build-for-windows/

content/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md

@@ -33,7 +33,7 @@ export FOO=BAR
 pack build sample-app \
     --env "HELLO=WORLD" \
     --env "FOO" \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --buildpack  samples/buildpacks/hello-world/ \
     --buildpack samples/apps/bash-script/bash-script-buildpack/ \
     --path  samples/apps/bash-script/
@@ -79,7 +79,7 @@ echo -en "HELLO=WORLD\nFOO" > ./envfile
 ```
 pack build sample-app \
     --env-file ./envfile \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --buildpack  samples/buildpacks/hello-world/ \
     --buildpack samples/apps/bash-script/bash-script-buildpack/ \
     --path  samples/apps/bash-script/
@@ -125,7 +125,7 @@ EOL
 2. Build the app
 ```
 pack build sample-app \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --buildpack  samples/buildpacks/hello-world/ \
     --buildpack samples/apps/bash-script/bash-script-buildpack/ \
     --path  samples/apps/bash-script/

content/docs/for-app-developers/how-to/build-inputs/specify-default-launch-process.md

@@ -4,6 +4,15 @@ weight=99
 summary="Buildpacks can define multiple processes for an application image. Specify which process should be the default."
 +++
 
-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.
+While buildpacks usually define the default process type for an application, end users may specify the desired default process.
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+To specify the default process:
+
+* You first need to know what named process types might be contributed by the buildpacks in your build; for more information, see docs for [running the application][Run the application]
+* Append the following flag to the `pack build` command:
+
+```bash
+pack build --default-process <process name> <image name>` # <process name> must be a valid process name
+```
+
+[Run the application]: https://buildpacks.io/docs/for-app-developers/how-to/build-outputs/specify-launch-process/

content/docs/for-app-developers/how-to/build-inputs/use-cache-image.md

@@ -29,10 +29,10 @@ For the following examples we will use:
 > **NOTE:**  If we wish to publish to an external registry like `Dockerhub` we will first need to authenticate with `docker` to allow us to push images. We can do this via `docker login`
 
 
-Next we trust the `cnbs/sample-builder:jammy` builder in order to allow access to docker credentials when publishing.
+Next we trust the `cnbs/sample-builder:noble` builder in order to allow access to docker credentials when publishing.
 
 ```
-pack config trusted-builders add cnbs/sample-builder:jammy
+pack config trusted-builders add cnbs/sample-builder:noble
 ```
 <!--+- "{{execute}}"+-->
 
@@ -42,7 +42,7 @@ To build the `localhost:5000/buildpack-examples/cache-image-example` application
 
 ```
 pack build localhost:5000/buildpack-examples/cache-image-example \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --buildpack samples/java-maven \
     --path samples/apps/java-maven \
     --cache-image localhost:5000/buildpack-examples/maven-cache-image:latest \
@@ -76,7 +76,7 @@ builds may also update the specified `cache-image`.
 The following command will restore data for the `samples/java-maven:maven_m2` layer from the cache image.
 ```
 pack build localhost:5000/buildpack-examples/second-cache-image-example \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --buildpack samples/java-maven \
     --path samples/apps/java-maven \
     --cache-image localhost:5000/buildpack-examples/maven-cache-image:latest \

content/docs/for-app-developers/how-to/build-inputs/use-project-toml.md

@@ -45,7 +45,7 @@ To use a `project.toml` file, simply:
 ```shell script
 # build the app
 pack build sample-app \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --path  samples/apps/bash-script/
 
 # run the app
@@ -55,7 +55,7 @@ docker run sample-app
 If the descriptor is named `project.toml`, it will be read by `pack` automatically. Otherwise, you can run:
 ```shell script
 pack build sample-app \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --path  samples/apps/bash-script/ \
     --descriptor  samples/apps/bash-script/<project-descriptor-file.toml>
 ```
@@ -99,7 +99,7 @@ Paste the above `toml` as `new-project.toml` in the `samples/apps/bash-script/`
 ```shell script
 # build the app
 pack build sample-app \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --path  samples/apps/bash-script/ \
     --descriptor samples/apps/bash-script/new-project.toml
 
@@ -112,7 +112,7 @@ The builder can also be [specified](https://github.com/buildpacks/spec/blob/main
 
 ```toml
 [io.buildpacks]
-builder = "cnbs/sample-builder:jammy"
+builder = "cnbs/sample-builder:noble"
 ```
 
 ```shell script

content/docs/for-app-developers/how-to/build-inputs/use-volume-mounts.md

@@ -83,7 +83,7 @@ Now, we can mount this volume during `pack build`:
 ```bash
 ls -al
 pack build volume-example \
-    --builder cnbs/sample-builder:jammy \
+    --builder cnbs/sample-builder:noble \
     --buildpack samples/buildpacks/hello-world \
     --path samples/apps/bash-script \
     --volume test-volume:/platform/volume:ro

content/docs/for-app-developers/how-to/build-outputs/inspect-app.md

@@ -8,20 +8,24 @@ Buildpacks-built images contain metadata that allow you to audit both the image
 <!--more-->
 
 Information includes:
+
 * 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...!
 
+`pack` offers a command to help you inspect the application image and view some of its contents as shown below:
+
 ```bash
 pack inspect-image test-node-js-app
 ```
+
 You should see the following:
 
 ```text
 Run Images:
-  cnbs/sample-base-run:jammy
+  cnbs/sample-base-run:noble
 ...
 
 Buildpacks:
@@ -35,4 +39,25 @@ Processes:
 
 Apart from the above standard metadata, buildpacks can also populate information about the dependencies they have provided in form of a `Software Bill-of-Materials` or [SBOM].
 
+Buildpacks-built images are constructed in a way that’s easy to understand, with each of the layers being meaningful and independent of all other layers. You can get more details about each layer and how it was created to better understand how the [build] actually worked.
+
+There are a number of available tools that can help you achieve this and understand what is contained in your `OCI` image; a popular one is [dive].
+
+`Dive` can help you inspect `OCI` images and view their layers and each layer's details. If you were to build an `OCI` image following the [multi process app] example and run `dive` on the generated image, you'll be presented with some detailed information about all of the image layers and the contents of each layer.
+
+You can use `dive` as follows:
+
+```bash
+dive multi-process-app
+```
+
+The output should look similar to the following:
+
+PLACEHOLDER
+
+As seen in the output above, you're presented with `Layers`, `Layer Details`, `Image Details`, and `Current Layer Contents`. To view the contents or explore the file tree of any layer, you need to select the layer on the left using the arrow keys.
+
 [SBOM]: /docs/for-app-developers/how-to/build-outputs/download-sbom
+[build]: https://buildpacks.io/docs/for-app-developers/concepts/build/
+[Dive]: https://github.com/wagoodman/dive
+[multi process app]: https://buildpacks.io/docs/for-app-developers/how-to/build-outputs/specify-launch-process/#build-a-multi-process-app

content/docs/for-app-developers/how-to/build-outputs/specify-launch-process.md

@@ -1,4 +1,3 @@
-
 +++
 title="Run the application"
 aliases=[
@@ -15,7 +14,8 @@ Buildpacks-built images can contain multiple process types.
 For this example we will use the `hello-processes` buildpack from our [samples][samples] repo so make sure you have it cloned locally.
 
 Let's build the app.
-```
+
+```bash
 pack build multi-process-app \
     --builder cnbs/sample-builder:alpine \
     --buildpack samples/java-maven \
@@ -26,14 +26,14 @@ pack build multi-process-app \
 
 If you inspect the app image with `pack`, you will see multiple process types defined:
 
-```
+```bash
 pack inspect-image multi-process-app
 ```
 <!--+- "{{execute}}"+-->
 
 The output should look similar to the below:
 
-```
+```text
 Inspecting image: multi-process-app
 
 REMOTE:
@@ -76,16 +76,18 @@ The `launcher` will source any profile scripts (for `non-direct` processes) and
 
 If you would like to run the default process, you can simply run the app image without any additional arguments:
 
-```
+```bash
 docker run --rm -p 8080:8080 multi-process-app
 ```
 <!--+- "{{execute}}"+-->
 
+>As an app developer, you can specify what the default process is; see the [specify default launch process][default-process] page for more information.
+
 #### Default process type with additional arguments
 
 If you would like to pass additional arguments to the default process, you can run the app image with the arguments specified in the command:
 
-```
+```bash
 docker run --rm -p 8080:8080 multi-process-app --spring.profiles.active=mysql
 ```
 <!--+- "{{execute interrupt}}"+-->
@@ -94,7 +96,7 @@ docker run --rm -p 8080:8080 multi-process-app --spring.profiles.active=mysql
 
 To run a non-default process type, set the process type as the entrypoint for the run container:
 
-```
+```bash
 docker run --rm --entrypoint sys-info multi-process-app
 ```
 <!--+- "{{execute interrupt}}"+-->
@@ -103,7 +105,7 @@ docker run --rm --entrypoint sys-info multi-process-app
 
 You can pass additional arguments to a non-default process type:
 
-```
+```bash
 docker run --rm --entrypoint sys-info multi-process-app --spring.profiles.active=mysql
 ```
 <!--+- "{{execute interrupt}}"+-->
@@ -112,21 +114,24 @@ docker run --rm --entrypoint sys-info multi-process-app --spring.profiles.active
 
 You can even override the buildpack-defined process types:
 
-```
+```bash
 docker run --rm --entrypoint launcher -it multi-process-app bash
 ```
 <!--+- "{{execute interrupt}}"+-->
 
-Now let's exit this shell and run an alternative entrypoint - 
-```
+Now let's exit this shell and run an alternative entrypoint -
+
+```bash
 exit
 ```
 <!--+- "{{execute interrupt}}"+-->
-```
+
+```bash
 docker run --rm --entrypoint launcher -it multi-process-app echo hello "$WORLD" # $WORLD is evaluated on the host machine
 ```
 <!--+- "{{execute interrupt}}"+-->
-```
+
+```bash
 docker run --rm --entrypoint launcher -it multi-process-app echo hello '$WORLD' # $WORLD is evaluated in the container after profile scripts are sourced
 ```
 <!--+- "{{execute interrupt}}"+-->
@@ -135,7 +140,7 @@ docker run --rm --entrypoint launcher -it multi-process-app echo hello '$WORLD'
 
 An entire script may be provided as a single argument:
 
-```
+```bash
 docker run --rm --entrypoint launcher -it multi-process-app 'for opt in $JAVA_OPTS; do echo $opt; done'
 ```
 <!--+- "{{execute interrupt}}"+-->
@@ -145,7 +150,7 @@ docker run --rm --entrypoint launcher -it multi-process-app 'for opt in $JAVA_OP
 By passing `--` before the command, we instruct the `launcher` to start the provided process without `bash`.
 Note that while buildpack-provided environment variables will be set in the execution environment, no profile scripts will be sourced (as these require `bash`):
 
-```
+```text
 docker run --rm --entrypoint launcher multi-process-app -- env # output will include buildpack-provided env vars
 docker run --rm --entrypoint launcher multi-process-app -- echo hello "$WORLD" # $WORLD is evaluated on the host machine
 docker run --rm --entrypoint launcher multi-process-app -- echo hello '$WORLD' # $WORLD is not evaluated, output will include string literal `$WORLD`
@@ -155,11 +160,12 @@ docker run --rm --entrypoint launcher multi-process-app -- echo hello '$WORLD' #
 
 You can bypass the launcher entirely by setting a new entrypoint for the run container:
 
-```
+```bash
 docker run --rm --entrypoint bash -it multi-process-app # profile scripts have NOT been sourced and buildpack-provided env vars are NOT set in this shell
 ```
 <!--+- "{{execute interrupt}}"+-->
 
 To learn more about the launcher, see the [platform spec](https://github.com/buildpacks/spec/blob/main/platform.md#launcher).
 
 [samples]: https://github.com/buildpacks/samples
+[default-process]: https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/specify-default-launch-process/