From 7ac49d6611fcc7213a6dd0f64e685aefd685f997 Mon Sep 17 00:00:00 2001 From: AidanDelaney Date: Thu, 7 Dec 2023 08:11:58 +0000 Subject: [PATCH] Merge pull request #633 from jose-fully-ported/patch-1 docs: update current buildpack version --- .../create-buildpack/index.xml | 37 ++--- docs/concepts/components/index.xml | 26 +--- .../consume-extension/index.xml | 6 +- .../create-extension/index.xml | 25 +--- docs/features/index.xml | 3 +- docs/index.xml | 4 +- docs/operator-guide/index.html | 6 +- docs/operator-guide/index.xml | 14 +- docs/reference/spec/buildpack-api/index.html | 4 +- docs/reference/spec/index.xml | 3 +- .../buildpack-api-0.8-0.9/index.html | 2 +- .../platform-api-0.9-0.10/index.html | 9 +- docs/tools/index.xml | 9 +- docs/tools/pack/index.html | 4 - index.html | 2 +- index.xml | 127 +++++------------- 16 files changed, 76 insertions(+), 205 deletions(-) diff --git a/docs/buildpack-author-guide/create-buildpack/index.xml b/docs/buildpack-author-guide/create-buildpack/index.xml index bbdef5bbd..c1fd3035a 100644 --- a/docs/buildpack-author-guide/create-buildpack/index.xml +++ b/docs/buildpack-author-guide/create-buildpack/index.xml @@ -12,82 +12,63 @@ https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/setup-local-environment/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/setup-local-environment/ - First, we&rsquo;ll create a sample Ruby app that you can use when developing your buildpack: -mkdir node-js-sample-app Create a file in the current directory called node-js-sample-app/app.js with the following contents: -const http = require(&#39;http&#39;); const hostname = &#39;0.0.0.0&#39;; const port = 8080; const server = http.createServer((req, res) =&gt; { res.statusCode = 200; res.setHeader(&#39;Content-Type&#39;, &#39;text/plain&#39;); res.end(&#39;Hello World!&#39;); }); // For demo purposes we do not actually start the server. This // allows us pretend to start the server and check if the output // message is correct. + First, we&rsquo;ll create a sample Ruby app that you can use when developing your buildpack: mkdir node-js-sample-app Create a file in the current directory called node-js-sample-app/app.js with the following contents: const http = require(&#39;http&#39;); const hostname = &#39;0.0.0.0&#39;; const port = 8080; const server = http.createServer((req, res) =&gt; { res.statusCode = 200; res.setHeader(&#39;Content-Type&#39;, &#39;text/plain&#39;); res.end(&#39;Hello World!&#39;); }); // For demo purposes we do not actually start the server. This // allows us pretend to start the server and check if the output // message is correct. Building blocks of a Cloud Native Buildpack https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb/ - Now we will set up the buildpack scaffolding. -Let&rsquo;s create the directory where your buildpack will live: -Using the Pack CLI The buildpack new &lt;id&gt; command will create a directory named for the buildpack ID. -Example: -pack buildpack new examples/node-js \ --api 0.8 \ --path node-js-buildpack \ --version 0.0.1 \ --stacks io.buildpacks.samples.stacks.jammy This command will create node-js-buildpack directory which contains buildpack.toml, bin/build, bin/detect files. -Additional Parameters -a, --api Buildpack API compatibility of the generated buildpack -h, --help Help for &rsquo;new' --path the location on the filesystem to generate the artifacts --stacks Stacks (deprecated) the buildpack will work with -V, --version the version of the buildpack in buildpack. + Now we will set up the buildpack scaffolding. Let&rsquo;s create the directory where your buildpack will live: Using the Pack CLI The buildpack new &lt;id&gt; command will create a directory named for the buildpack ID. Example: pack buildpack new examples/node-js \ --api 0.8 \ --path node-js-buildpack \ --version 0.0.1 \ --stacks io.buildpacks.samples.stacks.jammy This command will create node-js-buildpack directory which contains buildpack.toml, bin/build, bin/detect files. Additional Parameters -a, --api Buildpack API compatibility of the generated buildpack -h, --help Help for &rsquo;new' --path the location on the filesystem to generate the artifacts --stacks Stacks (deprecated) the buildpack will work with -V, --version the version of the buildpack in buildpack. Detecting your application https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/detection/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/detection/ - Next, you will want to actually detect that the app you are building is a node-js app. In order to do this, you will need to check for a package.json. -Replace exit 1 in the detect script with the following check: -if [[ ! -f package.json ]]; then exit 100 fi Your node-js-buildpack/bin/detect script should look like this: -#!/usr/bin/env bash set -eo pipefail if [[ ! -f package.json ]]; then exit 100 fi Next, rebuild your app with the updated buildpack: + Next, you will want to actually detect that the app you are building is a node-js app. In order to do this, you will need to check for a package.json. Replace exit 1 in the detect script with the following check: if [[ ! -f package.json ]]; then exit 100 fi Your node-js-buildpack/bin/detect script should look like this: #!/usr/bin/env bash set -eo pipefail if [[ ! -f package.json ]]; then exit 100 fi Next, rebuild your app with the updated buildpack: Building your application https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/build-app/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/build-app/ - Now we&rsquo;ll change the build step you created to install application dependencies. This will require updates to the build script such that it performs the following steps: -Create a layer for the NodeJS runtime Download the NodeJS runtime and installs it to the layer By doing this, you&rsquo;ll learn how to create arbitrary layers with your buildpack, and how to read the contents of the app in order to perform actions like downloading dependencies. + Now we&rsquo;ll change the build step you created to install application dependencies. This will require updates to the build script such that it performs the following steps: Create a layer for the NodeJS runtime Download the NodeJS runtime and installs it to the layer By doing this, you&rsquo;ll learn how to create arbitrary layers with your buildpack, and how to read the contents of the app in order to perform actions like downloading dependencies. Make your application runnable https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-app-runnable/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-app-runnable/ - To make your app runnable, a default start command must be set. You&rsquo;ll need to add the following to the end of your build script: -# ... # Set default start command cat &gt; &#34;${layersdir}/launch.toml&#34; &lt;&lt; EOL [[processes]] type = &#34;web&#34; command = &#34;node app.js&#34; default = true EOL # ... Your full node-js-buildpack/bin/build script should now look like the following: -#!/usr/bin/env bash set -eo pipefail echo &#34;---&gt; NodeJS Buildpack&#34; # 1. + To make your app runnable, a default start command must be set. You&rsquo;ll need to add the following to the end of your build script: # ... # Set default start command cat &gt; &#34;${layersdir}/launch.toml&#34; &lt;&lt; EOL [[processes]] type = &#34;web&#34; command = &#34;node app.js&#34; default = true EOL # ... Your full node-js-buildpack/bin/build script should now look like the following: #!/usr/bin/env bash set -eo pipefail echo &#34;---&gt; NodeJS Buildpack&#34; # 1. Specify multiple process types https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types/ - One of the benefits of buildpacks is that they are multi-process - an image can have multiple entrypoints for each operational mode. Let&rsquo;s see how this works. We will extend our app to have an entrypoint that allows a debugger to attach to it. -To enable running the debug process, we&rsquo;ll need to have our buildpack define a &ldquo;process type&rdquo; for the worker. Modify the section where processes are defined to: + One of the benefits of buildpacks is that they are multi-process - an image can have multiple entrypoints for each operational mode. Let&rsquo;s see how this works. We will extend our app to have an entrypoint that allows a debugger to attach to it. To enable running the debug process, we&rsquo;ll need to have our buildpack define a &ldquo;process type&rdquo; for the worker. Modify the section where processes are defined to: Improving performance with caching https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/caching/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/caching/ - We can improve performance by caching the runtime between builds, only re-downloading when necessary. To begin, let&rsquo;s cache the runtime layer. -Cache the runtime layer To do this, replace the following lines in the build script: -# 4. MAKE node-js AVAILABLE DURING LAUNCH echo -e &#39;[types]\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js.toml&#34; with the following: -# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE it echo -e &#39;[types]\ncache = true\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js. + We can improve performance by caching the runtime between builds, only re-downloading when necessary. To begin, let&rsquo;s cache the runtime layer. Cache the runtime layer To do this, replace the following lines in the build script: # 4. MAKE node-js AVAILABLE DURING LAUNCH echo -e &#39;[types]\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js.toml&#34; with the following: # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE it echo -e &#39;[types]\ncache = true\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js. Making your buildpack configurable https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable/ - It&rsquo;s likely that not all NodeJS apps will want to use the same version of NodeJS. Let&rsquo;s make the NodeJS version configurable. -Select NodeJS version We&rsquo;ll allow buildpack users to define the desired NodeJS version via a .node-js-version file in their app. We&rsquo;ll first update the detect script to check for this file. We will then record the dependency we can provide (NodeJS), as well as the specific dependency the application will require, in the Build Plan, a document the lifecycle uses to determine if the buildpack will provide everything the application needs. + It&rsquo;s likely that not all NodeJS apps will want to use the same version of NodeJS. Let&rsquo;s make the NodeJS version configurable. Select NodeJS version We&rsquo;ll allow buildpack users to define the desired NodeJS version via a .node-js-version file in their app. We&rsquo;ll first update the detect script to check for this file. We will then record the dependency we can provide (NodeJS), as well as the specific dependency the application will require, in the Build Plan, a document the lifecycle uses to determine if the buildpack will provide everything the application needs. Adding Bill-of-Materials https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials/ - One of the benefits of buildpacks is they can also populate the app image with metadata from the build process, allowing you to audit the app image for information like: -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&hellip;! + One of the benefits of buildpacks is they can also populate the app image with metadata from the build process, allowing you to audit the app image for information like: 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&hellip;! diff --git a/docs/concepts/components/index.xml b/docs/concepts/components/index.xml index 8d46264fc..ed0a73661 100644 --- a/docs/concepts/components/index.xml +++ b/docs/concepts/components/index.xml @@ -26,16 +26,14 @@ https://buildpacks.io/docs/concepts/components/buildpack/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/buildpack/ - <h2 id="what-is-a-buildpack">What is a buildpack?</h2> -<p>A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.</p> + <h2 id="what-is-a-buildpack">What is a buildpack?</h2> <p>A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.</p> Run image https://buildpacks.io/docs/concepts/components/base-images/run/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/base-images/run/ - What is a run image? The run image provides the base image for application images. The lifecycle requires a reference to a run image and (where necessary) possible 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). + What is a run image? The run image provides the base image for application images. The lifecycle requires a reference to a run image and (where necessary) possible 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). Buildpack Group @@ -49,35 +47,21 @@ Run image mirrors Run image mirrors provide alternate locations for run images, https://buildpacks.io/docs/concepts/components/platform/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/platform/ - <h2 id="what-is-a-platform">What is a Platform?</h2> -<p>A <code>platform</code> uses a <a href="https://buildpacks.io/docs/concepts/components/lifecycle/">lifecycle</a>, <a href="https://buildpacks.io/docs/concepts/components/buildpack/">buildpacks</a> (packaged in a <a href="https://buildpacks.io/docs/concepts/components/builder/">builder</a>), and application source code to produce an OCI image.</p> + <h2 id="what-is-a-platform">What is a Platform?</h2> <p>A <code>platform</code> uses a <a href="https://buildpacks.io/docs/concepts/components/lifecycle/">lifecycle</a>, <a href="https://buildpacks.io/docs/concepts/components/buildpack/">buildpacks</a> (packaged in a <a href="https://buildpacks.io/docs/concepts/components/builder/">builder</a>), and application source code to produce an OCI image.</p> Stack https://buildpacks.io/docs/concepts/components/stack/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/stack/ - <h2 id="what-is-a-stack">What is a stack?</h2> -<p>A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.</p> -<p>As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> -<p>For more information, see</p> -<ul> -<li>Platform API 0.12 <a href="https://buildpacks.io/docs/reference/spec/migration/platform-api-0.11-0.12/">migration guide</a></li> -<li>Buildpack API 0.10 <a href="https://buildpacks.io/docs/reference/spec/migration/buildpack-api-0.9-0.10/">migration guide</a></li> -<li><a href="https://buildpacks.io/docs/concepts/components/base-images/build/">Build image</a> concept</li> -<li><a href="https://buildpacks.io/docs/concepts/components/base-images/run/">Run image</a> concept</li> -<li><a href="https://buildpacks.io/docs/concepts/components/targets/">Target data</a></li> -</ul> -<p>For older API versions, see below on using stacks.</p> + <h2 id="what-is-a-stack">What is a stack?</h2> <p>A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.</p> <p>As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> <p>For more information, see</p> <ul> <li>Platform API 0.12 <a href="https://buildpacks.io/docs/reference/spec/migration/platform-api-0.11-0.12/">migration guide</a></li> <li>Buildpack API 0.10 <a href="https://buildpacks.io/docs/reference/spec/migration/buildpack-api-0.9-0.10/">migration guide</a></li> <li><a href="https://buildpacks.io/docs/concepts/components/base-images/build/">Build image</a> concept</li> <li><a href="https://buildpacks.io/docs/concepts/components/base-images/run/">Run image</a> concept</li> <li><a href="https://buildpacks.io/docs/concepts/components/targets/">Target data</a></li> </ul> <p>For older API versions, see below on using stacks.</p> Targets https://buildpacks.io/docs/concepts/components/targets/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/targets/ - The concept of &ldquo;targets&rdquo; is used to identify compatibility between buildpacks and base images. -Target data includes: -Operating system name (e.g., &ldquo;linux&rdquo;) Architecture (e.g., &ldquo;amd64&rdquo;, &ldquo;arm64&rdquo;) Architecture variant Operating system distribution name (e.g., &ldquo;ubuntu&rdquo;, &ldquo;alpine&rdquo;) Operating system distribution version (e.g., &ldquo;22.04&rdquo;, &ldquo;3.18.3&rdquo;) For Linux-based images, operating system distribution name and version should be the values in /etc/os-release ($ID and $VERSION_ID). For Windows-based images, operating system distribution name is blank, and version should be the value of os. + The concept of &ldquo;targets&rdquo; is used to identify compatibility between buildpacks and base images. Target data includes: Operating system name (e.g., &ldquo;linux&rdquo;) Architecture (e.g., &ldquo;amd64&rdquo;, &ldquo;arm64&rdquo;) Architecture variant Operating system distribution name (e.g., &ldquo;ubuntu&rdquo;, &ldquo;alpine&rdquo;) Operating system distribution version (e.g., &ldquo;22.04&rdquo;, &ldquo;3.18.3&rdquo;) For Linux-based images, operating system distribution name and version should be the values in /etc/os-release ($ID and $VERSION_ID). For Windows-based images, operating system distribution name is blank, and version should be the value of os. diff --git a/docs/extension-guide/consume-extension/index.xml b/docs/extension-guide/consume-extension/index.xml index ef54fb9ea..55efe9e9c 100644 --- a/docs/extension-guide/consume-extension/index.xml +++ b/docs/extension-guide/consume-extension/index.xml @@ -12,16 +12,14 @@ https://buildpacks.io/docs/extension-guide/consume-extension/from-cli/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/consume-extension/from-cli/ - Specifying an Image Extension at Build Time No builder can be truly omniscient, and whoever did yours surely was no exception! You need to add a little extra spice to the mix with this late-breaking extension, by doing something like: -pack build [...] --extension=foo [...] + Specifying an Image Extension at Build Time No builder can be truly omniscient, and whoever did yours surely was no exception! You need to add a little extra spice to the mix with this late-breaking extension, by doing something like: pack build [...] --extension=foo [...] Specifying an Image Extension in the Builder https://buildpacks.io/docs/extension-guide/consume-extension/in-builder/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/consume-extension/in-builder/ - Specifying an Image Extension in the Builder You&rsquo;re pretty sharp, and you know what your buildpack users will need. That&rsquo;s why you&rsquo;re going to add something similar to the following lines directly to builder.toml: -[[order-extensions]] [[order-extensions.group]] id = &#34;foo&#34; version = &#34;0.0.1&#34; [[extensions]] id = &#34;foo&#34; version = &#34;0.0.1&#34; uri = &#34;/local/path/to/extension/foo&#34; # can be relative or absolute + Specifying an Image Extension in the Builder You&rsquo;re pretty sharp, and you know what your buildpack users will need. That&rsquo;s why you&rsquo;re going to add something similar to the following lines directly to builder.toml: [[order-extensions]] [[order-extensions.group]] id = &#34;foo&#34; version = &#34;0.0.1&#34; [[extensions]] id = &#34;foo&#34; version = &#34;0.0.1&#34; uri = &#34;/local/path/to/extension/foo&#34; # can be relative or absolute diff --git a/docs/extension-guide/create-extension/index.xml b/docs/extension-guide/create-extension/index.xml index fc6423736..374b7c1b7 100644 --- a/docs/extension-guide/create-extension/index.xml +++ b/docs/extension-guide/create-extension/index.xml @@ -12,55 +12,42 @@ https://buildpacks.io/docs/extension-guide/create-extension/setup-local-environment/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/setup-local-environment/ - Let&rsquo;s walk through a build that uses extensions, step by step. We will see an image extension that installs curl on the builder image, and switches the run image to an image that has curl installed. -Ensure Docker is running docker version If you see output similar to the following, you&rsquo;re good to go! Otherwise, start Docker and check again. -Client: Docker Engine - Community Version: 20.10.9 API version: 1. + Let&rsquo;s walk through a build that uses extensions, step by step. We will see an image extension that installs curl on the builder image, and switches the run image to an image that has curl installed. Ensure Docker is running docker version If you see output similar to the following, you&rsquo;re good to go! Otherwise, start Docker and check again. Client: Docker Engine - Community Version: 20.10.9 API version: 1. Why Dockerfiles https://buildpacks.io/docs/extension-guide/create-extension/why-dockerfiles/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/why-dockerfiles/ - Let&rsquo;s see a build that requires base image extension in order to succeed. -Examine hello-extensions buildpack detect cat $PWD/samples/buildpacks/hello-extensions/bin/detect 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&rsquo;t require any dependencies through a build plan unless the BP_REQUIRES environment variable is set. -build cat $PWD/samples/buildpacks/hello-extensions/bin/build The buildpack tries to use vim at build-time, and defines a launch process called curl that runs curl --version at runtime. + Let&rsquo;s see a build that requires base image extension in order to succeed. Examine hello-extensions buildpack detect cat $PWD/samples/buildpacks/hello-extensions/bin/detect 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&rsquo;t require any dependencies through a build plan unless the BP_REQUIRES environment variable is set. build cat $PWD/samples/buildpacks/hello-extensions/bin/build The buildpack tries to use vim at build-time, and defines a launch process called curl that runs curl --version at runtime. Building blocks of a CNB Image Extension https://buildpacks.io/docs/extension-guide/create-extension/building-blocks-extension/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/building-blocks-extension/ - Examine vim extension tree $PWD/samples/extensions/vim You should see something akin to the following: -. ├── bin │ ├── detect &lt;- similar to a buildpack ./bin/detect │ ├── generate &lt;- similar to a buildpack ./bin/build ├── extension.toml &lt;- 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. + Examine vim extension tree $PWD/samples/extensions/vim You should see something akin to the following: . ├── bin │ ├── detect &lt;- similar to a buildpack ./bin/detect │ ├── generate &lt;- similar to a buildpack ./bin/build ├── extension.toml &lt;- 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. Generating a build.Dockerfile https://buildpacks.io/docs/extension-guide/create-extension/build-dockerfile/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/build-dockerfile/ - Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies for the current application. -Examine vim extension detect cat $PWD/samples/extensions/vim/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called vim by writing to the build plan. -generate cat $PWD/samples/extensions/vim/bin/generate The extension generates a build.Dockerfile that installs vim on the builder image. -Configure the hello-extensions buildpack to require vim Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require vim (review the . + Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies for the current application. Examine vim extension detect cat $PWD/samples/extensions/vim/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called vim by writing to the build plan. generate cat $PWD/samples/extensions/vim/bin/generate The extension generates a build.Dockerfile that installs vim on the builder image. Configure the hello-extensions buildpack to require vim Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require vim (review the . Generating a run.Dockerfile that switches the runtime base image https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-switch/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-switch/ - 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 cat $PWD/samples/extensions/curl/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called curl. + 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 cat $PWD/samples/extensions/curl/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called curl. Generating a run.Dockerfile that extends the runtime base image https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-extend/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-extend/ - 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 cat $PWD/samples/extensions/cowsay/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called cowsay. -generate cat $PWD/samples/extensions/cowsay/bin/generate The extension generates a run.Dockerfile that installs cowsay on the current run image. -Configure the hello-extensions buildpack to require cowsay Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require both vim and curl (review the . + 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 cat $PWD/samples/extensions/cowsay/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called cowsay. generate cat $PWD/samples/extensions/cowsay/bin/generate The extension generates a run.Dockerfile that installs cowsay on the current run image. Configure the hello-extensions buildpack to require cowsay Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require both vim and curl (review the . The finer points of image extensions diff --git a/docs/features/index.xml b/docs/features/index.xml index f70af850f..460bde4af 100644 --- a/docs/features/index.xml +++ b/docs/features/index.xml @@ -19,8 +19,7 @@ https://buildpacks.io/docs/features/reproducibility/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/features/reproducibility/ - <h2 id="summary">Summary</h2> -<p>The Cloud Native Buildpacks project aims to create &ldquo;Reproducible Builds&rdquo; of container images. For image creation commands (<code>builder create</code>, <code>buildpack package</code>, <code>build</code>) <code>pack</code> creates container images in a reproducible fashion. &ldquo;Reproducible&rdquo; is hard to define but we&rsquo;ll do so by example and with a few caveats:</p> + <h2 id="summary">Summary</h2> <p>The Cloud Native Buildpacks project aims to create &ldquo;Reproducible Builds&rdquo; of container images. For image creation commands (<code>builder create</code>, <code>buildpack package</code>, <code>build</code>) <code>pack</code> creates container images in a reproducible fashion. &ldquo;Reproducible&rdquo; is hard to define but we&rsquo;ll do so by example and with a few caveats:</p> Software Bill of Materials diff --git a/docs/index.xml b/docs/index.xml index cf7dcf630..3459b493c 100644 --- a/docs/index.xml +++ b/docs/index.xml @@ -12,9 +12,7 @@ https://buildpacks.io/docs/app-journey/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/app-journey/ - Pack for the journey In this tutorial, we&rsquo;ll explain how to use pack and buildpacks to create a runnable app image from source code. -In order to run the build process in an isolated fashion, pack uses Docker. That means you&rsquo;ll need to make sure you have both docker and pack installed: -Install Docker Install pack NOTE: pack is only one implementation of the Cloud Native Buildpacks Platform Specification. Additionally, not all Cloud Native Buildpacks Platforms require Docker. + Pack for the journey In this tutorial, we&rsquo;ll explain how to use pack and buildpacks to create a runnable app image from source code. In order to run the build process in an isolated fashion, pack uses Docker. That means you&rsquo;ll need to make sure you have both docker and pack installed: Install Docker Install pack NOTE: pack is only one implementation of the Cloud Native Buildpacks Platform Specification. Additionally, not all Cloud Native Buildpacks Platforms require Docker. diff --git a/docs/operator-guide/index.html b/docs/operator-guide/index.html index 9ca4a2d25..bb943da52 100644 --- a/docs/operator-guide/index.html +++ b/docs/operator-guide/index.html @@ -753,8 +753,7 @@

Create a build base image

Define a build base image for your CNB build We need a Dockerfile similar to the following:

-

Define the base image FROM ubuntu:jammy # Install packages that we want to make available at build time RUN apt-get update && \ apt-get install -y xz-utils ca-certificates && \ rm -rf /var/lib/apt/lists/* \ # Set required CNB user information ARG cnb_uid=1000 ARG cnb_gid=1000 ENV CNB_USER_ID=${cnb_uid} ENV CNB_GROUP_ID=${cnb_gid} # Create user and group RUN groupadd cnb –gid ${CNB_GROUP_ID} && \ useradd –uid ${CNB_USER_ID} –gid ${CNB_GROUP_ID} -m -s /bin/bash cnb \ # Set user and group USER ${CNB_USER_ID}:${CNB_GROUP_ID} # Set required CNB target information LABEL io.

-

+

Define the base image FROM ubuntu:jammy # Install packages that we want to make available at build time RUN apt-get update && \ apt-get install -y xz-utils ca-certificates && \ rm -rf /var/lib/apt/lists/* \ # Set required CNB user information ARG cnb_uid=1000 ARG cnb_gid=1000 ENV CNB_USER_ID=${cnb_uid} ENV CNB_GROUP_ID=${cnb_gid} # Create user and group RUN groupadd cnb –gid ${CNB_GROUP_ID} && \ useradd –uid ${CNB_USER_ID} –gid ${CNB_GROUP_ID} -m -s /bin/bash cnb \ # Set user and group USER ${CNB_USER_ID}:${CNB_GROUP_ID} # Set required CNB target information LABEL io.

@@ -763,8 +762,7 @@

Create a run base image

Define a run base image for your CNB build We need a Dockerfile similar to the following:

-

Define the base image FROM ubuntu:jammy # Install packages that we want to make available at run time RUN apt-get update && \ apt-get install -y xz-utils ca-certificates && \ rm -rf /var/lib/apt/lists/* \ # Create user and group ARG cnb_uid=1000 ARG cnb_gid=1000 RUN groupadd cnb –gid ${cnb_gid} && \ useradd –uid ${cnb_uid} –gid ${cnb_gid} -m -s /bin/bash cnb \ # Set user and group USER ${cnb_uid}:${cnb_gid} # Set required CNB target information LABEL io.

-

+

Define the base image FROM ubuntu:jammy # Install packages that we want to make available at run time RUN apt-get update && \ apt-get install -y xz-utils ca-certificates && \ rm -rf /var/lib/apt/lists/* \ # Create user and group ARG cnb_uid=1000 ARG cnb_gid=1000 RUN groupadd cnb –gid ${cnb_gid} && \ useradd –uid ${cnb_uid} –gid ${cnb_gid} -m -s /bin/bash cnb \ # Set user and group USER ${cnb_uid}:${cnb_gid} # Set required CNB target information LABEL io.

diff --git a/docs/operator-guide/index.xml b/docs/operator-guide/index.xml index ca6b047b1..0289652ec 100644 --- a/docs/operator-guide/index.xml +++ b/docs/operator-guide/index.xml @@ -19,29 +19,21 @@ https://buildpacks.io/docs/operator-guide/create-build-base/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/operator-guide/create-build-base/ - Define a build base image for your CNB build We need a Dockerfile similar to the following: -# Define the base image FROM ubuntu:jammy # Install packages that we want to make available at build time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Set required CNB user information ARG cnb_uid=1000 ARG cnb_gid=1000 ENV CNB_USER_ID=${cnb_uid} ENV CNB_GROUP_ID=${cnb_gid} # Create user and group RUN groupadd cnb --gid ${CNB_GROUP_ID} &amp;&amp; \ useradd --uid ${CNB_USER_ID} --gid ${CNB_GROUP_ID} -m -s /bin/bash cnb \ # Set user and group USER ${CNB_USER_ID}:${CNB_GROUP_ID} # Set required CNB target information LABEL io. + Define a build base image for your CNB build We need a Dockerfile similar to the following: # Define the base image FROM ubuntu:jammy # Install packages that we want to make available at build time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Set required CNB user information ARG cnb_uid=1000 ARG cnb_gid=1000 ENV CNB_USER_ID=${cnb_uid} ENV CNB_GROUP_ID=${cnb_gid} # Create user and group RUN groupadd cnb --gid ${CNB_GROUP_ID} &amp;&amp; \ useradd --uid ${CNB_USER_ID} --gid ${CNB_GROUP_ID} -m -s /bin/bash cnb \ # Set user and group USER ${CNB_USER_ID}:${CNB_GROUP_ID} # Set required CNB target information LABEL io. Create a run base image https://buildpacks.io/docs/operator-guide/create-run-base/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/operator-guide/create-run-base/ - Define a run base image for your CNB build We need a Dockerfile similar to the following: -# Define the base image FROM ubuntu:jammy # Install packages that we want to make available at run time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Create user and group ARG cnb_uid=1000 ARG cnb_gid=1000 RUN groupadd cnb --gid ${cnb_gid} &amp;&amp; \ useradd --uid ${cnb_uid} --gid ${cnb_gid} -m -s /bin/bash cnb \ # Set user and group USER ${cnb_uid}:${cnb_gid} # Set required CNB target information LABEL io. + Define a run base image for your CNB build We need a Dockerfile similar to the following: # Define the base image FROM ubuntu:jammy # Install packages that we want to make available at run time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Create user and group ARG cnb_uid=1000 ARG cnb_gid=1000 RUN groupadd cnb --gid ${cnb_gid} &amp;&amp; \ useradd --uid ${cnb_uid} --gid ${cnb_gid} -m -s /bin/bash cnb \ # Set user and group USER ${cnb_uid}:${cnb_gid} # Set required CNB target information LABEL io. Create a stack https://buildpacks.io/docs/operator-guide/create-a-stack/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/operator-guide/create-a-stack/ - <p><strong>Note</strong>: As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> -<p>You can still configure the build and run base images for your CNB build. -To find out how, see <a href="https://buildpacks.io/docs/operator-guide/create-build-base/">create a build base image</a> and <a href="https://buildpacks.io/docs/operator-guide/create-run-base/">create a run base image</a>.</p> -<p>A stack is the grouping together of the build and run base images, represented by a unique ID. -A stack ID identifies the configuration for the build and run base images, and it used to determined compatibility with available buildpacks, and rebasability when updated run images are available. -If you&rsquo;re on an older Platform API version, you may still need to create a custom stack. -To find out how, read on&hellip;</p> + <p><strong>Note</strong>: As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> <p>You can still configure the build and run base images for your CNB build. To find out how, see <a href="https://buildpacks.io/docs/operator-guide/create-build-base/">create a build base image</a> and <a href="https://buildpacks.io/docs/operator-guide/create-run-base/">create a run base image</a>.</p> <p>A stack is the grouping together of the build and run base images, represented by a unique ID. A stack ID identifies the configuration for the build and run base images, and it used to determined compatibility with available buildpacks, and rebasability when updated run images are available. If you&rsquo;re on an older Platform API version, you may still need to create a custom stack. To find out how, read on&hellip;</p> diff --git a/docs/reference/spec/buildpack-api/index.html b/docs/reference/spec/buildpack-api/index.html index 8869b0ab5..90bca429c 100644 --- a/docs/reference/spec/buildpack-api/index.html +++ b/docs/reference/spec/buildpack-api/index.html @@ -825,7 +825,7 @@

