Crane: Remote Container Swiss Army Knife

TL;DR #

Google’s crane is a lightweight CLI tool for interacting with container registries remotely. This allows you to mutate images without pulling them to localhost - even adding layers directly to remote registries. Perfect for CI/CD workflows where you need fast, efficient image operations without the overhead of local Docker pulls.

Key Operations #

Registry Authentication Required: You must authenticate with the registry before performing operations.

Image Retag #

Tag existing remote images without pulling:

$ crane tag registry.example.com/library/ubuntu:v0 v1

This eliminates the traditional workflow of pull → tag → push by operating directly on the registry.

Export Files #

List files in an image without pulling:

$ crane export ubuntu - | tar -tvf - | less

Extract specific files from remote images:

$ crane export ubuntu - | tar -Oxf - etc/passwd

$ crane export ubuntu - | tar -Oxf - etc/hostname > hostname.txt

The export command streams the entire image as a tar archive to stdout (-), allowing you to pipe it directly to standard Unix tools. This is particularly useful for inspecting image contents or extracting configuration files without local storage overhead.

You can use dive for this use case too, but crane export is a more lightweight and faster solution for file extraction without the interactive overhead.

Get Config #

Inspect image configuration without pulling:

$ crane config busybox:1.33

Compare configurations between image versions:

$ diff <(crane config busybox:1.32 | jq) <(crane config busybox:1.33 | jq)

This reveals environment variables, entrypoints, working directories, and other image metadata directly from the registry.

Append #

Add layers to remote images without local pulls:

This is actually the feature that first introduced me to this tool - the ability to append layers directly to remote images.

$ echo "custom content" > myfile.txt
$ tar -czf myfile.tar.gz myfile.txt
$ crane append -b ubuntu:22.04 -f myfile.tar.gz -t registry.example.com/myapp:custom

The append command takes a base image (-b), adds new layers from tarballs (-f), and creates a new tagged image (-t) directly in the registry, bypassing the need for local Docker builds or intermediate storage.

See how powerful this command is? Imagine you have a CUDA image that’s 5GB to build - with crane append, you can add your application layer without downloading that massive base image.

Traditional Docker workflow vs Crane append:

With crane append, you’re only transferring the new layer content - not the entire base image. This makes it incredibly efficient for adding small customizations to large base images.

Wrapping Up #

These operations represent just a glimpse of what crane offers for optimizing CI/CD workflows. By enabling direct registry manipulation, crane shifts how we think about container operations - moving from local-first to registry-first approaches.

The core value proposition is network efficiency: instead of downloading gigabytes to perform simple operations, crane works directly with remote registries. This translates to faster pipelines, reduced bandwidth costs, and more efficient resource utilization across your delivery process.

What I’d covered here are just the one I found useful to start with. Crane supports many more use cases.

📚 References #

• Official crane documentation
• Crane recipes and examples
• Go containerregistry project