Merge pull request cds-hooks#527 from buildpacks/extensions-phase-2-rc2

Docs for Dockerfiles

Author: AidanDelaney

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

@@ -0,0 +1,9 @@
++++
+title="Extension Author Guide"
+weight=4
+include_summaries=true
+expand=true
+aliases=[
+    "/docs/create-extension/"
+]
++++

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

@@ -0,0 +1,30 @@
++++
+title="Create an extension"
+weight=4
+summary="This is a step-by-step tutorial for creating and using CNB image extensions"
++++
+
+<!--+if false+-->
+## Prerequisites
+
+Before we get started, make sure you've got the following installed:
+
+{{< download-button href="https://store.docker.com/search?type=edition&offering=community" color="blue" >}} Install Docker {{</>}}
+{{< download-button href="/docs/install-pack" color="pink" >}} Install pack {{</>}}
+
+## Overview
+<!--+end+-->
+
+This is a step-by-step tutorial for creating and using CNB image extensions.
+
+- [Set up your local environment](/docs/extension-author-guide/create-extension/setup-local-environment)
+- [See a build that requires base image extension in order to succeed](/docs/extension-author-guide/create-extension/why-dockerfiles)
+- [Building blocks of an extension](/docs/extension-author-guide/create-extension/building-blocks-extension)
+- [Generating a build.Dockerfile for your application](/docs/extension-author-guide/create-extension/build-dockerfile)
+- [Generating a run.Dockerfile for your application](/docs/extension-author-guide/create-extension/run-dockerfile)
+
+<!--+if false+-->
+---
+
+<a href="/docs/extension-author-guide/create-extension/setup-local-environment" class="button bg-pink">Start Tutorial</a>
+<!--+end+-->

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

