1# `remote`
2
3[](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote)
4
5The `remote` package implements a client for accessing a registry,
6per the [OCI distribution spec](https://github.com/opencontainers/distribution-spec/blob/master/spec.md).
7
8It leans heavily on the lower level [`transport`](/pkg/v1/remote/transport) package, which handles the
9authentication handshake and structured errors.
10
11## Usage
12
13```go
14package main
15
16import (
17 "github.com/google/go-containerregistry/pkg/authn"
18 "github.com/google/go-containerregistry/pkg/name"
19 "github.com/google/go-containerregistry/pkg/v1/remote"
20)
21
22func main() {
23 ref, err := name.ParseReference("gcr.io/google-containers/pause")
24 if err != nil {
25 panic(err)
26 }
27
28 img, err := remote.Image(ref, remote.WithAuthFromKeychain(authn.DefaultKeychain))
29 if err != nil {
30 panic(err)
31 }
32
33 // do stuff with img
34}
35```
36
37## Structure
38
39<p align="center">
40 <img src="/images/remote.dot.svg" />
41</p>
42
43
44## Background
45
46There are a lot of confusingly similar terms that come up when talking about images in registries.
47
48### Anatomy of an image
49
50In general...
51
52* A tag refers to an image manifest.
53* An image manifest references a config file and an orderered list of _compressed_ layers by sha256 digest.
54* A config file references an ordered list of _uncompressed_ layers by sha256 digest and contains runtime configuration.
55* The sha256 digest of the config file is the [image id](https://github.com/opencontainers/image-spec/blob/master/config.md#imageid) for the image.
56
57For example, an image with two layers would look something like this:
58
59
60
61### Anatomy of an index
62
63In the normal case, an [index](https://github.com/opencontainers/image-spec/blob/master/image-index.md) is used to represent a multi-platform image.
64This was the original use case for a [manifest
65list](https://docs.docker.com/registry/spec/manifest-v2-2/#manifest-list).
66
67
68
69It is possible for an index to reference another index, per the OCI
70[image-spec](https://github.com/opencontainers/image-spec/blob/master/media-types.md#compatibility-matrix).
71In theory, both an image and image index can reference arbitrary things via
72[descriptors](https://github.com/opencontainers/image-spec/blob/master/descriptor.md),
73e.g. see the [image layout
74example](https://github.com/opencontainers/image-spec/blob/master/image-layout.md#index-example),
75which references an application/xml file from an image index.
76
77That could look something like this:
78
79
80
81Using a recursive index like this might not be possible with all registries,
82but this flexibility allows for some interesting applications, e.g. the
83[OCI Artifacts](https://github.com/opencontainers/artifacts) effort.
84
85### Anatomy of an image upload
86
87The structure of an image requires a delicate ordering when uploading an image to a registry.
88Below is a (slightly simplified) figure that describes how an image is prepared for upload
89to a registry and how the data flows between various artifacts:
90
91
92
93Note that:
94
95* A config file references the uncompressed layer contents by sha256.
96* A manifest references the compressed layer contents by sha256 and the size of the layer.
97* A manifest references the config file contents by sha256 and the size of the file.
98
99It follows that during an upload, we need to upload layers before the config file,
100and we need to upload the config file before the manifest.
101
102Sometimes, we know all of this information ahead of time, (e.g. when copying from remote.Image),
103so the ordering is less important.
104
105In other cases, e.g. when using a [`stream.Layer`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/stream#Layer),
106we can't compute anything until we have already uploaded the layer, so we need to be careful about ordering.
107
108## Caveats
109
110### schema 1
111
112This package does not support schema 1 images, see [`#377`](https://github.com/google/go-containerregistry/issues/377),
113however, it's possible to do _something_ useful with them via [`remote.Get`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote#Get),
114which doesn't try to interpret what is returned by the registry.
115
116[`crane.Copy`](https://godoc.org/github.com/google/go-containerregistry/pkg/crane#Copy) takes advantage of this to implement support for copying schema 1 images,
117see [here](https://github.com/google/go-containerregistry/blob/main/pkg/internal/legacy/copy.go).
View as plain text