Example

buildpack.toml

A buildpack must contain a buildpack.toml file in its root directory.

Example

-
api = "0.8"
+
api = "0.10"
 
 [buildpack]
 id = "example.com/python"
@@ -842,7 +842,7 @@ 
Example

 
The schema is as follows:

 
    
 
  • 
-
    api (string, required, current: 0.8)
    
+
    api (string, required, current: 0.10)
    
 The Buildpack API version the buildpack adheres to. Used to ensure compatibility against
 the lifecycle.
    
 
    
diff --git a/docs/reference/spec/index.xml b/docs/reference/spec/index.xml
index 3cc22a4ed..faff3b573 100644
--- a/docs/reference/spec/index.xml
+++ b/docs/reference/spec/index.xml
@@ -12,8 +12,7 @@
       https://buildpacks.io/docs/reference/spec/buildpack-api/
       Mon, 01 Jan 0001 00:00:00 +0000
       https://buildpacks.io/docs/reference/spec/buildpack-api/
-      <p>This specification defines the interface between a buildpack and the environment that runs it.
-This API will be used by buildpack authors.</p>
+      <p>This specification defines the interface between a buildpack and the environment that runs it.
This API will be used by buildpack authors.</p>
     
     
       Distribution API
diff --git a/docs/reference/spec/migration/buildpack-api-0.8-0.9/index.html b/docs/reference/spec/migration/buildpack-api-0.8-0.9/index.html
index f51bf98f5..7a92ea087 100644
--- a/docs/reference/spec/migration/buildpack-api-0.8-0.9/index.html
+++ b/docs/reference/spec/migration/buildpack-api-0.8-0.9/index.html
@@ -747,7 +747,7 @@ 
    Shell removal
    
 
    Overridable process arguments
    
 
    Hand-in-hand with shell removal is the introduction of overridable process arguments.
    
 
    In launch.toml, command is now a list. The first element in command is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The args list now designates arguments that can be overridden by the end user - if supported by the platform (Platform API version 0.10 and above). For further details, see the platform migration guide.
    
-
    For older platforms (Platform API version 0.9 and below), arguments in args will be appended to arguments in command, negating the new functionality (but preserving compatibility).
    
+
    For older platforms (Platform API version 0.9 and below), arguments in command will be prepended to arguments in args, negating the new functionality (but preserving compatibility).
    
 
    Image extensions are supported (experimental)
    
 
    Platform 0.10 introduces image extensions as experimental components for customizing build and run-time base images (see here for more information).
    
 
    For more information, see authoring an image extension.
    
diff --git a/docs/reference/spec/migration/platform-api-0.9-0.10/index.html b/docs/reference/spec/migration/platform-api-0.9-0.10/index.html
index e3610720d..2fe4c5cf1 100644
--- a/docs/reference/spec/migration/platform-api-0.9-0.10/index.html
+++ b/docs/reference/spec/migration/platform-api-0.9-0.10/index.html
@@ -754,6 +754,11 @@ 
    Newer buildpacks
    
 
will result in the following command invocation: some-command always-1 always-2 override-1 override-2. However:

 
docker run --entrypoint from-newer-buildpack my-image user-1 user-2
 
will result in the following command invocation: some-command always-1 always-2 user-1 user-2.

+
Implications of upgrading

+
For processes from newer buildpacks, upgrading the platform (without changing anything else) will change the command invocation for end-users.

+
As an example, the following on Platform API version 0.9:

