Skip to content

Commit 899b0cd

Browse files
AidanDelaneyAidanDelaney
committed
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 <[email protected]>
1 parent 114efac commit 899b0cd

File tree

4 files changed

+53
-48
lines changed

4 files changed

+53
-48
lines changed

‎content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md

Lines changed: 15 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,11 @@ One of the benefits of buildpacks is they can also populate the app image with m
1515

1616
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`.
1717

18-
<!-- test:exec -->
1918
```bash
2019
pack inspect-image test-node-js-app
2120
```
22-
<!--+- "{{execute}}"+-->
2321
You should see the following:
2422

25-
<!-- test:assert=contains;ignore-lines=... -->
2623
```text
2724
Run Images:
2825
cnbs/sample-base-run:jammy
@@ -123,29 +120,29 @@ plan=$3
123120
node_js_layer="${layersdir}"/node-js
124121
mkdir -p "${node_js_layer}"
125122

126-
# ======= MODIFIED =======
127123
# 3. DOWNLOAD node-js
128-
node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version') || "18.18.1"
129-
node_js_url=https://nodejs.org/dist/v18.18.1/node-v${node_js_version}-linux-x64.tar.xz
130-
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs-version 2>/dev/null || echo 'NOT FOUND')
124+
default_node_js_version="18.18.1"
125+
node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
126+
node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
127+
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
131128
if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
132129
echo "-----> Downloading and extracting NodeJS"
133-
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
134130
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
135-
cat >> "${layersdir}/node-js.toml" << EOL
136-
[metadata]
137-
nodejs-version = "${node_js_version}"
138-
EOL
139131
else
140132
echo "-----> Reusing NodeJS"
141133
fi
142134

143135
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
144-
echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
136+
cat > "${layersdir}/node-js.toml" << EOL
137+
[types]
138+
cache = true
139+
launch = true
140+
[metadata]
141+
nodejs_version = "${node_js_version}"
142+
EOL
145143

146-
# ========== ADDED ===========
147144
# 5. SET DEFAULT START COMMAND
148-
cat > "${layersdir}/launch.toml" << EOL
145+
cat >> "${layersdir}/launch.toml" << EOL
149146
[[processes]]
150147
type = "web"
151148
command = "node app.js"
@@ -154,8 +151,8 @@ EOL
154151

155152
# ========== ADDED ===========
156153
# 6. ADD A SBOM
157-
node-jsbom="${layersdir}/node-js.sbom.cdx.json"
158-
cat >> ${node-jsbom} << EOL
154+
node_jsbom="${layersdir}/node-js.sbom.cdx.json"
155+
cat >> ${node_jsbom} << EOL
159156
{
160157
"bomFormat": "CycloneDX",
161158
"specVersion": "1.4",
@@ -196,7 +193,6 @@ cat layers/sbom/launch/examples_node-js/node-js/sbom.cdx.json | jq -M
196193

197194
You should find that the included `node-js` version is `18.18.1` as expected.
198195

199-
<!-- test:assert=contains;ignore-lines=... -->
200196
```text
201197
{
202198
"bomFormat": "CycloneDX",
@@ -207,7 +203,7 @@ You should find that the included `node-js` version is `18.18.1` as expected.
207203
"type": "library",
208204
"name": "node-js",
209205
"version": "18.18.1"
210-
},
206+
}
211207
...
212208
]
213209
}

‎content/docs/buildpack-author-guide/create-buildpack/caching.md

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ Reusing layer 'examples/node-js:node-js'
8181

8282
## Caching dependencies
8383

84-
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.
84+
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.
8585

8686
<!-- test:file=node-js-buildpack/bin/build -->
8787
```
@@ -97,39 +97,43 @@ layersdir=$1
9797
node_js_layer="${layersdir}"/node-js
9898
mkdir -p "${node_js_layer}"
9999
100+
# ======= MODIFIED =======
100101
# 3. DOWNLOAD node-js
101-
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
102-
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs-version 2>/dev/null || echo 'NOT FOUND')
103-
if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
102+
node_js_version="18.18.1"
103+
node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
104+
cached_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
105+
if [[ "${node_js_url}" != *"${cached_nodejs_version}"* ]] ; then
104106
echo "-----> Downloading and extracting NodeJS"
105-
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
106107
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
107-
cat >> "${layersdir}/node-js.toml" << EOL
108-
[metadata]
109-
nodejs-version = "18.18.1"
110-
EOL
111108
else
112109
echo "-----> Reusing NodeJS"
113110
fi
114111
112+
# ======= MODIFIED =======
115113
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
116-
echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
114+
cat > "${layersdir}/node-js.toml" << EOL
115+
[types]
116+
cache = true
117+
launch = true
118+
[metadata]
119+
nodejs_version = "${node_js_version}"
120+
EOL
117121
118-
# ========== ADDED ===========
119122
# 5. SET DEFAULT START COMMAND
120-
cat > "${layersdir}/launch.toml" << EOL
123+
cat >> "${layersdir}/launch.toml" << EOL
121124
[[processes]]
122125
type = "web"
123126
command = "node app.js"
124127
default = true
125128
EOL
126129
```
127130

128-
Now when you build your app:
131+
Now when you build your app, the second call will reuse the layer:
129132

130133
<!-- test:exec -->
131134
```text
132135
pack build test-node-js-app --path ./node-js-sample-app --buildpack ./node-js-buildpack
136+
pack build test-node-js-app --path ./node-js-sample-app --buildpack ./node-js-buildpack
133137
```
134138
<!--+- "{{execute}}"+-->
135139

@@ -140,7 +144,7 @@ you will see the new caching logic at work during the `BUILDING` phase:
140144
===> BUILDING
141145
...
142146
---> NodeJS Buildpack
143-
---> Reusing node-js
147+
-----> Reusing NodeJS
144148
```
145149

