From 3f31733b784f6dd0d3ed53aaa30667d557f69f1b Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Fri, 17 Nov 2023 11:18:49 +0000 Subject: [PATCH] Simplify caching example in author guide Work out the gremlins in the caching example. We now cache only the layer creating the runtime. Signed-off-by: Aidan Delaney --- .../adding-bill-of-materials.md | 33 +++++++++---------- .../create-buildpack/caching.md | 32 ++++++++++-------- .../make-buildpack-configurable.md | 30 +++++++++-------- .../specify-multiple-process-types.md | 5 ++- 4 files changed, 53 insertions(+), 47 deletions(-) diff --git a/content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md b/content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md index 3c4d44c39..50f899b9a 100644 --- a/content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md +++ b/content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md @@ -15,14 +15,11 @@ One of the benefits of buildpacks is they can also populate the app image with m You can find some of this information using `pack` via its `inspect-image` command. The bill-of-materials information will be available using `pack sbom download`. - ```bash pack inspect-image test-node-js-app ``` - You should see the following: - ```text Run Images: cnbs/sample-base-run:jammy @@ -123,29 +120,29 @@ plan=$3 node_js_layer="${layersdir}"/node-js mkdir -p "${node_js_layer}" -# ======= MODIFIED ======= # 3. DOWNLOAD node-js -node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version') || "18.18.1" -node_js_url=https://nodejs.org/dist/v18.18.1/node-v${node_js_version}-linux-x64.tar.xz -remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs-version 2>/dev/null || echo 'NOT FOUND') +default_node_js_version="18.18.1" +node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version}) +node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz +remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND') if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then echo "-----> Downloading and extracting NodeJS" - node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}" - cat >> "${layersdir}/node-js.toml" << EOL -[metadata] -nodejs-version = "${node_js_version}" -EOL else echo "-----> Reusing NodeJS" fi # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER -echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml" + cat > "${layersdir}/node-js.toml" << EOL +[types] +cache = true +launch = true +[metadata] +nodejs_version = "${node_js_version}" +EOL -# ========== ADDED =========== # 5. SET DEFAULT START COMMAND -cat > "${layersdir}/launch.toml" << EOL +cat >> "${layersdir}/launch.toml" << EOL [[processes]] type = "web" command = "node app.js" @@ -154,8 +151,8 @@ EOL # ========== ADDED =========== # 6. ADD A SBOM -node-jsbom="${layersdir}/node-js.sbom.cdx.json" -cat >> ${node-jsbom} << EOL +node_jsbom="${layersdir}/node-js.sbom.cdx.json" +cat >> ${node_jsbom} << EOL { "bomFormat": "CycloneDX", "specVersion": "1.4", @@ -207,7 +204,7 @@ You should find that the included `node-js` version is `18.18.1` as expected. "type": "library", "name": "node-js", "version": "18.18.1" - }, + } ... ] } diff --git a/content/docs/buildpack-author-guide/create-buildpack/caching.md b/content/docs/buildpack-author-guide/create-buildpack/caching.md index 7482c9fe0..57e15a6cf 100644 --- a/content/docs/buildpack-author-guide/create-buildpack/caching.md +++ b/content/docs/buildpack-author-guide/create-buildpack/caching.md @@ -81,7 +81,7 @@ Reusing layer 'examples/node-js:node-js' ## Caching dependencies -Now, let's implement the caching logic. We need to record the version of the NodeJS runtime that is used in a build. On subsequent builds, the caching logic will detect the current requested NodeJS version and restore the previous layer from the cache if the current requested NodeJS version matches the previous NodeJS runtime version. +Now, let's implement the caching logic. We need to record the version of the NodeJS runtime that is used in a build. On subsequent builds, the caching logic will detect if the NodeJS version is the same as the version in the cached layer. We restore the previous layer from the cache if the current requested NodeJS version matches the previous NodeJS runtime version. ``` @@ -97,27 +97,30 @@ layersdir=$1 node_js_layer="${layersdir}"/node-js mkdir -p "${node_js_layer}" +# ======= MODIFIED ======= # 3. DOWNLOAD node-js -node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz -remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs-version 2>/dev/null || echo 'NOT FOUND') -if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then +node_js_version="18.18.1" +node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz +cached_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND') +if [[ "${node_js_url}" != *"${cached_nodejs_version}"* ]] ; then echo "-----> Downloading and extracting NodeJS" - node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}" - cat >> "${layersdir}/node-js.toml" << EOL -[metadata] -nodejs-version = "18.18.1" -EOL else echo "-----> Reusing NodeJS" fi +# ======= MODIFIED ======= # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER -echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml" + cat > "${layersdir}/node-js.toml" << EOL +[types] +cache = true +launch = true +[metadata] +nodejs_version = "${node_js_version}" +EOL -# ========== ADDED =========== # 5. SET DEFAULT START COMMAND -cat > "${layersdir}/launch.toml" << EOL +cat >> "${layersdir}/launch.toml" << EOL [[processes]] type = "web" command = "node app.js" @@ -125,11 +128,12 @@ default = true EOL ``` -Now when you build your app: +Now when you build your app, the second call will reuse the layer: ```text pack build test-node-js-app --path ./node-js-sample-app --buildpack ./node-js-buildpack +pack build test-node-js-app --path ./node-js-sample-app --buildpack ./node-js-buildpack ``` @@ -140,7 +144,7 @@ you will see the new caching logic at work during the `BUILDING` phase: ===> BUILDING ... ---> NodeJS Buildpack ----> Reusing node-js +-----> Reusing NodeJS ``` Next, let's see how buildpack users may be able to provide configuration to the buildpack. diff --git a/content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md b/content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md index 210c8e78e..81687352c 100644 --- a/content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md +++ b/content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md @@ -57,27 +57,29 @@ mkdir -p "${node_js_layer}" # ======= MODIFIED ======= # 3. DOWNLOAD node-js -node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version') || "18.18.1" -node_js_url=https://nodejs.org/dist/v18.18.1/node-v${node_js_version}-linux-x64.tar.xz -remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs-version 2>/dev/null || echo 'NOT FOUND') +default_node_js_version="18.18.1" +node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version}) +node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz +remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND') if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then - echo "-----> Downloading and extracting NodeJS" - node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz + echo "-----> Downloading and extracting NodeJS" ${node_js_version} wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}" - cat >> "${layersdir}/node-js.toml" << EOL -[metadata] -nodejs-version = "${node_js_version}" -EOL else echo "-----> Reusing NodeJS" fi # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER -echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml" + cat > "${layersdir}/node-js.toml" << EOL +[types] +cache = true +launch = true +[metadata] +nodejs_version = "${node_js_version}" +EOL # ========== ADDED =========== # 5. SET DEFAULT START COMMAND -cat > "${layersdir}/launch.toml" << EOL +cat >> "${layersdir}/launch.toml" << EOL [[processes]] type = "web" command = "node app.js" @@ -92,11 +94,11 @@ Finally, create a file `node-js-sample-app/.node-js-version` with the following 18.18.1 ``` -Now when you run: +In the following `pack` invocation we choose to `--clear-cache` so that we explicitly do not re-use cached layers. This helps us demonstrate that the NodeJS runtime layer does not get restored from a cache. ```bash -pack build test-node-js-app --path ./node-js-sample-app --buildpack ./node-js-buildpack +pack build test-node-js-app --clear-cache --path ./node-js-sample-app --buildpack ./node-js-buildpack ``` @@ -107,7 +109,7 @@ You will notice that version of NodeJS specified in the app's `.node-js-version` ===> BUILDING ... ---> NodeJS Buildpack ----> Downloading and extracting NodeJS 18.18.1 +-----> Downloading and extracting NodeJS 18.18.1 ``` Next, let's see how buildpacks can store information about the dependencies provided in the output app image for introspection. diff --git a/content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md b/content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md index b284b9076..936b76206 100644 --- a/content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md +++ b/content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md @@ -50,7 +50,10 @@ node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}" # 4. MAKE node-js AVAILABLE DURING LAUNCH -echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml" + cat > "${layersdir}/node-js.toml" << EOL +[types] +launch = true +EOL # ========== MODIFIED =========== # 5. SET DEFAULT START COMMAND