+
docker run --entrypoint from-newer-buildpack my-image user-1 user-2
+
will result in the following command invocation: some-command always-1 always-2 override-1 override-2 user-1 user-2, where overridable arguments are treated like regular arguments, and user-provided arguments are always appended. Upgrading the platform will cause override-1 and override-2 to be dropped, as shown above.

 
Older buildpacks

 
Process types contributed by older buildpacks (Buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml:

 
[[processes]]
@@ -761,10 +766,12 @@ 
Older buildpacks

 command = ["some-command"]
 args = ["always-1", "always-2"]
 
The command list will never have more than one element. always-1 and always-2 are arguments that are always provided to some-command. If no user-provided arguments are specified when the application image is launched, always-1 and always-2 will be provided only. If user-provided arguments are specified, these will be appended to the args list. Example:

-
docker run --entrypoint from-newer-buildpack my-image
+
docker run --entrypoint from-older-buildpack my-image
 
will result in the following command invocation: some-command always-1 always-2. However:

 
docker run --entrypoint from-older-buildpack my-image user-1 user-2
 
will result in the following command invocation: some-command always-1 always-2 user-1 user-2.

+
Implications of upgrading

+
For processes from older buildpacks, upgrading the platform will not change the command invocation.

 
Image extensions are supported (experimental)

 
Platform 0.10 introduces image extensions as experimental components for customizing build and run-time base images (see here for more information). Image extensions output Dockerfiles which are applied by the lifecycle using [kaniko][https://github.com/GoogleContainerTools/kaniko], a tool for building container images in Kubernetes, as a library.

 
Note: image extensions are not supported for Windows container images.

diff --git a/docs/tools/index.xml b/docs/tools/index.xml
index 3ced2d77d..dba4fcdb9 100644
--- a/docs/tools/index.xml
+++ b/docs/tools/index.xml
@@ -12,16 +12,14 @@
       https://buildpacks.io/docs/tools/circleci/
       Mon, 01 Jan 0001 00:00:00 +0000
       https://buildpacks.io/docs/tools/circleci/
-      <p><a href="https://circleci.com/">CircleCI</a> is a continuous integration and delivery platform. The CNB project maintains an integration, called an <a href="https://circleci.com/orbs/">orb</a>,
-which allows users to run <a href="https://buildpacks.io/docs/install-pack">pack</a> commands inside their pipelines.</p>
+      <p><a href="https://circleci.com/">CircleCI</a> is a continuous integration and delivery platform. The CNB project maintains an integration, called an <a href="https://circleci.com/orbs/">orb</a>,
which allows users to run <a href="https://buildpacks.io/docs/install-pack">pack</a> commands inside their pipelines.</p>
     
     
       Gitlab Auto DevOps
       https://buildpacks.io/docs/tools/gitlab/
       Mon, 01 Jan 0001 00:00:00 +0000
       https://buildpacks.io/docs/tools/gitlab/
-      <p><a href="https://about.gitlab.com/">Gitlab</a> is a web based DevOps platform. It uses <a href="https://buildpacks.io/docs/install-pack"><code>pack</code></a> as part of the <a href="https://docs.gitlab.com/ee/topics/autodevops/">Auto DevOps</a> feature, to
-build applications prior to deploying them.</p>
+      <p><a href="https://about.gitlab.com/">Gitlab</a> is a web based DevOps platform. It uses <a href="https://buildpacks.io/docs/install-pack"><code>pack</code></a> as part of the <a href="https://docs.gitlab.com/ee/topics/autodevops/">Auto DevOps</a> feature, to
build applications prior to deploying them.</p>
     
     
       kpack
@@ -42,8 +40,7 @@ build applications prior to deploying them.</p>
       https://buildpacks.io/docs/tools/tekton/
       Mon, 01 Jan 0001 00:00:00 +0000
       https://buildpacks.io/docs/tools/tekton/
-      <p><a href="https://tekton.dev/">Tekton</a> is an open-source CI/CD system platform implementation running on k8s. There are two Tekton <code>tasks</code>
-maintained by the CNB project, both of which use the <a href="https://buildpacks.io/docs/concepts/components/lifecycle">lifecycle</a> directly (i.e. they do not use <code>pack</code>).</p>
+      <p><a href="https://tekton.dev/">Tekton</a> is an open-source CI/CD system platform implementation running on k8s. There are two Tekton <code>tasks</code>
maintained by the CNB project, both of which use the <a href="https://buildpacks.io/docs/concepts/components/lifecycle">lifecycle</a> directly (i.e. they do not use <code>pack</code>).</p>
     
   
 
diff --git a/docs/tools/pack/index.html b/docs/tools/pack/index.html
index 6b3a234b9..87a42ca56 100644
--- a/docs/tools/pack/index.html
+++ b/docs/tools/pack/index.html
@@ -818,7 +818,6 @@ 
Install

 
  • pack-cli
    • 
 
  • pack-cli-bin
    • 
 
-
    @@ -886,7 +885,6 @@

    Usage

  • Extract the pack binary
  • (Optional) Add the directory containing pack to PATH
    • -
    @@ -980,7 +978,6 @@

    Usage

  • Extract the pack binary
  • (Optional) Add the directory containing pack to PATH
    • - @@ -1069,7 +1066,6 @@

    Usage

  • Extract the pack binary
  • (Optional) Add the directory containing pack to PATH
    • - diff --git a/index.html b/index.html index 6e5506039..e3a47a764 100644 --- a/index.html +++ b/index.html @@ -2,7 +2,7 @@ - + diff --git a/index.xml b/index.xml index 7feed13a6..18b090449 100644 --- a/index.xml +++ b/index.xml @@ -68,9 +68,7 @@ https://buildpacks.io/docs/app-journey/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/app-journey/ - Pack for the journey In this tutorial, we&rsquo;ll explain how to use pack and buildpacks to create a runnable app image from source code. -In order to run the build process in an isolated fashion, pack uses Docker. That means you&rsquo;ll need to make sure you have both docker and pack installed: -Install Docker Install pack NOTE: pack is only one implementation of the Cloud Native Buildpacks Platform Specification. Additionally, not all Cloud Native Buildpacks Platforms require Docker. + Pack for the journey In this tutorial, we&rsquo;ll explain how to use pack and buildpacks to create a runnable app image from source code. In order to run the build process in an isolated fashion, pack uses Docker. That means you&rsquo;ll need to make sure you have both docker and pack installed: Install Docker Install pack NOTE: pack is only one implementation of the Cloud Native Buildpacks Platform Specification. Additionally, not all Cloud Native Buildpacks Platforms require Docker. Build a Windows app @@ -91,8 +89,7 @@ Install Docker Install pack NOTE: pack is only one implementation of the Cloud N https://buildpacks.io/docs/concepts/components/buildpack/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/buildpack/ - <h2 id="what-is-a-buildpack">What is a buildpack?</h2> -<p>A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.</p> + <h2 id="what-is-a-buildpack">What is a buildpack?</h2> <p>A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.</p> Community @@ -106,8 +103,7 @@ Install Docker Install pack NOTE: pack is only one implementation of the Cloud N https://buildpacks.io/docs/operator-guide/create-build-base/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/operator-guide/create-build-base/ - Define a build base image for your CNB build We need a Dockerfile similar to the following: -# Define the base image FROM ubuntu:jammy # Install packages that we want to make available at build time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Set required CNB user information ARG cnb_uid=1000 ARG cnb_gid=1000 ENV CNB_USER_ID=${cnb_uid} ENV CNB_GROUP_ID=${cnb_gid} # Create user and group RUN groupadd cnb --gid ${CNB_GROUP_ID} &amp;&amp; \ useradd --uid ${CNB_USER_ID} --gid ${CNB_GROUP_ID} -m -s /bin/bash cnb \ # Set user and group USER ${CNB_USER_ID}:${CNB_GROUP_ID} # Set required CNB target information LABEL io. + Define a build base image for your CNB build We need a Dockerfile similar to the following: # Define the base image FROM ubuntu:jammy # Install packages that we want to make available at build time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Set required CNB user information ARG cnb_uid=1000 ARG cnb_gid=1000 ENV CNB_USER_ID=${cnb_uid} ENV CNB_GROUP_ID=${cnb_gid} # Create user and group RUN groupadd cnb --gid ${CNB_GROUP_ID} &amp;&amp; \ useradd --uid ${CNB_USER_ID} --gid ${CNB_GROUP_ID} -m -s /bin/bash cnb \ # Set user and group USER ${CNB_USER_ID}:${CNB_GROUP_ID} # Set required CNB target information LABEL io. Detect @@ -128,8 +124,7 @@ Install Docker Install pack NOTE: pack is only one implementation of the Cloud N https://buildpacks.io/docs/concepts/components/base-images/run/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/base-images/run/ - What is a run image? The run image provides the base image for application images. The lifecycle requires a reference to a run image and (where necessary) possible 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). + What is a run image? The run image provides the base image for application images. The lifecycle requires a reference to a run image and (where necessary) possible 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). Buildpack Group @@ -143,8 +138,7 @@ Run image mirrors Run image mirrors provide alternate locations for run images, https://buildpacks.io/docs/operator-guide/create-run-base/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/operator-guide/create-run-base/ - Define a run base image for your CNB build We need a Dockerfile similar to the following: -# Define the base image FROM ubuntu:jammy # Install packages that we want to make available at run time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Create user and group ARG cnb_uid=1000 ARG cnb_gid=1000 RUN groupadd cnb --gid ${cnb_gid} &amp;&amp; \ useradd --uid ${cnb_uid} --gid ${cnb_gid} -m -s /bin/bash cnb \ # Set user and group USER ${cnb_uid}:${cnb_gid} # Set required CNB target information LABEL io. + Define a run base image for your CNB build We need a Dockerfile similar to the following: # Define the base image FROM ubuntu:jammy # Install packages that we want to make available at run time RUN apt-get update &amp;&amp; \ apt-get install -y xz-utils ca-certificates &amp;&amp; \ rm -rf /var/lib/apt/lists/* \ # Create user and group ARG cnb_uid=1000 ARG cnb_gid=1000 RUN groupadd cnb --gid ${cnb_gid} &amp;&amp; \ useradd --uid ${cnb_uid} --gid ${cnb_gid} -m -s /bin/bash cnb \ # Set user and group USER ${cnb_uid}:${cnb_gid} # Set required CNB target information LABEL io. Environment variables @@ -165,8 +159,7 @@ Run image mirrors Run image mirrors provide alternate locations for run images, https://buildpacks.io/docs/concepts/components/platform/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/platform/ - <h2 id="what-is-a-platform">What is a Platform?</h2> -<p>A <code>platform</code> uses a <a href="https://buildpacks.io/docs/concepts/components/lifecycle/">lifecycle</a>, <a href="https://buildpacks.io/docs/concepts/components/buildpack/">buildpacks</a> (packaged in a <a href="https://buildpacks.io/docs/concepts/components/builder/">builder</a>), and application source code to produce an OCI image.</p> + <h2 id="what-is-a-platform">What is a Platform?</h2> <p>A <code>platform</code> uses a <a href="https://buildpacks.io/docs/concepts/components/lifecycle/">lifecycle</a>, <a href="https://buildpacks.io/docs/concepts/components/buildpack/">buildpacks</a> (packaged in a <a href="https://buildpacks.io/docs/concepts/components/builder/">builder</a>), and application source code to produce an OCI image.</p> Restore @@ -194,13 +187,7 @@ Run image mirrors Run image mirrors provide alternate locations for run images, https://buildpacks.io/docs/operator-guide/create-a-stack/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/operator-guide/create-a-stack/ - <p><strong>Note</strong>: As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> -<p>You can still configure the build and run base images for your CNB build. -To find out how, see <a href="https://buildpacks.io/docs/operator-guide/create-build-base/">create a build base image</a> and <a href="https://buildpacks.io/docs/operator-guide/create-run-base/">create a run base image</a>.</p> -<p>A stack is the grouping together of the build and run base images, represented by a unique ID. -A stack ID identifies the configuration for the build and run base images, and it used to determined compatibility with available buildpacks, and rebasability when updated run images are available. -If you&rsquo;re on an older Platform API version, you may still need to create a custom stack. -To find out how, read on&hellip;</p> + <p><strong>Note</strong>: As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> <p>You can still configure the build and run base images for your CNB build. To find out how, see <a href="https://buildpacks.io/docs/operator-guide/create-build-base/">create a build base image</a> and <a href="https://buildpacks.io/docs/operator-guide/create-run-base/">create a run base image</a>.</p> <p>A stack is the grouping together of the build and run base images, represented by a unique ID. A stack ID identifies the configuration for the build and run base images, and it used to determined compatibility with available buildpacks, and rebasability when updated run images are available. If you&rsquo;re on an older Platform API version, you may still need to create a custom stack. To find out how, read on&hellip;</p> Mounting Volumes @@ -221,27 +208,14 @@ To find out how, read on&hellip;</p> https://buildpacks.io/docs/concepts/components/stack/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/stack/ - <h2 id="what-is-a-stack">What is a stack?</h2> -<p>A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.</p> -<p>As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> -<p>For more information, see</p> -<ul> -<li>Platform API 0.12 <a href="https://buildpacks.io/docs/reference/spec/migration/platform-api-0.11-0.12/">migration guide</a></li> -<li>Buildpack API 0.10 <a href="https://buildpacks.io/docs/reference/spec/migration/buildpack-api-0.9-0.10/">migration guide</a></li> -<li><a href="https://buildpacks.io/docs/concepts/components/base-images/build/">Build image</a> concept</li> -<li><a href="https://buildpacks.io/docs/concepts/components/base-images/run/">Run image</a> concept</li> -<li><a href="https://buildpacks.io/docs/concepts/components/targets/">Target data</a></li> -</ul> -<p>For older API versions, see below on using stacks.</p> + <h2 id="what-is-a-stack">What is a stack?</h2> <p>A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.</p> <p>As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.</p> <p>For more information, see</p> <ul> <li>Platform API 0.12 <a href="https://buildpacks.io/docs/reference/spec/migration/platform-api-0.11-0.12/">migration guide</a></li> <li>Buildpack API 0.10 <a href="https://buildpacks.io/docs/reference/spec/migration/buildpack-api-0.9-0.10/">migration guide</a></li> <li><a href="https://buildpacks.io/docs/concepts/components/base-images/build/">Build image</a> concept</li> <li><a href="https://buildpacks.io/docs/concepts/components/base-images/run/">Run image</a> concept</li> <li><a href="https://buildpacks.io/docs/concepts/components/targets/">Target data</a></li> </ul> <p>For older API versions, see below on using stacks.</p> Targets https://buildpacks.io/docs/concepts/components/targets/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/concepts/components/targets/ - The concept of &ldquo;targets&rdquo; is used to identify compatibility between buildpacks and base images. -Target data includes: -Operating system name (e.g., &ldquo;linux&rdquo;) Architecture (e.g., &ldquo;amd64&rdquo;, &ldquo;arm64&rdquo;) Architecture variant Operating system distribution name (e.g., &ldquo;ubuntu&rdquo;, &ldquo;alpine&rdquo;) Operating system distribution version (e.g., &ldquo;22.04&rdquo;, &ldquo;3.18.3&rdquo;) For Linux-based images, operating system distribution name and version should be the values in /etc/os-release ($ID and $VERSION_ID). For Windows-based images, operating system distribution name is blank, and version should be the value of os. + The concept of &ldquo;targets&rdquo; is used to identify compatibility between buildpacks and base images. Target data includes: Operating system name (e.g., &ldquo;linux&rdquo;) Architecture (e.g., &ldquo;amd64&rdquo;, &ldquo;arm64&rdquo;) Architecture variant Operating system distribution name (e.g., &ldquo;ubuntu&rdquo;, &ldquo;alpine&rdquo;) Operating system distribution version (e.g., &ldquo;22.04&rdquo;, &ldquo;3.18.3&rdquo;) For Linux-based images, operating system distribution name and version should be the values in /etc/os-release ($ID and $VERSION_ID). For Windows-based images, operating system distribution name is blank, and version should be the value of os. Export @@ -346,127 +320,98 @@ Operating system name (e.g., &ldquo;linux&rdquo;) Architecture (e.g., &a https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/setup-local-environment/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/setup-local-environment/ - First, we&rsquo;ll create a sample Ruby app that you can use when developing your buildpack: -mkdir node-js-sample-app Create a file in the current directory called node-js-sample-app/app.js with the following contents: -const http = require(&#39;http&#39;); const hostname = &#39;0.0.0.0&#39;; const port = 8080; const server = http.createServer((req, res) =&gt; { res.statusCode = 200; res.setHeader(&#39;Content-Type&#39;, &#39;text/plain&#39;); res.end(&#39;Hello World!&#39;); }); // For demo purposes we do not actually start the server. This // allows us pretend to start the server and check if the output // message is correct. + First, we&rsquo;ll create a sample Ruby app that you can use when developing your buildpack: mkdir node-js-sample-app Create a file in the current directory called node-js-sample-app/app.js with the following contents: const http = require(&#39;http&#39;); const hostname = &#39;0.0.0.0&#39;; const port = 8080; const server = http.createServer((req, res) =&gt; { res.statusCode = 200; res.setHeader(&#39;Content-Type&#39;, &#39;text/plain&#39;); res.end(&#39;Hello World!&#39;); }); // For demo purposes we do not actually start the server. This // allows us pretend to start the server and check if the output // message is correct. Set up your local environment https://buildpacks.io/docs/extension-guide/create-extension/setup-local-environment/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/setup-local-environment/ - Let&rsquo;s walk through a build that uses extensions, step by step. We will see an image extension that installs curl on the builder image, and switches the run image to an image that has curl installed. -Ensure Docker is running docker version If you see output similar to the following, you&rsquo;re good to go! Otherwise, start Docker and check again. -Client: Docker Engine - Community Version: 20.10.9 API version: 1. + Let&rsquo;s walk through a build that uses extensions, step by step. We will see an image extension that installs curl on the builder image, and switches the run image to an image that has curl installed. Ensure Docker is running docker version If you see output similar to the following, you&rsquo;re good to go! Otherwise, start Docker and check again. Client: Docker Engine - Community Version: 20.10.9 API version: 1. Building blocks of a Cloud Native Buildpack https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb/ - Now we will set up the buildpack scaffolding. -Let&rsquo;s create the directory where your buildpack will live: -Using the Pack CLI The buildpack new &lt;id&gt; command will create a directory named for the buildpack ID. -Example: -pack buildpack new examples/node-js \ --api 0.8 \ --path node-js-buildpack \ --version 0.0.1 \ --stacks io.buildpacks.samples.stacks.jammy This command will create node-js-buildpack directory which contains buildpack.toml, bin/build, bin/detect files. -Additional Parameters -a, --api Buildpack API compatibility of the generated buildpack -h, --help Help for &rsquo;new' --path the location on the filesystem to generate the artifacts --stacks Stacks (deprecated) the buildpack will work with -V, --version the version of the buildpack in buildpack. + Now we will set up the buildpack scaffolding. Let&rsquo;s create the directory where your buildpack will live: Using the Pack CLI The buildpack new &lt;id&gt; command will create a directory named for the buildpack ID. Example: pack buildpack new examples/node-js \ --api 0.8 \ --path node-js-buildpack \ --version 0.0.1 \ --stacks io.buildpacks.samples.stacks.jammy This command will create node-js-buildpack directory which contains buildpack.toml, bin/build, bin/detect files. Additional Parameters -a, --api Buildpack API compatibility of the generated buildpack -h, --help Help for &rsquo;new' --path the location on the filesystem to generate the artifacts --stacks Stacks (deprecated) the buildpack will work with -V, --version the version of the buildpack in buildpack. Why Dockerfiles https://buildpacks.io/docs/extension-guide/create-extension/why-dockerfiles/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/why-dockerfiles/ - Let&rsquo;s see a build that requires base image extension in order to succeed. -Examine hello-extensions buildpack detect cat $PWD/samples/buildpacks/hello-extensions/bin/detect 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&rsquo;t require any dependencies through a build plan unless the BP_REQUIRES environment variable is set. -build cat $PWD/samples/buildpacks/hello-extensions/bin/build The buildpack tries to use vim at build-time, and defines a launch process called curl that runs curl --version at runtime. + Let&rsquo;s see a build that requires base image extension in order to succeed. Examine hello-extensions buildpack detect cat $PWD/samples/buildpacks/hello-extensions/bin/detect 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&rsquo;t require any dependencies through a build plan unless the BP_REQUIRES environment variable is set. build cat $PWD/samples/buildpacks/hello-extensions/bin/build The buildpack tries to use vim at build-time, and defines a launch process called curl that runs curl --version at runtime. Building blocks of a CNB Image Extension https://buildpacks.io/docs/extension-guide/create-extension/building-blocks-extension/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/building-blocks-extension/ - Examine vim extension tree $PWD/samples/extensions/vim You should see something akin to the following: -. ├── bin │ ├── detect &lt;- similar to a buildpack ./bin/detect │ ├── generate &lt;- similar to a buildpack ./bin/build ├── extension.toml &lt;- 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. + Examine vim extension tree $PWD/samples/extensions/vim You should see something akin to the following: . ├── bin │ ├── detect &lt;- similar to a buildpack ./bin/detect │ ├── generate &lt;- similar to a buildpack ./bin/build ├── extension.toml &lt;- 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. Detecting your application https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/detection/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/detection/ - Next, you will want to actually detect that the app you are building is a node-js app. In order to do this, you will need to check for a package.json. -Replace exit 1 in the detect script with the following check: -if [[ ! -f package.json ]]; then exit 100 fi Your node-js-buildpack/bin/detect script should look like this: -#!/usr/bin/env bash set -eo pipefail if [[ ! -f package.json ]]; then exit 100 fi Next, rebuild your app with the updated buildpack: + Next, you will want to actually detect that the app you are building is a node-js app. In order to do this, you will need to check for a package.json. Replace exit 1 in the detect script with the following check: if [[ ! -f package.json ]]; then exit 100 fi Your node-js-buildpack/bin/detect script should look like this: #!/usr/bin/env bash set -eo pipefail if [[ ! -f package.json ]]; then exit 100 fi Next, rebuild your app with the updated buildpack: Building your application https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/build-app/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/build-app/ - Now we&rsquo;ll change the build step you created to install application dependencies. This will require updates to the build script such that it performs the following steps: -Create a layer for the NodeJS runtime Download the NodeJS runtime and installs it to the layer By doing this, you&rsquo;ll learn how to create arbitrary layers with your buildpack, and how to read the contents of the app in order to perform actions like downloading dependencies. + Now we&rsquo;ll change the build step you created to install application dependencies. This will require updates to the build script such that it performs the following steps: Create a layer for the NodeJS runtime Download the NodeJS runtime and installs it to the layer By doing this, you&rsquo;ll learn how to create arbitrary layers with your buildpack, and how to read the contents of the app in order to perform actions like downloading dependencies. Generating a build.Dockerfile https://buildpacks.io/docs/extension-guide/create-extension/build-dockerfile/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/build-dockerfile/ - Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies for the current application. -Examine vim extension detect cat $PWD/samples/extensions/vim/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called vim by writing to the build plan. -generate cat $PWD/samples/extensions/vim/bin/generate The extension generates a build.Dockerfile that installs vim on the builder image. -Configure the hello-extensions buildpack to require vim Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require vim (review the . + Builder images can be kept lean if image extensions are used to dynamically install the needed dependencies for the current application. Examine vim extension detect cat $PWD/samples/extensions/vim/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called vim by writing to the build plan. generate cat $PWD/samples/extensions/vim/bin/generate The extension generates a build.Dockerfile that installs vim on the builder image. Configure the hello-extensions buildpack to require vim Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require vim (review the . Generating a run.Dockerfile that switches the runtime base image https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-switch/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-switch/ - 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 cat $PWD/samples/extensions/curl/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called curl. + 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 cat $PWD/samples/extensions/curl/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called curl. Make your application runnable https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-app-runnable/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-app-runnable/ - To make your app runnable, a default start command must be set. You&rsquo;ll need to add the following to the end of your build script: -# ... # Set default start command cat &gt; &#34;${layersdir}/launch.toml&#34; &lt;&lt; EOL [[processes]] type = &#34;web&#34; command = &#34;node app.js&#34; default = true EOL # ... Your full node-js-buildpack/bin/build script should now look like the following: -#!/usr/bin/env bash set -eo pipefail echo &#34;---&gt; NodeJS Buildpack&#34; # 1. + To make your app runnable, a default start command must be set. You&rsquo;ll need to add the following to the end of your build script: # ... # Set default start command cat &gt; &#34;${layersdir}/launch.toml&#34; &lt;&lt; EOL [[processes]] type = &#34;web&#34; command = &#34;node app.js&#34; default = true EOL # ... Your full node-js-buildpack/bin/build script should now look like the following: #!/usr/bin/env bash set -eo pipefail echo &#34;---&gt; NodeJS Buildpack&#34; # 1. Specifying an Image Extension at Build Time https://buildpacks.io/docs/extension-guide/consume-extension/from-cli/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/consume-extension/from-cli/ - Specifying an Image Extension at Build Time No builder can be truly omniscient, and whoever did yours surely was no exception! You need to add a little extra spice to the mix with this late-breaking extension, by doing something like: -pack build [...] --extension=foo [...] + Specifying an Image Extension at Build Time No builder can be truly omniscient, and whoever did yours surely was no exception! You need to add a little extra spice to the mix with this late-breaking extension, by doing something like: pack build [...] --extension=foo [...] Specifying an Image Extension in the Builder https://buildpacks.io/docs/extension-guide/consume-extension/in-builder/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/consume-extension/in-builder/ - Specifying an Image Extension in the Builder You&rsquo;re pretty sharp, and you know what your buildpack users will need. That&rsquo;s why you&rsquo;re going to add something similar to the following lines directly to builder.toml: -[[order-extensions]] [[order-extensions.group]] id = &#34;foo&#34; version = &#34;0.0.1&#34; [[extensions]] id = &#34;foo&#34; version = &#34;0.0.1&#34; uri = &#34;/local/path/to/extension/foo&#34; # can be relative or absolute + Specifying an Image Extension in the Builder You&rsquo;re pretty sharp, and you know what your buildpack users will need. That&rsquo;s why you&rsquo;re going to add something similar to the following lines directly to builder.toml: [[order-extensions]] [[order-extensions.group]] id = &#34;foo&#34; version = &#34;0.0.1&#34; [[extensions]] id = &#34;foo&#34; version = &#34;0.0.1&#34; uri = &#34;/local/path/to/extension/foo&#34; # can be relative or absolute Generating a run.Dockerfile that extends the runtime base image https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-extend/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/extension-guide/create-extension/run-dockerfile-extend/ - 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 cat $PWD/samples/extensions/cowsay/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called cowsay. -generate cat $PWD/samples/extensions/cowsay/bin/generate The extension generates a run.Dockerfile that installs cowsay on the current run image. -Configure the hello-extensions buildpack to require cowsay Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require both vim and curl (review the . + 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 cat $PWD/samples/extensions/cowsay/bin/detect The extension always detects (because its exit code is 0) and provides a dependency called cowsay. generate cat $PWD/samples/extensions/cowsay/bin/generate The extension generates a run.Dockerfile that installs cowsay on the current run image. Configure the hello-extensions buildpack to require cowsay Set the BP_REQUIRES build-time environment variable to configure the hello-extensions buildpack to require both vim and curl (review the . Specify multiple process types https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types/ - One of the benefits of buildpacks is that they are multi-process - an image can have multiple entrypoints for each operational mode. Let&rsquo;s see how this works. We will extend our app to have an entrypoint that allows a debugger to attach to it. -To enable running the debug process, we&rsquo;ll need to have our buildpack define a &ldquo;process type&rdquo; for the worker. Modify the section where processes are defined to: + One of the benefits of buildpacks is that they are multi-process - an image can have multiple entrypoints for each operational mode. Let&rsquo;s see how this works. We will extend our app to have an entrypoint that allows a debugger to attach to it. To enable running the debug process, we&rsquo;ll need to have our buildpack define a &ldquo;process type&rdquo; for the worker. Modify the section where processes are defined to: The finer points of image extensions @@ -480,26 +425,21 @@ To enable running the debug process, we&rsquo;ll need to have our buildpack https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/caching/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/caching/ - We can improve performance by caching the runtime between builds, only re-downloading when necessary. To begin, let&rsquo;s cache the runtime layer. -Cache the runtime layer To do this, replace the following lines in the build script: -# 4. MAKE node-js AVAILABLE DURING LAUNCH echo -e &#39;[types]\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js.toml&#34; with the following: -# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE it echo -e &#39;[types]\ncache = true\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js. + We can improve performance by caching the runtime between builds, only re-downloading when necessary. To begin, let&rsquo;s cache the runtime layer. Cache the runtime layer To do this, replace the following lines in the build script: # 4. MAKE node-js AVAILABLE DURING LAUNCH echo -e &#39;[types]\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js.toml&#34; with the following: # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE it echo -e &#39;[types]\ncache = true\nlaunch = true&#39; &gt; &#34;${layersdir}/node-js. Making your buildpack configurable https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable/ - It&rsquo;s likely that not all NodeJS apps will want to use the same version of NodeJS. Let&rsquo;s make the NodeJS version configurable. -Select NodeJS version We&rsquo;ll allow buildpack users to define the desired NodeJS version via a .node-js-version file in their app. We&rsquo;ll first update the detect script to check for this file. We will then record the dependency we can provide (NodeJS), as well as the specific dependency the application will require, in the Build Plan, a document the lifecycle uses to determine if the buildpack will provide everything the application needs. + It&rsquo;s likely that not all NodeJS apps will want to use the same version of NodeJS. Let&rsquo;s make the NodeJS version configurable. Select NodeJS version We&rsquo;ll allow buildpack users to define the desired NodeJS version via a .node-js-version file in their app. We&rsquo;ll first update the detect script to check for this file. We will then record the dependency we can provide (NodeJS), as well as the specific dependency the application will require, in the Build Plan, a document the lifecycle uses to determine if the buildpack will provide everything the application needs. Adding Bill-of-Materials https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials/ - One of the benefits of buildpacks is they can also populate the app image with metadata from the build process, allowing you to audit the app image for information like: -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&hellip;! + One of the benefits of buildpacks is they can also populate the app image with metadata from the build process, allowing you to audit the app image for information like: 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&hellip;! builder.toml @@ -513,8 +453,7 @@ The process types that are available and the commands associated with them The r https://buildpacks.io/docs/reference/spec/buildpack-api/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/reference/spec/buildpack-api/ - <p>This specification defines the interface between a buildpack and the environment that runs it. -This API will be used by buildpack authors.</p> + <p>This specification defines the interface between a buildpack and the environment that runs it. This API will be used by buildpack authors.</p> Buildpack API 0.4 -> 0.5 @@ -563,8 +502,7 @@ This API will be used by buildpack authors.</p> https://buildpacks.io/docs/tools/circleci/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/tools/circleci/ - <p><a href="https://circleci.com/">CircleCI</a> is a continuous integration and delivery platform. The CNB project maintains an integration, called an <a href="https://circleci.com/orbs/">orb</a>, -which allows users to run <a href="https://buildpacks.io/docs/install-pack">pack</a> commands inside their pipelines.</p> + <p><a href="https://circleci.com/">CircleCI</a> is a continuous integration and delivery platform. The CNB project maintains an integration, called an <a href="https://circleci.com/orbs/">orb</a>, which allows users to run <a href="https://buildpacks.io/docs/install-pack">pack</a> commands inside their pipelines.</p> Distribution API @@ -585,8 +523,7 @@ which allows users to run <a href="https://buildpacks.io/docs/install-pac https://buildpacks.io/docs/tools/gitlab/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/tools/gitlab/ - <p><a href="https://about.gitlab.com/">Gitlab</a> is a web based DevOps platform. It uses <a href="https://buildpacks.io/docs/install-pack"><code>pack</code></a> as part of the <a href="https://docs.gitlab.com/ee/topics/autodevops/">Auto DevOps</a> feature, to -build applications prior to deploying them.</p> + <p><a href="https://about.gitlab.com/">Gitlab</a> is a web based DevOps platform. It uses <a href="https://buildpacks.io/docs/install-pack"><code>pack</code></a> as part of the <a href="https://docs.gitlab.com/ee/topics/autodevops/">Auto DevOps</a> feature, to build applications prior to deploying them.</p> kpack @@ -1048,8 +985,7 @@ build applications prior to deploying them.</p> https://buildpacks.io/docs/features/reproducibility/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/features/reproducibility/ - <h2 id="summary">Summary</h2> -<p>The Cloud Native Buildpacks project aims to create &ldquo;Reproducible Builds&rdquo; of container images. For image creation commands (<code>builder create</code>, <code>buildpack package</code>, <code>build</code>) <code>pack</code> creates container images in a reproducible fashion. &ldquo;Reproducible&rdquo; is hard to define but we&rsquo;ll do so by example and with a few caveats:</p> + <h2 id="summary">Summary</h2> <p>The Cloud Native Buildpacks project aims to create &ldquo;Reproducible Builds&rdquo; of container images. For image creation commands (<code>builder create</code>, <code>buildpack package</code>, <code>build</code>) <code>pack</code> creates container images in a reproducible fashion. &ldquo;Reproducible&rdquo; is hard to define but we&rsquo;ll do so by example and with a few caveats:</p> Software Bill of Materials @@ -1063,8 +999,7 @@ build applications prior to deploying them.</p> https://buildpacks.io/docs/tools/tekton/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/tools/tekton/ - <p><a href="https://tekton.dev/">Tekton</a> is an open-source CI/CD system platform implementation running on k8s. There are two Tekton <code>tasks</code> -maintained by the CNB project, both of which use the <a href="https://buildpacks.io/docs/concepts/components/lifecycle">lifecycle</a> directly (i.e. they do not use <code>pack</code>).</p> + <p><a href="https://tekton.dev/">Tekton</a> is an open-source CI/CD system platform implementation running on k8s. There are two Tekton <code>tasks</code> maintained by the CNB project, both of which use the <a href="https://buildpacks.io/docs/concepts/components/lifecycle">lifecycle</a> directly (i.e. they do not use <code>pack</code>).</p> Trusted Builders