1# go-containerregistry
2
3[](https://github.com/google/go-containerregistry/actions?query=workflow%3ABuild)
4[](https://godoc.org/github.com/google/go-containerregistry)
5[](https://codecov.io/gh/google/go-containerregistry)
6
7## Introduction
8
9This is a golang library for working with container registries.
10It's largely based on the [Python library of the same name](https://github.com/google/containerregistry).
11
12The following diagram shows the main types that this library handles.
13
14
15## Philosophy
16
17The overarching design philosophy of this library is to define interfaces that present an immutable
18view of resources (e.g. [`Image`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1#Image),
19[`Layer`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1#Layer),
20[`ImageIndex`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1#ImageIndex)),
21which can be backed by a variety of medium (e.g. [registry](./pkg/v1/remote/README.md),
22[tarball](./pkg/v1/tarball/README.md), [daemon](./pkg/v1/daemon/README.md), ...).
23
24To complement these immutable views, we support functional mutations that produce new immutable views
25of the resulting resource (e.g. [mutate](./pkg/v1/mutate/README.md)). The end goal is to provide a
26set of versatile primitives that can compose to do extraordinarily powerful things efficiently and easily.
27
28Both the resource views and mutations may be lazy, eager, memoizing, etc, and most are optimized
29for common paths based on the tooling we have seen in the wild (e.g. writing new images from disk
30to the registry as a compressed tarball).
31
32
33### Experiments
34
35Over time, we will add new functionality under experimental environment variables listed here.
36
37| Env Var | Value(s) | What is does |
38|---------|----------|--------------|
39| `GGCR_EXPERIMENT_ESTARGZ` | `"1"` | ⚠️DEPRECATED⚠️: When enabled this experiment will direct `tarball.LayerFromOpener` to emit [estargz](https://github.com/opencontainers/image-spec/issues/815) compatible layers, which enable them to be lazily loaded by an appropriately configured containerd. |
40
41
42### `v1.Image`
43
44#### Sources
45
46* [`remote.Image`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#Image)
47* [`tarball.Image`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/tarball#Image)
48* [`daemon.Image`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/daemon#Image)
49* [`layout.Image`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/layout#Path.Image)
50* [`random.Image`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/random#Image)
51
52#### Sinks
53
54* [`remote.Write`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#Write)
55* [`tarball.Write`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/tarball#Write)
56* [`daemon.Write`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/daemon#Write)
57* [`legacy/tarball.Write`](https://godoc.org/github.com/google/go-containerregistry/pkg/legacy/tarball#Write)
58* [`layout.AppendImage`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/layout#Path.AppendImage)
59
60### `v1.ImageIndex`
61
62#### Sources
63
64* [`remote.Index`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#Index)
65* [`random.Index`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/random#Index)
66* [`layout.ImageIndexFromPath`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/layout#ImageIndexFromPath)
67
68#### Sinks
69
70* [`remote.WriteIndex`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#WriteIndex)
71* [`layout.Write`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/layout#Write)
72
73### `v1.Layer`
74
75#### Sources
76
77* [`remote.Layer`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#Layer)
78* [`tarball.LayerFromFile`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/tarball#LayerFromFile)
79* [`random.Layer`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/random#Layer)
80* [`stream.Layer`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/stream#Layer)
81
82#### Sinks
83
84* [`remote.WriteLayer`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#WriteLayer)
85
86## Overview
87
88### `mutate`
89
90The simplest use for these libraries is to read from one source and write to another.
91
92For example,
93
94 * `crane pull` is `remote.Image -> tarball.Write`,
95 * `crane push` is `tarball.Image -> remote.Write`,
96 * `crane cp` is `remote.Image -> remote.Write`.
97
98However, often you actually want to _change something_ about an image.
99This is the purpose of the [`mutate`](pkg/v1/mutate) package, which exposes
100some commonly useful things to change about an image.
101
102### `partial`
103
104If you're trying to use this library with a different source or sink than it already supports,
105it can be somewhat cumbersome. The `Image` and `Layer` interfaces are pretty wide, with a lot
106of redundant information. This is somewhat by design, because we want to expose this information
107as efficiently as possible where we can, but again it is a pain to implement yourself.
108
109The purpose of the [`partial`](pkg/v1/partial) package is to make implementing a `v1.Image`
110much easier, by filling in all the derived accessors for you if you implement a minimal
111subset of `v1.Image`.
112
113### `transport`
114
115You might think our abstractions are bad and you just want to authenticate
116and send requests to a registry.
117
118This is the purpose of the [`transport`](pkg/v1/remote/transport) and [`authn`](pkg/authn) packages.
119
120## Tools
121
122This repo hosts some tools built on top of the library.
123
124### `crane`
125
126[`crane`](cmd/crane/README.md) is a tool for interacting with remote images
127and registries.
128
129### `gcrane`
130
131[`gcrane`](cmd/gcrane/README.md) is a GCR-specific variant of `crane` that has
132richer output for the `ls` subcommand and some basic garbage collection support.
133
134### `krane`
135
136[`krane`](cmd/krane/README.md) is a drop-in replacement for `crane` that supports
137common Kubernetes-based workload identity mechanisms using [`k8schain`](#k8schain)
138as a fallback to traditional authentication mechanisms.
139
140### `k8schain`
141
142[`k8schain`](pkg/authn/k8schain/README.md) implements the authentication
143semantics used by kubelets in a way that is easily consumable by this library.
144
145`k8schain` is not a standalone tool, but it is linked here for visibility.
146
147### Emeritus: [`ko`](https://github.com/google/ko)
148
149This tool was originally developed in this repo but has since been moved to its
150own repo.
View as plain text