@@ -0,0 +1,104 @@
++++
+title="Generating a build.Dockerfile"
+weight=404
++++
+
+<!-- test:suite=dockerfiles;weight=4 -->
+
+### Examine `tree` extension
+
+#### detect
+
+<!-- test:exec -->
+```bash
+cat $PWD/samples/extensions/tree/bin/detect
+```
+
+The extension always detects (because its exit code is `0`) and provides a dependency called `tree` by writing to the build plan.
+
+#### generate
+
+<!-- test:exec -->
+```bash
+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`
+
+Edit `$PWD/samples/buildpacks/hello-extensions/bin/detect` to uncomment the first set of lines that output `[[requires]]` to the build plan:
+
+<!-- test:exec -->
+```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:
+
+<!-- test:exec -->
+```
+pack builder create localhost:5000/extensions-builder \
+  --config $PWD/samples/builders/alpine/builder.toml \
+  --publish
+```
+
+### Re-build the application image
+
+<!-- test:exec -->
+```
+pack build hello-extensions \
+  --builder localhost:5000/extensions-builder \
+  --network host \
+  --path $PWD/samples/apps/java-maven \
+  --pull-policy always \
+  --verbose
+```
+
+Note that `--network host` is necessary when publishing to a local registry.
+
+You should see:
+
+```
+[detector] ======== Results ========
+[detector] pass: samples/[email protected]
+[detector] pass: samples/[email protected]
+[detector] Resolving plan... (try #1)
+[detector] samples/tree             0.0.1
+[detector] samples/hello-extensions 0.0.1
+[detector] Running generate for extension samples/[email protected]
+...
+[extender] Found build Dockerfile for extension 'samples/tree'
+[extender] 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
+...
+Successfully built image hello-extensions
+```
+
+### See the image fail to run
+
+```
+docker run --rm hello-extensions
+```
+
+You should see:
+
+```
+ERROR: failed to launch: path lookup: exec: "curl": executable file not found in $PATH
+```
+
+What happened: our builder uses run image `cnbs/sample-stack-run:alpine`, which does not have `curl` installed, so our
+  process failed to launch.
+
+Let's take a look at how the `samples/curl` extension fixes the error by switching the run image to another image...
+
+<!--+ if false+-->
+---
+
+<a href="/docs/extension-author-guide/create-extension/run-dockerfile" class="button bg-pink">Next Step</a>
+<!--+ end +-->

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

@@ -0,0 +1,50 @@
++++
+title="Building blocks of a CNB Image Extension"
+weight=403
++++
+
+<!-- test:suite=dockerfiles;weight=3 -->
+
+### Examine `tree` extension
+
+<!-- test:exec -->
+```bash
+tree $PWD/samples/extensions/tree
+```
+
+(That's right, we're using the very tool we will later be installing!) You should see something akin to the following:
+
+```
+.
+├── bin
+│   ├── detect     <- similar to a buildpack ./bin/detect
+│   ├── generate   <- similar to a buildpack ./bin/build
+├── extension.toml <- similar to a buildpack buildpack.toml
+```
+
+* The `extension.toml` describes the extension, containing information such as its name, ID, and version, as well as the
+  buildpack API that it implements. Though extensions are not buildpacks, they are expected to conform to the buildpack
+  API except where noted. Consult the [spec](https://github.com/buildpacks/spec/blob/buildpack/main/image_extension.md)
+  for further details.
+* `./bin/detect` is invoked during the `detect` phase. It analyzes application source code to determine if the extension
+  is needed and contributes [build plan](/docs/reference/spec/buildpack-api/#build-plan) entries (much like a
+  buildpack `./bin/detect`). Just like for buildpacks, a `./bin/detect` that exits with code `0` is considered to have
+  passed detection, and fails otherwise.
+* `./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.
+  * Only a limited set of Dockerfile instructions is supported - consult
+    the [spec](https://github.com/buildpacks/spec/blob/buildpack/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/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.
+
+<!--+ if false+-->
+---
+
+<a href="/docs/extension-author-guide/create-extension/build-dockerfile" class="button bg-pink">Next Step</a>
+<!--+ end +-->

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

@@ -0,0 +1,142 @@
++++
+title="Generating a run.Dockerfile"
+weight=405
++++
+
+<!-- test:suite=dockerfiles;weight=5 -->
+
+### Examine `curl` extension
+
+#### detect
+
+<!-- test:exec -->
+```bash
+cat $PWD/samples/extensions/curl/bin/detect
+```
+
+The extension always detects (because its exit code is `0`) and provides a dependency called `curl`.
+
+#### generate
+
+<!-- test:exec -->
+```bash
+cat $PWD/samples/extensions/curl/bin/generate
+```
+
+The extension generates a `run.Dockerfile` that switches the run image to reference `run-image-curl`.
+
+### Build a run image for `curl` extension to use
+
+<!-- test:exec -->
+```bash
+cat $PWD/samples/stacks/alpine/run/curl.Dockerfile
+```
+
+This is a simple Dockerfile that creates a CNB run image from the `curl` base image by adding the required CNB user configuration and `io.buildpacks.stack.id` label.
+
+The Dockerfile could come from anywhere, but we include it in the `stacks` directory for convenience.
+
+Build the run image:
+
+<!-- test:exec -->
+```bash
+docker build \
+  --file $PWD/samples/stacks/alpine/run/curl.Dockerfile \
+  --tag run-image-curl .
+```
+
+### Re-create our builder with `hello-extensions` updated 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:
+
+<!-- test:exec -->
+```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:
+
+<!-- test:exec -->
+```bash
+pack builder create localhost:5000/extensions-builder \
+  --config $PWD/samples/builders/alpine/builder.toml \
+  --publish
+```
+
+### Re-build the application image
+
+<!-- test:exec -->
+```bash
+pack build hello-extensions \
+  --builder localhost:5000/extensions-builder \
+  --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/[email protected]
+[detector] pass: samples/[email protected]
+[detector] pass: samples/[email protected]
+[detector] Resolving plan... (try #1)
+[detector] samples/tree             0.0.1
+[detector] samples/curl             0.0.1
+[detector] samples/hello-extensions 0.0.1
+[detector] Running generate for extension samples/[email protected]
+...
+[detector] Running generate for extension samples/[email protected]
+...
+[detector] Checking for new run image
+[detector] Found a run.Dockerfile configuring image 'run-image-curl' from extension with id 'samples/curl'
+...
+[extender] Found build Dockerfile for extension 'samples/tree'
+[extender] 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
+...
+Successfully built image hello-extensions
+```
+
+### See the image run successfully
+
+<!-- test:exec -->
+```bash
+docker run --rm hello-extensions
+```
+
+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
+  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
+
+Now our `curl` process can succeed!
+
+## What's next?
+
+The `tree` and `curl` examples are very simple, but we can unlock powerful new features with this functionality.
+
+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.
+
+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.