Merge branch 'main' into dependabot/github_actions/buildpacks/github-actions-5.5.3

Author: AidanDelaney

.github/workflows/main.yml

@@ -52,7 +52,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Download public folder
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: public
           path: ./public

config.toml

@@ -91,3 +91,29 @@ featureKatacoda = false
   [security.http]
     methods = ['(?i)GET|POST']
     urls = ['.*']
+
+# For more information, see https://gohugo.io/getting-started/directory-structure/#union-file-system
+[[module.mounts]]
+    source = 'content'
+    target = 'content'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/buildpack.md'
+    target = 'content/docs/for-app-developers/concepts/buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/buildpack.md'
+    target = 'content/docs/for-buildpack-authors/concepts/buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/buildpack.md'
+    target = 'content/docs/for-platform-operators/concepts/buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/extension.md'
+    target = 'content/docs/for-buildpack-authors/concepts/extension.md'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/extension.md'
+    target = 'content/docs/for-platform-operators/concepts/extension.md'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/composite-buildpack.md'
+    target = 'content/docs/for-buildpack-authors/concepts/composite-buildpack.md'
+[[module.mounts]]
+    source = 'content/docs/.common/concepts/composite-buildpack.md'
+    target = 'content/docs/for-platform-operators/concepts/composite-buildpack.md'

content/docs/.common/concepts/buildpack.md

