From 757f6f1e2b8dc157e2f7c4c384d05db40a48ab40 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 15:07:58 -0500 Subject: [PATCH 01/17] Improve extensions demo by not requiring the builder to be recreated after every failed build The hello-extensions buildpack can be configured through the environment after https://github.com/buildpacks/samples/pull/142 lands Signed-off-by: Natalie Arellano --- .../create-extension/build-dockerfile.md | 24 ++++--------------- .../create-extension/run-dockerfile.md | 24 ++++--------------- .../create-extension/why-dockerfiles.md | 5 +++- 3 files changed, 12 insertions(+), 41 deletions(-) diff --git a/content/docs/extension-author-guide/create-extension/build-dockerfile.md b/content/docs/extension-author-guide/create-extension/build-dockerfile.md index 254bb1be4..46c038bb1 100644 --- a/content/docs/extension-author-guide/create-extension/build-dockerfile.md +++ b/content/docs/extension-author-guide/create-extension/build-dockerfile.md @@ -25,32 +25,16 @@ cat $PWD/samples/extensions/tree/bin/generate The extension generates a `build.Dockerfile` that installs `tree` on the builder image. -### Re-create our builder with `hello-extensions` updated to require `tree` +### Configure the `hello-extensions` buildpack to require `tree` -Edit `$PWD/samples/buildpacks/hello-extensions/bin/detect` to uncomment the first set of lines that output `[[requires]]` to the build plan: - - -```bash -sed -i "10,11s/#//" $PWD/samples/buildpacks/hello-extensions/bin/detect -``` - -(On Mac, use `sed -i '' "10,11s/#//" $PWD/samples/buildpacks/hello-extensions/bin/detect`) - -Re-create the builder: - - -``` -pack builder create localhost:5000/extensions-builder \ - --config $PWD/samples/builders/alpine/builder.toml \ - --publish -``` - -### Re-build the application image +Set the `BP_REQUIRES` build-time environment variable to configure the `hello-extensions` buildpack to require `tree` (review the `./bin/detect` script to see why this works). ``` pack build hello-extensions \ --builder localhost:5000/extensions-builder \ + --env BP_EXT_DEMO=1 \ + --env BP_REQUIRES=tree \ --network host \ --path $PWD/samples/apps/java-maven \ --pull-policy always \ diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile.md b/content/docs/extension-author-guide/create-extension/run-dockerfile.md index 9f92ab5f5..ef62cc8f7 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile.md @@ -45,32 +45,16 @@ docker build \ --tag run-image-curl . ``` -### Re-create our builder with `hello-extensions` updated to require `curl` +### Configure the `hello-extensions` buildpack to require `curl` -Edit `$PWD/samples/buildpacks/hello-extensions/bin/detect` to uncomment the second set of lines that output `[[requires]]` to the build plan: - - -```bash -sed -i "14,15s/#//" $PWD/samples/buildpacks/hello-extensions/bin/detect -``` - -(On Mac, use `sed -i '' "14,15s/#//" $PWD/samples/buildpacks/hello-extensions/bin/detect`) - -Re-create the builder: - - -```bash -pack builder create localhost:5000/extensions-builder \ - --config $PWD/samples/builders/alpine/builder.toml \ - --publish -``` - -### Re-build the application image +Set the `BP_REQUIRES` build-time environment variable to configure the `hello-extensions` buildpack to require both `tree` and `curl` (review the `./bin/detect` script to see why this works). ```bash pack build hello-extensions \ --builder localhost:5000/extensions-builder \ + --env BP_EXT_DEMO=1 \ + --env BP_REQUIRES=tree,curl \ --path $PWD/samples/apps/java-maven \ --pull-policy always \ --network host \ diff --git a/content/docs/extension-author-guide/create-extension/why-dockerfiles.md b/content/docs/extension-author-guide/create-extension/why-dockerfiles.md index fdce88255..28c5f99f3 100644 --- a/content/docs/extension-author-guide/create-extension/why-dockerfiles.md +++ b/content/docs/extension-author-guide/create-extension/why-dockerfiles.md @@ -16,7 +16,9 @@ Let's see a build that requires base image extension in order to succeed. cat $PWD/samples/buildpacks/hello-extensions/bin/detect ``` -The buildpack always detects (because its exit code is `0`) but doesn't require any dependencies (as the output build plan is empty). +The buildpack opts-out of the build (exits with non-zero code) unless the `BP_EXT_DEMO` environment variable is set. + +If the `BP_EXT_DEMO` environment variable is set, the buildpack detects (exits with code `0`), but doesn't require any dependencies through a build plan unless the `BP_REQUIRES` environment variable is set. #### build @@ -57,6 +59,7 @@ Run `pack build` (note that the "source" directory is effectively ignored in our ``` pack build hello-extensions \ --builder localhost:5000/extensions-builder \ + --env BP_EXT_DEMO=1 \ --network host \ --path $PWD/samples/apps/java-maven \ --pull-policy always \ From 9c3c2eaafab8e1afb82577b2833f8c45e869328c Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 4 Apr 2023 17:47:43 -0400 Subject: [PATCH 02/17] Update extensions demo to show run image extension Signed-off-by: Natalie Arellano --- .../create-extension/build-dockerfile.md | 19 +++- .../create-extension/run-dockerfile-extend.md | 107 ++++++++++++++++++ ...dockerfile.md => run-dockerfile-switch.md} | 50 +++++--- .../create-extension/why-dockerfiles.md | 15 ++- 4 files changed, 165 insertions(+), 26 deletions(-) create mode 100644 content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md rename content/docs/extension-author-guide/create-extension/{run-dockerfile.md => run-dockerfile-switch.md} (63%) diff --git a/content/docs/extension-author-guide/create-extension/build-dockerfile.md b/content/docs/extension-author-guide/create-extension/build-dockerfile.md index 46c038bb1..ee377009c 100644 --- a/content/docs/extension-author-guide/create-extension/build-dockerfile.md +++ b/content/docs/extension-author-guide/create-extension/build-dockerfile.md @@ -5,6 +5,9 @@ weight=404 +Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies +for the current application. + ### Examine `tree` extension #### detect @@ -46,20 +49,26 @@ Note that `--network host` is necessary when publishing to a local registry. You should see: ``` +... [detector] ======== Results ======== [detector] pass: samples/tree@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/curl@0.0.1 provides unused curl +[detector] skip: samples/cowsay@0.0.1 provides unused cowsay +[detector] 2 of 4 buildpacks participating [detector] samples/tree 0.0.1 [detector] samples/hello-extensions 0.0.1 [detector] Running generate for extension samples/tree@0.0.1 ... -[extender] Found build Dockerfile for extension 'samples/tree' -[extender] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... +[extender (build)] Found build Dockerfile for extension 'samples/tree' +[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... ... -[extender] Running build command -[extender] ---> Hello Extensions Buildpack -[extender] tree 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)] tree v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro ... Successfully built image hello-extensions ``` diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md new file mode 100644 index 000000000..4181add6b --- /dev/null +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md @@ -0,0 +1,107 @@ ++++ +title="Generating a run.Dockerfile that extends the runtime base image" +weight=406 ++++ + + + +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 + + +```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 + + +```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 `tree` and `curl` (review the `./bin/detect` script to see why this works). + + +```bash +pack build hello-extensions \ + --builder localhost:5000/extensions-builder \ + --env BP_EXT_DEMO=1 \ + --env BP_REQUIRES=tree,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/tree@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/tree 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/tree@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 'run-image-curl' +... +[extender (build)] Found build Dockerfile for extension 'samples/tree' +[extender (build)] Applying Dockerfile at /layers/generated/build/samples_tree/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)] tree v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro +... +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 + + +```bash +docker run --rm --entrypoint cowsay hello-extensions +``` + +You should see something akin to: + +``` + ________ +< MOOOO! > + -------- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md similarity index 63% rename from content/docs/extension-author-guide/create-extension/run-dockerfile.md rename to content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md index ef62cc8f7..beb5fbe43 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md @@ -1,10 +1,14 @@ +++ -title="Generating a run.Dockerfile" +title="Generating a run.Dockerfile that switches the runtime base image" weight=405 +++ +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 @@ -69,8 +73,11 @@ You should see: [detector] ======== Results ======== [detector] pass: samples/tree@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/tree 0.0.1 [detector] samples/curl 0.0.1 [detector] samples/hello-extensions 0.0.1 @@ -79,14 +86,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 'run-image-curl' ... -[extender] Found build Dockerfile for extension 'samples/tree' -[extender] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... +[extender (build)] Found build Dockerfile for extension 'samples/tree' +[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... ... -[extender] Running build command -[extender] ---> Hello Extensions Buildpack -[extender] tree 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)] tree v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro ... Successfully built image hello-extensions ``` @@ -111,16 +118,27 @@ What happened: now that `hello-extensions` requires both `tree` and `curl` in it Now our `curl` process can succeed! -## What's next? +### Next steps -The `tree` 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, `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. + +--- -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. +Next Step + diff --git a/content/docs/extension-author-guide/create-extension/why-dockerfiles.md b/content/docs/extension-author-guide/create-extension/why-dockerfiles.md index 28c5f99f3..3406a424b 100644 --- a/content/docs/extension-author-guide/create-extension/why-dockerfiles.md +++ b/content/docs/extension-author-guide/create-extension/why-dockerfiles.md @@ -71,18 +71,23 @@ Note that `--network host` is necessary when publishing to a local registry. You should see: ``` +... [detector] ======== Results ======== [detector] pass: samples/tree@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/tree@0.0.1 provides unused tree -[detector] 1 of 2 buildpacks participating +[detector] skip: samples/curl@0.0.1 provides unused curl +[detector] skip: samples/cowsay@0.0.1 provides unused cowsay +[detector] 1 of 4 buildpacks participating [detector] samples/hello-extensions 0.0.1 ... -[extender] Running build command -[extender] ---> Hello Extensions Buildpack -[extender] /cnb/buildpacks/samples_hello-extensions/0.0.1/bin/build: line 6: tree: command not found -[extender] ERROR: failed to build: exit status 127 +[extender (build)] Running build command +[extender (build)] ---> Hello Extensions Buildpack +[extender (build)] /cnb/buildpacks/samples_hello-extensions/0.0.1/bin/build: line 6: tree: command not found +[extender (build)] ERROR: failed to build: exit status 127 ``` What happened: our builder doesn't have `tree` installed, so the `hello-extensions` buildpack failed to build (as it From 851b2ecd25e57c47def8bc1da766197f912dd694 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 17 Apr 2023 12:28:23 +0200 Subject: [PATCH 03/17] Update run image ref If we're extending the run image it must be in a registry Signed-off-by: Natalie Arellano --- .../create-extension/run-dockerfile-extend.md | 10 ++++++++++ .../create-extension/run-dockerfile-switch.md | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md index 4181add6b..b83cc6679 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md @@ -28,6 +28,16 @@ cat $PWD/samples/extensions/cowsay/bin/generate The extension generates a `run.Dockerfile` that installs `cowsay` on the current run image. +### Push run image to test registry + +Now that we are extending the run image (vs switching it, as in the previous example) it must reside in a registry +so that we can pull its manifest (necessary for the extension process). + + +```bash +docker push localhost:5000/run-image-curl +``` + ### 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 `tree` and `curl` (review the `./bin/detect` script to see why this works). diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md index beb5fbe43..dfe7e5bc7 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md @@ -46,7 +46,7 @@ Build the run image: ```bash docker build \ --file $PWD/samples/stacks/alpine/run/curl.Dockerfile \ - --tag run-image-curl . + --tag localhost:5000/run-image-curl . ``` ### Configure the `hello-extensions` buildpack to require `curl` @@ -86,7 +86,7 @@ You should see: [detector] Running generate for extension samples/curl@0.0.1 ... [detector] Checking for new run image -[detector] Found a run.Dockerfile from extension 'samples/curl' setting run image to 'run-image-curl' +[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/tree' [extender (build)] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... From ed41a6c89a4a1cee9b9befece10c6c66fc0a0aae Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 17 Apr 2023 12:30:48 +0200 Subject: [PATCH 04/17] Temporary changes for pre-release When both pack & lifecycle are released and the samples are updated, we can revert this commit Signed-off-by: Natalie Arellano --- .../create-extension/setup-local-environment.md | 4 ++++ .../create-extension/why-dockerfiles.md | 9 +++++++++ 2 files changed, 13 insertions(+) diff --git a/content/docs/extension-author-guide/create-extension/setup-local-environment.md b/content/docs/extension-author-guide/create-extension/setup-local-environment.md index 0445dfc8a..857938543 100644 --- a/content/docs/extension-author-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-author-guide/create-extension/setup-local-environment.md @@ -54,6 +54,9 @@ pack version The version should be at least `0.28.0` +**Note**: to follow this demo all the way through to the end (including run image extension), +the pack version should be at least `0.30.0-pre2`. Consult the [releases page](https://github.com/buildpacks/pack/releases) for more information. + ### Update pack configuration @@ -70,6 +73,7 @@ We unset any custom lifecycle image that may have been provided to ensure that t ```bash git clone https://github.com/buildpacks/samples.git +git checkout runext/update-samples # FIXME: remove when https://github.com/buildpacks/samples/pull/149 is merged ``` diff --git a/content/docs/extension-author-guide/create-extension/why-dockerfiles.md b/content/docs/extension-author-guide/create-extension/why-dockerfiles.md index 3406a424b..ad02bebbc 100644 --- a/content/docs/extension-author-guide/create-extension/why-dockerfiles.md +++ b/content/docs/extension-author-guide/create-extension/why-dockerfiles.md @@ -43,6 +43,15 @@ docker run -d --rm -p 5000:5000 registry:2 You can push the builder to any registry of your choice - just ensure that `docker login` succeeds and replace `localhost:5000` in the following examples with your registry namespace - e.g., `index.docker.io/`. +**Note**: to follow this demo all the way through to the end (including run image extension), you will need a pre-release version of the lifecycle. +* Download the `.tgz` file for your os/arch from the [releases page](https://github.com/buildpacks/lifecycle/releases) +* Add the following lines to `$PWD/samples/builders/alpine/builder.toml`: + +```bash +[lifecycle] +uri = +``` + Create the builder: From 7daeececd708944e83d685e0866c33c0935978d1 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 17 Apr 2023 12:40:13 +0200 Subject: [PATCH 05/17] Update all run image references to include the registry Signed-off-by: Natalie Arellano --- .../create-extension/run-dockerfile-extend.md | 2 +- .../create-extension/run-dockerfile-switch.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md index b83cc6679..165f8a51d 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-extend.md @@ -76,7 +76,7 @@ You should see: ... [detector] Running generate for extension samples/cowsay@0.0.1 ... -[detector] Found a run.Dockerfile from extension 'samples/curl' setting run image to 'run-image-curl' +[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/tree' [extender (build)] Applying Dockerfile at /layers/generated/build/samples_tree/Dockerfile... diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md index dfe7e5bc7..6a565355c 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md @@ -27,7 +27,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 @@ -114,7 +114,7 @@ curl 7.85.0-DEV (x86_64-pc-linux-musl) ... more stuff here ... What happened: now that `hello-extensions` requires both `tree` and `curl` in its build plan, both extensions are included in the build and provide the needed dependencies for build and launch, respectively * The `tree` extension installs `tree` 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! @@ -132,7 +132,7 @@ You should see: ERROR: failed to launch: path lookup: exec: "cowsay": executable file not found in $PATH ``` -Our run image, `run-image-curl`, has `curl` installed, but it doesn't have `cowsay`. +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. From 241eef3d404fd6b7ea30ffd839e52ae5d88244c4 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 17 Apr 2023 13:22:40 +0200 Subject: [PATCH 06/17] Make demo copy/pastable Signed-off-by: Natalie Arellano --- .../create-extension/build-dockerfile.md | 2 +- .../create-extension/setup-local-environment.md | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/content/docs/extension-author-guide/create-extension/build-dockerfile.md b/content/docs/extension-author-guide/create-extension/build-dockerfile.md index ee377009c..7e0395c7d 100644 --- a/content/docs/extension-author-guide/create-extension/build-dockerfile.md +++ b/content/docs/extension-author-guide/create-extension/build-dockerfile.md @@ -93,5 +93,5 @@ Let's take a look at how the `samples/curl` extension fixes the error by switchi --- -Next Step +Next Step diff --git a/content/docs/extension-author-guide/create-extension/setup-local-environment.md b/content/docs/extension-author-guide/create-extension/setup-local-environment.md index 857938543..0f7f63dfa 100644 --- a/content/docs/extension-author-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-author-guide/create-extension/setup-local-environment.md @@ -72,8 +72,11 @@ We unset any custom lifecycle image that may have been provided to ensure that t ```bash -git clone https://github.com/buildpacks/samples.git -git checkout runext/update-samples # FIXME: remove when https://github.com/buildpacks/samples/pull/149 is merged +# FIXME: remove branch when https://github.com/buildpacks/samples/pull/149 is merged +git clone https://github.com/buildpacks/samples.git && \ + cd samples && \ + git checkout runext/update-samples && \ + cd .. ``` From 22e964ec94db2b4317a16ff7f70494d75e2869f5 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 17 Apr 2023 13:38:55 +0200 Subject: [PATCH 07/17] Fix link Signed-off-by: Natalie Arellano --- .../create-extension/run-dockerfile-switch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md index 6a565355c..49d6c4834 100644 --- a/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md +++ b/content/docs/extension-author-guide/create-extension/run-dockerfile-switch.md @@ -140,5 +140,5 @@ Luckily, we can also use image extensions to dynamically install runtime depende --- -Next Step +Next Step From 79ab9738f5a87da517137900fab69a42b31eb9c3 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 7 Jul 2023 15:07:48 -0400 Subject: [PATCH 08/17] Fix: fetch branch of samples that we're using Signed-off-by: Natalie Arellano --- .../extension-guide/create-extension/setup-local-environment.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/extension-guide/create-extension/setup-local-environment.md b/content/docs/extension-guide/create-extension/setup-local-environment.md index 287175cb7..1a5c2136a 100644 --- a/content/docs/extension-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-guide/create-extension/setup-local-environment.md @@ -78,6 +78,7 @@ We unset any custom lifecycle image that may have been provided to ensure that t # FIXME: remove branch when https://github.com/buildpacks/samples/pull/149 is merged git clone https://github.com/buildpacks/samples.git && \ cd samples && \ + git fetch origin runext/update-samples && \ git checkout runext/update-samples && \ cd .. ``` From 7be27df8bdaa58feebd832da8cd43e418059f48b Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 7 Jul 2023 15:09:07 -0400 Subject: [PATCH 09/17] Bump pack version referenced Signed-off-by: Natalie Arellano --- .../extension-guide/create-extension/setup-local-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/extension-guide/create-extension/setup-local-environment.md b/content/docs/extension-guide/create-extension/setup-local-environment.md index 1a5c2136a..90751f397 100644 --- a/content/docs/extension-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-guide/create-extension/setup-local-environment.md @@ -58,7 +58,7 @@ pack version The version should be at least `0.28.0` **Note**: to follow this demo all the way through to the end (including run image extension), -the pack version should be at least `0.30.0-pre2`. Consult the [releases page](https://github.com/buildpacks/pack/releases) for more information. +the pack version should be at least `0.30.0-rc1`. Consult the [releases page](https://github.com/buildpacks/pack/releases) for more information. ### Update pack configuration From d550edd318bdcde5f76b57d6b4aee3bba0df3aa8 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 7 Jul 2023 15:14:37 -0400 Subject: [PATCH 10/17] Just require pack 0.30.0 since that is needed for run image extension Signed-off-by: Natalie Arellano --- .../create-extension/setup-local-environment.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/content/docs/extension-guide/create-extension/setup-local-environment.md b/content/docs/extension-guide/create-extension/setup-local-environment.md index 90751f397..2b206f787 100644 --- a/content/docs/extension-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-guide/create-extension/setup-local-environment.md @@ -55,10 +55,7 @@ cd pack version ``` -The version should be at least `0.28.0` - -**Note**: to follow this demo all the way through to the end (including run image extension), -the pack version should be at least `0.30.0-rc1`. Consult the [releases page](https://github.com/buildpacks/pack/releases) for more information. +The version should be at least `0.30.0` ### Update pack configuration From ab711532cd9b4e2df4eb326c3887fd16670e0cfa Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 25 Jul 2023 12:40:24 -0400 Subject: [PATCH 11/17] Bump pack in docs CI Signed-off-by: Natalie Arellano --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b3760be39..f3b3945db 100644 --- a/.github/workflows/main.yml +++ b/.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.28.0' + pack-version: '0.30.0-pre3' # FIXME: update to 0.30.0 when available - name: Test run: make test env: From c0dd6c5ffa25d2d353e5c3416481f7049cb35070 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 25 Jul 2023 15:17:34 -0400 Subject: [PATCH 12/17] Update docs to use vim sample instead of tree Signed-off-by: Natalie Arellano --- .../create-extension/build-dockerfile.md | 28 +++++++++--------- .../building-blocks-extension.md | 8 ++--- .../create-extension/run-dockerfile-extend.md | 16 +++++----- .../create-extension/run-dockerfile-switch.md | 22 +++++++------- .../setup-local-environment.md | 2 +- .../create-extension/why-dockerfiles.md | 29 +++++++------------ 6 files changed, 49 insertions(+), 56 deletions(-) diff --git a/content/docs/extension-guide/create-extension/build-dockerfile.md b/content/docs/extension-guide/create-extension/build-dockerfile.md index 1a505593e..d8653ce24 100644 --- a/content/docs/extension-guide/create-extension/build-dockerfile.md +++ b/content/docs/extension-guide/create-extension/build-dockerfile.md @@ -11,36 +11,36 @@ aliases = [ Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies for the current application. -### Examine `tree` extension +### Examine `vim` extension #### detect ```bash -cat $PWD/samples/extensions/tree/bin/detect +cat $PWD/samples/extensions/vim/bin/detect ``` -The extension always detects (because its exit code is `0`) and provides a dependency called `tree` by writing to the build plan. +The extension always detects (because its exit code is `0`) and provides a dependency called `vim` by writing to the build plan. #### generate ```bash -cat $PWD/samples/extensions/tree/bin/generate +cat $PWD/samples/extensions/vim/bin/generate ``` -The extension generates a `build.Dockerfile` that installs `tree` on the builder image. +The extension generates a `build.Dockerfile` that installs `vim` on the builder image. -### Configure the `hello-extensions` buildpack to require `tree` +### Configure the `hello-extensions` buildpack to require `vim` -Set the `BP_REQUIRES` build-time environment variable to configure the `hello-extensions` buildpack to require `tree` (review the `./bin/detect` script to see why this works). +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). ``` pack build hello-extensions \ --builder localhost:5000/extensions-builder \ --env BP_EXT_DEMO=1 \ - --env BP_REQUIRES=tree \ + --env BP_REQUIRES=vim \ --network host \ --path $PWD/samples/apps/java-maven \ --pull-policy always \ @@ -54,7 +54,7 @@ You should see: ``` ... [detector] ======== Results ======== -[detector] pass: samples/tree@0.0.1 +[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 @@ -62,16 +62,16 @@ You should see: [detector] skip: samples/curl@0.0.1 provides unused curl [detector] skip: samples/cowsay@0.0.1 provides unused cowsay [detector] 2 of 4 buildpacks participating -[detector] samples/tree 0.0.1 +[detector] samples/vim 0.0.1 [detector] samples/hello-extensions 0.0.1 -[detector] Running generate for extension samples/tree@0.0.1 +[detector] Running generate for extension samples/vim@0.0.1 ... -[extender (build)] Found build Dockerfile for extension 'samples/tree' -[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... +[extender (build)] Found build Dockerfile for extension 'samples/vim' +[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_vim/Dockerfile... ... [extender (build)] Running build command [extender (build)] ---> Hello Extensions Buildpack -[extender (build)] tree v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro +[extender (build)] VIM - Vi IMproved 9.0 (2022 Jun 28, compiled May 19 2023 16:28:36) ... Successfully built image hello-extensions ``` diff --git a/content/docs/extension-guide/create-extension/building-blocks-extension.md b/content/docs/extension-guide/create-extension/building-blocks-extension.md index e08c94148..ad17bfa4b 100644 --- a/content/docs/extension-guide/create-extension/building-blocks-extension.md +++ b/content/docs/extension-guide/create-extension/building-blocks-extension.md @@ -8,14 +8,14 @@ aliases = [ -### Examine `tree` extension +### Examine `vim` extension ```bash -tree $PWD/samples/extensions/tree +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: ``` . @@ -44,7 +44,7 @@ tree $PWD/samples/extensions/tree the [spec](https://github.com/buildpacks/spec/blob/buildpack/main/image_extension.md) for further details. -We'll take a closer look at the executables for the `tree` extension in the next step. +We'll take a closer look at the executables for the `vim` extension in the next step. --- diff --git a/content/docs/extension-guide/create-extension/run-dockerfile-extend.md b/content/docs/extension-guide/create-extension/run-dockerfile-extend.md index 165f8a51d..2ade60842 100644 --- a/content/docs/extension-guide/create-extension/run-dockerfile-extend.md +++ b/content/docs/extension-guide/create-extension/run-dockerfile-extend.md @@ -40,14 +40,14 @@ docker push localhost:5000/run-image-curl ### 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 `tree` and `curl` (review the `./bin/detect` script to see why this works). +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). ```bash pack build hello-extensions \ --builder localhost:5000/extensions-builder \ --env BP_EXT_DEMO=1 \ - --env BP_REQUIRES=tree,curl,cowsay \ + --env BP_REQUIRES=vim,curl,cowsay \ --path $PWD/samples/apps/java-maven \ --pull-policy always \ --network host \ @@ -61,16 +61,16 @@ You should see: ``` ... [detector] ======== Results ======== -[detector] pass: samples/tree@0.0.1 +[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/tree 0.0.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/tree@0.0.1 +[detector] Running generate for extension samples/vim@0.0.1 ... [detector] Running generate for extension samples/curl@0.0.1 ... @@ -78,8 +78,8 @@ You should see: ... [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/tree' -[extender (build)] Applying Dockerfile at /layers/generated/build/samples_tree/Dockerfile... +[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... @@ -88,7 +88,7 @@ You should see: ... [extender (build)] Running build command [extender (build)] ---> Hello Extensions Buildpack -[extender (build)] tree v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro +[extender (build)] VIM - Vi IMproved 9.0 (2022 Jun 28, compiled May 19 2023 16:28:36) ... Successfully built image hello-extensions ``` diff --git a/content/docs/extension-guide/create-extension/run-dockerfile-switch.md b/content/docs/extension-guide/create-extension/run-dockerfile-switch.md index 120d910a1..9c36b3ee3 100644 --- a/content/docs/extension-guide/create-extension/run-dockerfile-switch.md +++ b/content/docs/extension-guide/create-extension/run-dockerfile-switch.md @@ -50,18 +50,20 @@ 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 ``` ### 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 `tree` and `curl` (review the `./bin/detect` script to see why this works). +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). ```bash pack build hello-extensions \ --builder localhost:5000/extensions-builder \ --env BP_EXT_DEMO=1 \ - --env BP_REQUIRES=tree,curl \ + --env BP_REQUIRES=vim,curl \ --path $PWD/samples/apps/java-maven \ --pull-policy always \ --network host \ @@ -74,29 +76,29 @@ You should see: ``` [detector] ======== Results ======== -[detector] pass: samples/tree@0.0.1 +[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/tree 0.0.1 +[detector] samples/vim 0.0.1 [detector] samples/curl 0.0.1 [detector] samples/hello-extensions 0.0.1 -[detector] Running generate for extension samples/tree@0.0.1 +[detector] Running generate for extension samples/vim@0.0.1 ... [detector] Running generate for extension samples/curl@0.0.1 ... [detector] Checking for new run image [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/tree' -[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_tree/Dockerfile... +[extender (build)] Found build Dockerfile for extension 'samples/vim' +[extender (build)] Applying the Dockerfile at /layers/generated/build/samples_vim/Dockerfile... ... [extender (build)] Running build command [extender (build)] ---> Hello Extensions Buildpack -[extender (build)] tree v1.8.0 (c) 1996 - 2018 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro +[extender (build)] VIM - Vi IMproved 9.0 (2022 Jun 28, compiled May 19 2023 16:28:36) ... Successfully built image hello-extensions ``` @@ -114,9 +116,9 @@ You should see something akin to: curl 7.85.0-DEV (x86_64-pc-linux-musl) ... more stuff here ... ``` -What happened: now that `hello-extensions` requires both `tree` and `curl` in its build plan, both extensions are +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 `tree` extension installs `tree` at build time, as before +* The `vim` extension installs `vim` at build time, as before * The `curl` extension switches the run image to `localhost:5000/run-image-curl`, which has `curl` installed Now our `curl` process can succeed! diff --git a/content/docs/extension-guide/create-extension/setup-local-environment.md b/content/docs/extension-guide/create-extension/setup-local-environment.md index 2b206f787..9324ce5f8 100644 --- a/content/docs/extension-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-guide/create-extension/setup-local-environment.md @@ -75,7 +75,7 @@ We unset any custom lifecycle image that may have been provided to ensure that t # FIXME: remove branch when https://github.com/buildpacks/samples/pull/149 is merged git clone https://github.com/buildpacks/samples.git && \ cd samples && \ - git fetch origin runext/update-samples && \ + git fetch --all && \ git checkout runext/update-samples && \ cd .. ``` diff --git a/content/docs/extension-guide/create-extension/why-dockerfiles.md b/content/docs/extension-guide/create-extension/why-dockerfiles.md index 7584009f0..ef8d02437 100644 --- a/content/docs/extension-guide/create-extension/why-dockerfiles.md +++ b/content/docs/extension-guide/create-extension/why-dockerfiles.md @@ -30,7 +30,7 @@ If the `BP_EXT_DEMO` environment variable is set, the buildpack detects (exits w cat $PWD/samples/buildpacks/hello-extensions/bin/build ``` -The buildpack tries to use `tree` at build-time, and defines a launch process called `curl` that runs `curl --version` at runtime. +The buildpack tries to use `vim` at build-time, and defines a launch process called `curl` that runs `curl --version` at runtime. ### Create a builder with extensions and publish it @@ -46,15 +46,6 @@ docker run -d --rm -p 5000:5000 registry:2 You can push the builder to any registry of your choice - just ensure that `docker login` succeeds and replace `localhost:5000` in the following examples with your registry namespace - e.g., `index.docker.io/`. -**Note**: to follow this demo all the way through to the end (including run image extension), you will need a pre-release version of the lifecycle. -* Download the `.tgz` file for your os/arch from the [releases page](https://github.com/buildpacks/lifecycle/releases) -* Add the following lines to `$PWD/samples/builders/alpine/builder.toml`: - -```bash -[lifecycle] -uri = -``` - Create the builder: @@ -85,12 +76,12 @@ You should see: ``` ... [detector] ======== Results ======== -[detector] pass: samples/tree@0.0.1 +[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/tree@0.0.1 provides unused tree +[detector] skip: samples/vim@0.0.1 provides unused vim [detector] skip: samples/curl@0.0.1 provides unused curl [detector] skip: samples/cowsay@0.0.1 provides unused cowsay [detector] 1 of 4 buildpacks participating @@ -98,18 +89,18 @@ You should see: ... [extender (build)] Running build command [extender (build)] ---> Hello Extensions Buildpack -[extender (build)] /cnb/buildpacks/samples_hello-extensions/0.0.1/bin/build: line 6: tree: command not found +[extender (build)] /cnb/buildpacks/samples_hello-extensions/0.0.1/bin/build: line 6: vim: command not found [extender (build)] ERROR: failed to build: exit status 127 ``` -What happened: our builder doesn't have `tree` installed, so the `hello-extensions` buildpack failed to build (as it -tries to run `tree --version` in its `./bin/build` script). +What happened: our builder doesn't have `vim` installed, so the `hello-extensions` buildpack failed to build (as it +tries to run `vim --version` in its `./bin/build` script). -Even though there is a `samples/tree` extension that passed detection (`pass: samples/tree@0.0.1`), because -the `hello-extensions` buildpack didn't require `tree` in the build plan, the extension was omitted from the detected -group (`skip: samples/tree@0.0.1 provides unused tree`). +Even though there is a `samples/vim` extension that passed detection (`pass: samples/vim@0.0.1`), because +the `hello-extensions` buildpack didn't require `vim` in the build plan, the extension was omitted from the detected +group (`skip: samples/vim@0.0.1 provides unused vim`). -Let's take a look at how the `samples/tree` extension installs `tree` on the builder image... +Let's take a look at how the `samples/vim` extension installs `vim` on the builder image... --- From 801594a47deed63a0dc5ea842617c1c625264437 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 28 Jul 2023 15:35:53 -0400 Subject: [PATCH 13/17] Remove instruction to push run image to local registry We pushed it in an earlier step Signed-off-by: Natalie Arellano --- .../create-extension/run-dockerfile-extend.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/content/docs/extension-guide/create-extension/run-dockerfile-extend.md b/content/docs/extension-guide/create-extension/run-dockerfile-extend.md index 2ade60842..fce8b3b8c 100644 --- a/content/docs/extension-guide/create-extension/run-dockerfile-extend.md +++ b/content/docs/extension-guide/create-extension/run-dockerfile-extend.md @@ -28,16 +28,6 @@ cat $PWD/samples/extensions/cowsay/bin/generate The extension generates a `run.Dockerfile` that installs `cowsay` on the current run image. -### Push run image to test registry - -Now that we are extending the run image (vs switching it, as in the previous example) it must reside in a registry -so that we can pull its manifest (necessary for the extension process). - - -```bash -docker push localhost:5000/run-image-curl -``` - ### 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). From ef3cc5c0bf6bd7a8ad02691891265503f72719d6 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 7 Aug 2023 12:38:22 -0400 Subject: [PATCH 14/17] Bump pack version Signed-off-by: Natalie Arellano --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f3b3945db..89ef65ffd 100644 --- a/.github/workflows/main.yml +++ b/.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-pre3' # FIXME: update to 0.30.0 when available + pack-version: '0.30.0-rc1' # FIXME: update to 0.30.0 when available - name: Test run: make test env: From e1c1ffbd14383d23bc1491df1771b3f62028c181 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 8 Aug 2023 13:16:26 -0400 Subject: [PATCH 15/17] Remove FIXME Signed-off-by: Natalie Arellano --- .../create-extension/setup-local-environment.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/content/docs/extension-guide/create-extension/setup-local-environment.md b/content/docs/extension-guide/create-extension/setup-local-environment.md index 9324ce5f8..74daf7fb1 100644 --- a/content/docs/extension-guide/create-extension/setup-local-environment.md +++ b/content/docs/extension-guide/create-extension/setup-local-environment.md @@ -72,12 +72,7 @@ We unset any custom lifecycle image that may have been provided to ensure that t ```bash -# FIXME: remove branch when https://github.com/buildpacks/samples/pull/149 is merged -git clone https://github.com/buildpacks/samples.git && \ - cd samples && \ - git fetch --all && \ - git checkout runext/update-samples && \ - cd .. +git clone https://github.com/buildpacks/samples.git ``` From 5a96a9e6032f864c87b7e30fa1c0a5ac45d9b82e Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 8 Aug 2023 13:30:00 -0400 Subject: [PATCH 16/17] Fix broken link Signed-off-by: Natalie Arellano --- content/docs/extension-guide/create-extension/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/extension-guide/create-extension/_index.md b/content/docs/extension-guide/create-extension/_index.md index 4a9144184..2ec44ee1d 100644 --- a/content/docs/extension-guide/create-extension/_index.md +++ b/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) --- From bfe3c08c8d330cf1133accd8f6a4f616c03f2eab Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 10 Aug 2023 17:35:36 -0400 Subject: [PATCH 17/17] Remove notes about things not being implemented that are now implemented Signed-off-by: Natalie Arellano --- .../building-blocks-extension.md | 5 --- content/docs/features/dockerfiles.md | 32 +++---------------- 2 files changed, 5 insertions(+), 32 deletions(-) diff --git a/content/docs/extension-guide/create-extension/building-blocks-extension.md b/content/docs/extension-guide/create-extension/building-blocks-extension.md index b577e4d6e..3cd2322b4 100644 --- a/content/docs/extension-guide/create-extension/building-blocks-extension.md +++ b/content/docs/extension-guide/create-extension/building-blocks-extension.md @@ -38,11 +38,6 @@ You should see something akin to the following: * 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. diff --git a/content/docs/features/dockerfiles.md b/content/docs/features/dockerfiles.md index 0919f03a9..705113c7e 100644 --- a/content/docs/features/dockerfiles.md +++ b/content/docs/features/dockerfiles.md @@ -56,8 +56,7 @@ An image extension could be defined with the following directory: * `./bin/detect` is invoked during the `detect` phase. It analyzes application source code to determine if the extension is needed and contributes build plan entries. * `./bin/generate` is invoked during the `generate` phase (a new lifecycle phase that happens after `detect`). It - outputs either or both of `build.Dockerfile` or `run.Dockerfile` for extending the builder or run image, - respectively (in the [initial implementation](#phased-approach), only limited `run.Dockerfile`s are allowed). + outputs either or both of `build.Dockerfile` or `run.Dockerfile` for extending the builder or run image. For more information and to see a build in action, see [authoring an image extension](/docs/extension-guide/create-extension). @@ -78,30 +77,9 @@ should be **used with great care**. Platform operators should be mindful that: may not have all the mixins required by buildpacks that detected. Platforms may wish to optionally re-validate mixins prior to `build` when using extensions. -### Phased approach +### Putting it all together -Some limitations of the initial implementation of the Dockerfiles feature have already been mentioned, and we'll expand -on them here. As this is a large and complicated feature, the implementation has been split into phases in order to -deliver incremental value and gather feedback. - -#### Phase 1 (supported in lifecycle `0.15.0` or greater) - -One or more `run.Dockerfile`s each containing a single `FROM` instruction can be used to switch the original run image -to a new image (as no image modifications are permitted, there is no need to run `extend` on the run image) - -#### Phase 2 (supported in lifecycle `0.15.0` or greater) - -One or more `build.Dockerfile`s can be used to extend the builder image - -* A new `extend` lifecycle phase is introduced to apply `build.Dockerfile`s from `generate` to the builder image - -#### Phase 3 (future) - -One or more `run.Dockerfile`s can be used to extend the run image - -* The `extend` lifecycle phase can be run in parallel for the builder and run images - -The final ordering of lifecycle phases will look something like the following: +The ordering of lifecycle phases looks like the following: * `analyze` * `detect` - after standard detection, `detect` will also run extensions' `./bin/generate`; output Dockerfiles are @@ -116,9 +94,9 @@ For more information, consult the [migration guide](/docs/reference/spec/migrati #### Platform support for Dockerfiles -Supported (phases 1 and 2): +Supported: -* [pack cli](https://github.com/buildpacks/pack) (version `0.28.0` and above) +* [pack cli](https://github.com/buildpacks/pack) (prefer version `0.30.0` and above) Needs support: