1# `crane` Recipes
2
3Useful tips and things you can do with `crane` and other standard tools.
4
5### List files in an image
6
7```
8crane export ubuntu - | tar -tvf - | less
9```
10
11### Extract a single file from an image
12
13```
14crane export ubuntu - | tar -Oxf - etc/passwd
15```
16
17Note: Be sure to remove the leading `/` from the path (not `/etc/passwd`). This behavior will not follow symlinks.
18
19### Bundle directory contents into an image
20
21```
22crane append -f <(tar -f - -c some-dir/) -t ${IMAGE}
23```
24
25By default, this produces an image with one layer containing the directory contents. Add `-b ${BASE_IMAGE}` to append the layer to a base image instead.
26
27You can extend this even further with `crane mutate`, to make an executable in the appended layer the image's entrypoint.
28
29```
30crane mutate ${IMAGE} --entrypoint=some-dir/entrypoint.sh
31```
32
33Because `crane append` emits the full image reference, these calls can even be chained together:
34
35```
36crane mutate $(
37 crane append -f <(tar -f - -c some-dir/) -t ${IMAGE}
38) --entrypoint=some-dir/entrypoint.sh
39```
40
41This will bundle `some-dir/` into an image, push it, mutate its entrypoint to `some-dir/entrypoint.sh`, and push that new image by digest.
42
43### Diff two configs
44
45```
46diff <(crane config busybox:1.32 | jq) <(crane config busybox:1.33 | jq)
47```
48
49### Diff two manifests
50
51```
52diff <(crane manifest busybox:1.32 | jq) <(crane manifest busybox:1.33 | jq)
53```
54
55### Diff filesystem contents
56
57```
58diff \
59 <(crane export gcr.io/kaniko-project/executor:v1.6.0-debug - | tar -tvf - | sort) \
60 <(crane export gcr.io/kaniko-project/executor:v1.7.0-debug - | tar -tvf - | sort)
61```
62
63This will show file size diffs and (unfortunately) modified time diffs.
64
65With some work, you can use `cut` and other built-in Unix tools to ignore these diffs.
66
67### Get total image size
68
69Given an image manifest, you can calculate the total size of all layer blobs and the image's config blob using `jq`:
70
71```
72crane manifest gcr.io/buildpacks/builder:v1 | jq '.config.size + ([.layers[].size] | add)'
73```
74
75This will produce a number of bytes, which you can make human-readable by passing to [`numfmt`](https://www.gnu.org/software/coreutils/manual/html_node/numfmt-invocation.html)
76
77```
78crane manifest gcr.io/buildpacks/builder:v1 | jq '.config.size + ([.layers[].size] | add)' | numfmt --to=iec
79```
80
81For image indexes, you can pass the `--platform` flag to `crane` to get a platform-specific image.
82
83### Filter irrelevant platforms from a multi-platform image
84
85Perhaps you use a base image that supports a wide variety of exotic platforms, but you only care about linux/amd64 and linux/arm64.
86If you want to copy that base image into a different registry, you will end up with a bunch of images you don't use.
87You can filter the base to include only platforms that are relevant to you.
88
89```
90crane index filter ubuntu --platform linux/amd64 --platform linux/arm64 -t ${IMAGE}
91```
92
93Note that this will obviously modify the digest of the multi-platform image you're using, so this may invalidate other artifacts that reference it, e.g. signatures.
94
95### Create a multi-platform image from scratch
96
97If you have a bunch of platform-specific images that you want to turn into a multi-platform image, `crane index append` can do that:
98
99```
100crane index append -t ${IMAGE} \
101 -m ubuntu@sha256:c985bc3f77946b8e92c9a3648c6f31751a7dd972e06604785e47303f4ad47c4c \
102 -m ubuntu@sha256:61bd0b97000996232eb07b8d0e9375d14197f78aa850c2506417ef995a7199a7
103```
104
105Note that this is less flexible than [`manifest-tool`](https://github.com/estesp/manifest-tool) because it derives the platform from each image's config file, but it should work in most cases.
View as plain text