README
¶
go-containerregistry
Introduction
This is a golang library for working with container registries. It's largely based on the Python library of the same name.
The following diagram shows the main types that this library handles.
Philosophy
The overarching design philosophy of this library is to define interfaces that present an immutable
view of resources (e.g. Image,
Layer,
ImageIndex),
which can be backed by a variety of medium (e.g. registry,
tarball, daemon, ...).
To complement these immutable views, we support functional mutations that produce new immutable views of the resulting resource (e.g. mutate). The end goal is to provide a set of versatile primitives that can compose to do extraordinarily powerful things efficiently and easily.
Both the resource views and mutations may be lazy, eager, memoizing, etc, and most are optimized for common paths based on the tooling we have seen in the wild (e.g. writing new images from disk to the registry as a compressed tarball).
Experiments
Over time, we will add new functionality under experimental environment variables listed here.
| Env Var | Value(s) | What is does |
|---|---|---|
GGCR_EXPERIMENT_ESTARGZ |
"1" |
⚠️DEPRECATED⚠️: When enabled this experiment will direct tarball.LayerFromOpener to emit estargz compatible layers, which enable them to be lazily loaded by an appropriately configured containerd. |
v1.Image
Sources
Sinks
v1.ImageIndex
Sources
Sinks
v1.Layer
Sources
Sinks
Overview
mutate
The simplest use for these libraries is to read from one source and write to another.
For example,
crane pullisremote.Image -> tarball.Write,crane pushistarball.Image -> remote.Write,crane cpisremote.Image -> remote.Write.
However, often you actually want to change something about an image.
This is the purpose of the mutate package, which exposes
some commonly useful things to change about an image.
partial
If you're trying to use this library with a different source or sink than it already supports,
it can be somewhat cumbersome. The Image and Layer interfaces are pretty wide, with a lot
of redundant information. This is somewhat by design, because we want to expose this information
as efficiently as possible where we can, but again it is a pain to implement yourself.
The purpose of the partial package is to make implementing a v1.Image
much easier, by filling in all the derived accessors for you if you implement a minimal
subset of v1.Image.
transport
You might think our abstractions are bad and you just want to authenticate and send requests to a registry.
This is the purpose of the transport and authn packages.
Tools
This repo hosts some tools built on top of the library.
crane
crane is a tool for interacting with remote images
and registries.
gcrane
gcrane is a GCR-specific variant of crane that has
richer output for the ls subcommand and some basic garbage collection support.
krane
krane is a drop-in replacement for crane that supports
common Kubernetes-based workload identity mechanisms using k8schain
as a fallback to traditional authentication mechanisms.
k8schain
k8schain implements the authentication
semantics used by kubelets in a way that is easily consumable by this library.
k8schain is not a standalone tool, but it is linked here for visibility.
Emeritus: ko
This tool was originally developed in this repo but has since been moved to its own repo.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
and
Package and provides helpers for adding Close to io.{Reader|Writer}.
|
Package and provides helpers for adding Close to io.{Reader|Writer}. |
|
compare
Package compare provides methods for comparing images, indexes, and layers.
|
Package compare provides methods for comparing images, indexes, and layers. |
|
compression
Package compression abstracts over gzip and zstd.
|
Package compression abstracts over gzip and zstd. |
|
depcheck
Package depcheck defines a test utility for ensuring certain packages don't take on heavy dependencies.
|
Package depcheck defines a test utility for ensuring certain packages don't take on heavy dependencies. |
|
editor
Package editor implements a simple interface for interactive file editing.
|
Package editor implements a simple interface for interactive file editing. |
|
estargz
Package estargz adapts the containerd estargz package to our abstractions.
|
Package estargz adapts the containerd estargz package to our abstractions. |
|
gzip
Package gzip provides helper functions for interacting with gzipped streams.
|
Package gzip provides helper functions for interacting with gzipped streams. |
|
httptest
Package httptest provides a method for testing a TLS server a la net/http/httptest.
|
Package httptest provides a method for testing a TLS server a la net/http/httptest. |
|
redact
Package redact contains a simple context signal for redacting requests.
|
Package redact contains a simple context signal for redacting requests. |
|
retry
Package retry provides methods for retrying operations.
|
Package retry provides methods for retrying operations. |
|
retry/wait
Package wait is a subset of k8s.io/apimachinery to avoid conflicts in dependencies (specifically, logging).
|
Package wait is a subset of k8s.io/apimachinery to avoid conflicts in dependencies (specifically, logging). |
|
verify
Package verify provides a ReadCloser that verifies content matches the expected hash values.
|
Package verify provides a ReadCloser that verifies content matches the expected hash values. |
|
zstd
Package zstd provides helper functions for interacting with zstd streams.
|
Package zstd provides helper functions for interacting with zstd streams. |
|
pkg
|
|
|
authn
Package authn defines different methods of authentication for talking to a container registry.
|
Package authn defines different methods of authentication for talking to a container registry. |
|
authn/github
Package github provides a keychain for the GitHub Container Registry.
|
Package github provides a keychain for the GitHub Container Registry. |
|
compression
Package compression abstracts over gzip and zstd.
|
Package compression abstracts over gzip and zstd. |
|
crane
Package crane holds libraries used to implement the crane CLI.
|
Package crane holds libraries used to implement the crane CLI. |
|
gcrane
Package gcrane holds libraries used to implement the gcrane CLI.
|
Package gcrane holds libraries used to implement the gcrane CLI. |
|
legacy
Package legacy provides functionality to work with docker images in the v1 format.
|
Package legacy provides functionality to work with docker images in the v1 format. |
|
legacy/tarball
Package tarball provides facilities for writing v1 docker images (https://github.com/moby/moby/blob/master/image/spec/v1.md) from/to a tarball on-disk.
|
Package tarball provides facilities for writing v1 docker images (https://github.com/moby/moby/blob/master/image/spec/v1.md) from/to a tarball on-disk. |
|
logs
Package logs exposes the loggers used by this library.
|
Package logs exposes the loggers used by this library. |
|
name
Package name defines structured types for representing image references.
|
Package name defines structured types for representing image references. |
|
registry
Package registry implements a docker V2 registry and the OCI distribution specification.
|
Package registry implements a docker V2 registry and the OCI distribution specification. |
|
v1
Package v1 defines structured types for OCI v1 images
|
Package v1 defines structured types for OCI v1 images |
|
v1/cache
Package cache provides methods to cache layers.
|
Package cache provides methods to cache layers. |
|
v1/daemon
Package daemon provides facilities for reading/writing v1.Image from/to a running daemon.
|
Package daemon provides facilities for reading/writing v1.Image from/to a running daemon. |
|
v1/empty
Package empty provides an implementation of v1.Image equivalent to "FROM scratch".
|
Package empty provides an implementation of v1.Image equivalent to "FROM scratch". |
|
v1/fake
Code generated by counterfeiter.
|
Code generated by counterfeiter. |
|
v1/google
Package google provides facilities for listing images in gcr.io.
|
Package google provides facilities for listing images in gcr.io. |
|
v1/layout
Package layout provides facilities for reading/writing artifacts from/to an OCI image layout on disk, see:
|
Package layout provides facilities for reading/writing artifacts from/to an OCI image layout on disk, see: |
|
v1/match
Package match provides functionality for conveniently matching a v1.Descriptor.
|
Package match provides functionality for conveniently matching a v1.Descriptor. |
|
v1/mutate
Package mutate provides facilities for mutating v1.Images of any kind.
|
Package mutate provides facilities for mutating v1.Images of any kind. |
|
v1/partial
Package partial defines methods for building up a v1.Image from minimal subsets that are sufficient for defining a v1.Image.
|
Package partial defines methods for building up a v1.Image from minimal subsets that are sufficient for defining a v1.Image. |
|
v1/random
Package random provides a facility for synthesizing pseudo-random images.
|
Package random provides a facility for synthesizing pseudo-random images. |
|
v1/remote
Package remote provides facilities for reading/writing v1.Images from/to a remote image registry.
|
Package remote provides facilities for reading/writing v1.Images from/to a remote image registry. |
|
v1/remote/transport
Package transport provides facilities for setting up an authenticated http.RoundTripper given an Authenticator and base RoundTripper.
|
Package transport provides facilities for setting up an authenticated http.RoundTripper given an Authenticator and base RoundTripper. |
|
v1/stream
Package stream implements a single-pass streaming v1.Layer.
|
Package stream implements a single-pass streaming v1.Layer. |
|
v1/tarball
Package tarball provides facilities for reading/writing v1.Images from/to a tarball on-disk.
|
Package tarball provides facilities for reading/writing v1.Images from/to a tarball on-disk. |
|
v1/types
Package types holds common OCI media types.
|
Package types holds common OCI media types. |
|
v1/validate
Package validate provides methods for validating image correctness.
|
Package validate provides methods for validating image correctness. |