146150
Next, let's see how buildpack users may be able to provide configuration to the buildpack.

‎content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -57,27 +57,29 @@ mkdir -p "${node_js_layer}"
5757

5858
# ======= MODIFIED =======
5959
# 3. DOWNLOAD node-js
60-
node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version') || "18.18.1"
61-
node_js_url=https://nodejs.org/dist/v18.18.1/node-v${node_js_version}-linux-x64.tar.xz
62-
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs-version 2>/dev/null || echo 'NOT FOUND')
60+
default_node_js_version="18.18.1"
61+
node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
62+
node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
63+
remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
6364
if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
64-
echo "-----> Downloading and extracting NodeJS"
65-
node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
65+
echo "-----> Downloading and extracting NodeJS" ${node_js_version}
6666
wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
67-
cat >> "${layersdir}/node-js.toml" << EOL
68-
[metadata]
69-
nodejs-version = "${node_js_version}"
70-
EOL
7167
else
7268
echo "-----> Reusing NodeJS"
7369
fi
7470

7571
# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
76-
echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
72+
cat > "${layersdir}/node-js.toml" << EOL
73+
[types]
74+
cache = true
75+
launch = true
76+
[metadata]
77+
nodejs_version = "${node_js_version}"
78+
EOL
7779

7880
# ========== ADDED ===========
7981
# 5. SET DEFAULT START COMMAND
80-
cat > "${layersdir}/launch.toml" << EOL
82+
cat >> "${layersdir}/launch.toml" << EOL
8183
[[processes]]
8284
type = "web"
8385
command = "node app.js"
@@ -92,11 +94,11 @@ Finally, create a file `node-js-sample-app/.node-js-version` with the following
9294
18.18.1
9395
```
9496

95-
Now when you run:
97+
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.
9698

9799
<!-- test:exec -->
98100
```bash
99-
pack build test-node-js-app --path ./node-js-sample-app --buildpack ./node-js-buildpack
101+
pack build test-node-js-app --clear-cache --path ./node-js-sample-app --buildpack ./node-js-buildpack
100102
```
101103
<!--+- "{{execute}}"+-->
102104

@@ -107,7 +109,7 @@ You will notice that version of NodeJS specified in the app's `.node-js-version`
107109
===> BUILDING
108110
...
109111
---> NodeJS Buildpack
110-
---> Downloading and extracting NodeJS 18.18.1
112+
-----> Downloading and extracting NodeJS 18.18.1
111113
```
112114

113115
Next, let's see how buildpacks can store information about the dependencies provided in the output app image for introspection.

‎content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,10 @@ node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
5050
wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
5151

5252
# 4. MAKE node-js AVAILABLE DURING LAUNCH
53-
echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
53+
cat > "${layersdir}/node-js.toml" << EOL
54+
[types]
55+
launch = true
56+
EOL
5457

5558
# ========== MODIFIED ===========
5659
# 5. SET DEFAULT START COMMAND

0 commit comments

Comments
 (0)