Documentation ¶
Overview ¶
Package remote provides facilities for reading/writing v1.Images from/to a remote image registry.
Index ¶
- Variables
- func Catalog(ctx context.Context, target name.Registry, options ...Option) ([]string, error)
- func CatalogPage(target name.Registry, last string, n int, options ...Option) ([]string, error)
- func CheckPushPermission(ref name.Reference, kc authn.Keychain, t http.RoundTripper) error
- func Delete(ref name.Reference, options ...Option) error
- func Head(ref name.Reference, options ...Option) (*v1.Descriptor, error)
- func Image(ref name.Reference, options ...Option) (v1.Image, error)
- func Index(ref name.Reference, options ...Option) (v1.ImageIndex, error)
- func Layer(ref name.Digest, options ...Option) (v1.Layer, error)
- func List(repo name.Repository, options ...Option) ([]string, error)
- func ListWithContext(ctx context.Context, repo name.Repository, options ...Option) ([]string, error)deprecated
- func MultiWrite(todo map[name.Reference]Taggable, options ...Option) (rerr error)
- func Push(ref name.Reference, t Taggable, options ...Option) (rerr error)
- func Put(ref name.Reference, t Taggable, options ...Option) error
- func Referrers(d name.Digest, options ...Option) (v1.ImageIndex, error)
- func Tag(tag name.Tag, t Taggable, options ...Option) error
- func WithNondistributable(o *options) error
- func Write(ref name.Reference, img v1.Image, options ...Option) (rerr error)
- func WriteIndex(ref name.Reference, ii v1.ImageIndex, options ...Option) (rerr error)
- func WriteLayer(repo name.Repository, layer v1.Layer, options ...Option) (rerr error)
- type Backoff
- type Catalogger
- type Catalogs
- type Descriptor
- type Lister
- type MountableLayer
- type Option
- func Reuse[I *Puller | *Pusher](i I) Option
- func WithAuth(auth authn.Authenticator) Option
- func WithAuthFromKeychain(keys authn.Keychain) Option
- func WithContext(ctx context.Context) Option
- func WithFilter(key string, value string) Option
- func WithJobs(jobs int) Option
- func WithPageSize(size int) Option
- func WithPlatform(p v1.Platform) Option
- func WithProgress(updates chan<- v1.Update) Option
- func WithRetryBackoff(backoff Backoff) Option
- func WithRetryPredicate(predicate retry.Predicate) Option
- func WithRetryStatusCodes(codes ...int) Option
- func WithTransport(t http.RoundTripper) Option
- func WithUserAgent(ua string) Option
- type Puller
- func (p *Puller) Catalog(ctx context.Context, reg name.Registry) ([]string, error)
- func (p *Puller) Catalogger(ctx context.Context, reg name.Registry) (*Catalogger, error)
- func (p *Puller) Get(ctx context.Context, ref name.Reference) (*Descriptor, error)
- func (p *Puller) Head(ctx context.Context, ref name.Reference) (*v1.Descriptor, error)
- func (p *Puller) Layer(ctx context.Context, ref name.Digest) (v1.Layer, error)
- func (p *Puller) List(ctx context.Context, repo name.Repository) ([]string, error)
- func (p *Puller) Lister(ctx context.Context, repo name.Repository) (*Lister, error)
- type Pusher
- func (p *Pusher) Delete(ctx context.Context, ref name.Reference) error
- func (p *Pusher) Push(ctx context.Context, ref name.Reference, t Taggable) error
- func (p *Pusher) Put(ctx context.Context, ref name.Reference, t Taggable) error
- func (p *Pusher) Upload(ctx context.Context, repo name.Repository, l v1.Layer) error
- type Taggable
- type Tags
Constants ¶
This section is empty.
Variables ¶
var DefaultTransport http.RoundTripper = &http.Transport{ Proxy: http.ProxyFromEnvironment, DialContext: (&net.Dialer{ Timeout: 30 * time.Second, KeepAlive: 30 * time.Second, }).DialContext, ForceAttemptHTTP2: true, MaxIdleConns: 100, IdleConnTimeout: 90 * time.Second, TLSHandshakeTimeout: 10 * time.Second, ExpectContinueTimeout: 1 * time.Second, MaxIdleConnsPerHost: 50, }
DefaultTransport is based on http.DefaultTransport with modifications documented inline below.
var ErrSchema1 = errors.New("see https://github.com/google/go-containerregistry/issues/377")
ErrSchema1 indicates that we received a schema1 manifest from the registry. This library doesn't have plans to support this legacy image format: https://github.com/google/go-containerregistry/issues/377
Functions ¶
func CatalogPage ¶
CatalogPage calls /_catalog, returning the list of repositories on the registry.
func CheckPushPermission ¶
CheckPushPermission returns an error if the given keychain cannot authorize a push operation to the given ref.
This can be useful to check whether the caller has permission to push an image before doing work to construct the image.
TODO(#412): Remove the need for this method.
func Head ¶
Head returns a v1.Descriptor for the given reference by issuing a HEAD request.
Note that the server response will not have a body, so any errors encountered should be retried with Get to get more details.
func Layer ¶
Layer reads the given blob reference from a registry as a Layer. A blob reference here is just a punned name.Digest where the digest portion is the digest of the blob to be read and the repository portion is the repo where that blob lives.
func List ¶
func List(repo name.Repository, options ...Option) ([]string, error)
List calls /tags/list for the given repository, returning the list of tags in the "tags" property.
func ListWithContext
deprecated
func MultiWrite ¶
MultiWrite writes the given Images or ImageIndexes to the given refs, as efficiently as possible, by deduping shared layer blobs while uploading them in parallel.
func Put ¶
Put adds a manifest from the given Taggable via PUT /v1/.../manifest/<ref>
Notable implementations of Taggable are v1.Image, v1.ImageIndex, and remote.Descriptor.
If t implements MediaType, we will use that for the Content-Type, otherwise we will default to types.DockerManifestSchema2.
Put does not attempt to write anything other than the manifest, so callers should ensure that all blobs or manifests that are referenced by t exist in the target registry.
func Referrers ¶
Referrers returns a list of descriptors that refer to the given manifest digest.
The subject manifest doesn't have to exist in the registry for there to be descriptors that refer to it.
func Tag ¶
Tag adds a tag to the given Taggable via PUT /v2/.../manifests/<tag>
Notable implementations of Taggable are v1.Image, v1.ImageIndex, and remote.Descriptor.
If t implements MediaType, we will use that for the Content-Type, otherwise we will default to types.DockerManifestSchema2.
Tag does not attempt to write anything other than the manifest, so callers should ensure that all blobs or manifests that are referenced by t exist in the target registry.
func WithNondistributable ¶
func WithNondistributable(o *options) error
WithNondistributable includes non-distributable (foreign) layers when writing images, see: https://github.com/opencontainers/image-spec/blob/master/layer.md#non-distributable-layers
The default behaviour is to skip these layers
func WriteIndex ¶
WriteIndex pushes the provided ImageIndex to the specified image reference. WriteIndex will attempt to push all of the referenced manifests before attempting to push the ImageIndex, to retain referential integrity.
func WriteLayer ¶
WriteLayer uploads the provided Layer to the specified repo.
Types ¶
type Backoff ¶
Backoff is an alias of retry.Backoff to expose this configuration option to consumers of this lib
type Catalogger ¶
type Catalogger struct {
// contains filtered or unexported fields
}
func (*Catalogger) HasNext ¶
func (l *Catalogger) HasNext() bool
type Descriptor ¶
type Descriptor struct { v1.Descriptor Manifest []byte // contains filtered or unexported fields }
Descriptor provides access to metadata about remote artifact and accessors for efficiently converting it into a v1.Image or v1.ImageIndex.
func Get ¶
func Get(ref name.Reference, options ...Option) (*Descriptor, error)
Get returns a remote.Descriptor for the given reference. The response from the registry is left un-interpreted, for the most part. This is useful for querying what kind of artifact a reference represents.
See Head if you don't need the response body.
func (*Descriptor) Image ¶
func (d *Descriptor) Image() (v1.Image, error)
Image converts the Descriptor into a v1.Image.
If the fetched artifact is already an image, it will just return it.
If the fetched artifact is an index, it will attempt to resolve the index to a child image with the appropriate platform.
See WithPlatform to set the desired platform.
func (*Descriptor) ImageIndex ¶
func (d *Descriptor) ImageIndex() (v1.ImageIndex, error)
ImageIndex converts the Descriptor into a v1.ImageIndex.
func (*Descriptor) RawManifest ¶
func (d *Descriptor) RawManifest() ([]byte, error)
RawManifest exists to satisfy the Taggable interface.
func (*Descriptor) Schema1 ¶
func (d *Descriptor) Schema1() (v1.Image, error)
Schema1 converts the Descriptor into a v1.Image for v2 schema 1 media types.
The v1.Image returned by this method does not implement the entire interface because it would be inefficient. This exists mostly to make it easier to copy schema 1 images around or look at their filesystems. This is separate from Image() to avoid a backward incompatible change for callers expecting ErrSchema1.
type MountableLayer ¶
MountableLayer wraps a v1.Layer in a shim that enables the layer to be "mounted" when published to another registry.
func (*MountableLayer) Descriptor ¶
func (ml *MountableLayer) Descriptor() (*v1.Descriptor, error)
Descriptor retains the original descriptor from an image manifest. See partial.Descriptor.
func (*MountableLayer) Exists ¶
func (ml *MountableLayer) Exists() (bool, error)
Exists is a hack. See partial.Exists.
type Option ¶
type Option func(*options) error
Option is a functional option for remote operations.
func Reuse ¶
Reuse takes a Puller or Pusher and reuses it for remote interactions rather than starting from a clean slate. For example, it will reuse token exchanges when possible and avoid sending redundant HEAD requests.
Reuse will take precedence over other options passed to most remote functions because most options deal with setting up auth and transports, which Reuse intetionally skips.
func WithAuth ¶
func WithAuth(auth authn.Authenticator) Option
WithAuth is a functional option for overriding the default authenticator for remote operations. It is an error to use both WithAuth and WithAuthFromKeychain in the same Option set.
The default authenticator is authn.Anonymous.
func WithAuthFromKeychain ¶
WithAuthFromKeychain is a functional option for overriding the default authenticator for remote operations, using an authn.Keychain to find credentials. It is an error to use both WithAuth and WithAuthFromKeychain in the same Option set.
The default authenticator is authn.Anonymous.
func WithContext ¶
WithContext is a functional option for setting the context in http requests performed by a given function. Note that this context is used for _all_ http requests, not just the initial volley. E.g., for remote.Image, the context will be set on http requests generated by subsequent calls to RawConfigFile() and even methods on layers returned by Layers().
The default context is context.Background().
func WithFilter ¶
WithFilter sets the filter querystring for HTTP operations.
func WithJobs ¶
WithJobs is a functional option for setting the parallelism of remote operations performed by a given function. Note that not all remote operations support parallelism.
The default value is 4.
func WithPageSize ¶
WithPageSize sets the given size as the value of parameter 'n' in the request.
To omit the `n` parameter entirely, use WithPageSize(0). The default value is 1000.
func WithPlatform ¶
WithPlatform is a functional option for overriding the default platform that Image and Descriptor.Image use for resolving an index to an image.
The default platform is amd64/linux.
func WithProgress ¶
WithProgress takes a channel that will receive progress updates as bytes are written.
Sending updates to an unbuffered channel will block writes, so callers should provide a buffered channel to avoid potential deadlocks.
func WithRetryBackoff ¶
WithRetryBackoff sets the httpBackoff for retry HTTP operations.
func WithRetryPredicate ¶
WithRetryPredicate sets the predicate for retry HTTP operations.
func WithRetryStatusCodes ¶
WithRetryStatusCodes sets which http response codes will be retried.
func WithTransport ¶
func WithTransport(t http.RoundTripper) Option
WithTransport is a functional option for overriding the default transport for remote operations. If transport.Wrapper is provided, this signals that the consumer does *not* want any further wrapping to occur. i.e. logging, retry and useragent
The default transport is DefaultTransport.
func WithUserAgent ¶
WithUserAgent adds the given string to the User-Agent header for any HTTP requests. This header will also include "go-containerregistry/${version}".
If you want to completely overwrite the User-Agent header, use WithTransport.
type Puller ¶
type Puller struct {
// contains filtered or unexported fields
}
func (*Puller) Catalog ¶
Catalog lists repos in a registry and handles pagination, returning the full list of repos.
func (*Puller) Catalogger ¶
Catalogger lists repos in a registry and returns a Catalogger for paginating through the results.
type Pusher ¶
type Pusher struct {
// contains filtered or unexported fields
}
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
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. |