@@ -0,0 +1,54 @@
++++
+title="What is a buildpack?"
+weight=1
++++
+
+A `buildpack` is software that transforms application source code into runnable artifacts
+by analyzing the code and determining the best way to build it.
+
+<!--more-->
+
+![buildpacks](/images/what.svg)
+
+## Why buildpacks?
+
+Buildpacks allow application developers to focus on what they do best - writing code, without having to worry about image security, optimizing container images, or container build strategy.
+
+How much time have you spent struggling to wrangle yet another Dockerfile? Copying and pasting random Dockerfile snippets into every project? Buildpacks can help! They are a better approach to building container images for applications.
+
+## What do they look like?
+
+Typical buildpacks consist of at least three files:
+
+* `buildpack.toml` -- provides metadata about the buildpack, containing information such as its name, ID, and version.
+* `bin/detect` -- performs [detect](#detect).
+* `bin/build` -- performs [build](#build).
+
+## How do they work?
+
+![how](/images/how.svg)
+
+**Each buildpack has two jobs to do**
+
+### Detect
+
+The buildpack determines if it is needed or not.
+
+For example:
+
+- A Python buildpack may look for a `requirements.txt` or a `setup.py` file.
+- A Node buildpack may look for a `package-lock.json` file.
+
+### Build
+
+The buildpack transforms application source code in some way, for example by
+
+- Setting build-time and run-time environment variables.
+- Downloading dependencies.
+- Running source code compilation (if needed).
+- Configuring the application entrypoint and any startup scripts.
+
+For example:
+
+- A Python buildpack may run `pip install -r requirements.txt` if it detected a `requirements.txt` file.
+- A Node buildpack may run `npm install` if it detected a `package-lock.json` file.

content/docs/.common/concepts/composite-buildpack.md

@@ -0,0 +1,10 @@
++++
+title="What is a composite buildpack?"
+weight=99
++++
+
+A composite buildpack, also sometimes called a "meta-buildpack",
+is a buildpack that does not contain any `./bin/detect` or `./bin/build` binaries,
+but instead references other buildpacks in its `buildpack.toml` via the `[[order]]` array.
+
+This is useful for composing more complex detection strategies.

content/docs/.common/concepts/extension.md

@@ -0,0 +1,84 @@
+
++++
+title="What is an image extension?"
+aliases=[
+  "/docs/features/dockerfiles"
+]
+weight=99
++++
+
+An `image extension` is software that generates Dockerfiles that can be used to extend base images for buildpacks builds.
+
+<!--more-->
+
+## Why image extensions?
+
+Buildpacks can do a lot, but there are some things buildpacks can't do. They can't install operating system packages,
+for example. Why not?
+
+Buildpacks do not run as the `root` user and cannot make arbitrary changes to the filesystem. This enhances security,
+enables buildpack interoperability, and preserves the ability to rebase - but it comes at a cost. Base image authors
+must anticipate the OS-level dependencies that will be needed at build and run-time ahead of time, and this isn't always
+possible.
+
+This has been a longstanding source of [discussion](https://github.com/buildpacks/rfcs/pull/173) within the CNB project:
+how can we preserve the benefits of buildpacks while enabling more powerful capabilities?
+
+### Buildpacks and Dockerfiles can work together
+
+Buildpacks are often presented as an alternative to Dockerfiles, but we think buildpacks and Dockerfiles can work
+together.
+
+Buildpacks are optimized for creating layers that are efficient and logically mapped to the dependencies that they
+provide. By contrast, Dockerfiles are the most-used and best-understood mechanism for constructing base images and
+installing OS-level dependencies for containers.
+
+The CNB Dockerfiles feature allows Dockerfiles to "provide" dependencies that buildpacks "require" through a
+shared [build plan], by introducing the concept of image extensions.
+
+## What do they look like?
+
+Image extensions are buildpack-like components that use a restricted `Dockerfile` syntax to expand base images. Their
+purpose is to generate Dockerfiles that can be used to extend the builder or run images prior to buildpacks builds.
+
+An image extension could be defined with the following directory:
+
+```
+.
+├── extension.toml <- similar to a buildpack buildpack.toml
+├── bin
+│   ├── detect     <- similar to a buildpack ./bin/detect
+│   ├── generate   <- similar to a buildpack ./bin/build
+```
+
+* The `extension.toml` provides metadata about the extension, containing information such as its name, ID, and version.
+* `./bin/detect` performs [detect](#detect). It analyzes application source code to determine if the extension
+  is needed and contributes build plan entries.
+* `./bin/generate` performs [generate](#generate) (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.
+
+## How do they work?
+
+**Each image extension has two jobs to do**
+
+### Detect
+
+The extension determines if it is needed or not.
+
+Like buildpacks, extensions participate in the `detect` phase - analyzing application source code to determine if they
+are needed. During `detect`, extensions can contribute to
+the [build plan] - recording dependencies that they are able to "
+provide" (though unlike buildpacks, they can't "require" anything).
+
+If the provided order contains extensions, the output of `detect` will be a group of image extensions and a group of
+buildpacks that together produce a valid build plan. Image extensions only generate Dockerfiles - they don't create
+layers or participate in the `build` phase.
+
+### Generate
+
+The extension outputs Dockerfiles that can be used to extend either or both of the build-time base image and the runtime base image.
+
+For more information and to see a build in action,
+see [authoring an image extension](/docs/for-buildpack-authors/tutorials/basic-extension).
+
+[build plan]: /docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan

content/docs/buildpacks-logo.svg

@@ -11,36 +11,46 @@ The **run image** provides the base image for application images.
 
 <!--more-->
 
-The lifecycle requires a reference to a run image and (where necessary) possible run image mirrors in order to construct the application image.
+CNB tooling requires a reference to a run image and (where necessary) run image mirrors in order to construct the application image.
 
 ### Run image mirrors
 
-Run image mirrors provide alternate locations for run images, for use during `build` or `rebase`.
-When running `build` with a builder containing run image mirrors, `pack` will select a run image
-whose registry location matches that of the specified app image (if no registry host is specified in the image name,
-DockerHub is assumed). This is useful when publishing the resulting app image (via the `--publish` flag or via
-`docker push`), as the app's base image (i.e. run image) will be located on the same registry as the app image itself,
-reducing the amount of data transfer required to push the app image.
+Run image mirrors provide alternate locations for `run images`, for use during `build` or `rebase`.
 
-In the following example, assuming a builder configured with the example TOML above, the selected run image will be
-`registry.example.com/example/run`.
+When run image mirrors are defined, CNB tooling will try to find a run image that resides on the same registry as the application image,
+based on the image name provided.
 
-```bash
-$ pack build registry.example.com/example/app
+This is to reduce the amount of data transfer required to push the application image to a registry.
+
+#### Example - determining the registry
+
+If the application image name is:
+
+* `registry.example.com/example/app` - the registry is `registry.example.com`
+* `example/app` (registry omitted) - Docker Hub is assumed; the registry is `index.docker.io`
+
+#### Example - determining the run image mirror
+
+If your builder has a run image with mirrors defined as follows (see [how to create a builder](/docs/for-platform-operators/how-to/build-inputs/create-builder/builder) for more information):
+
+```toml
+[[run.images]]
+image = "example/run"
+mirrors = ["registry.example.com/example/run"]
 ```
 
-while naming the app without a registry specified, `example/app`, will cause `example/run` to be selected as the app's
-run image.
+Then if you run `pack build` as follows:
 
 ```bash
-$ pack build example/app
+$ pack build registry.example.com/example/app
 ```
 
-> For local development, it's often helpful to override the run image mirrors in a builder. For this, the
-> `pack config run-image-mirrors` command can be used. This command does not modify the builder, and instead configures the
-> local environment.
+the selected run image will be `registry.example.com/example/run`.
+
+> For local development, it's often helpful to override the run image mirrors in a builder.
+> For this, the `pack config run-image-mirrors` command can be used.
+> This command does not modify the builder, and instead configures the local environment.
 >
-> To see what run images are configured for a builder, the
-> `builder inspect` command can be used. `builder inspect` will output built-in and locally-configured run images for
-> a given builder, along with other useful information. The order of the run images in the output denotes the order in
-> which they will be matched during `build`.
+> To see what run images are configured for a builder, `pack builder inspect` can be used.
+> `pack builder inspect` will output built-in and locally-configured run images for a given builder, along with other useful information.
+> The order of the run images in the output denotes the order in which they will be matched during `build`.