oci

Documentation

Overview

Package oci contains functionality for working with Open Container Initiative (OCI) images and containers.

Index

• func ParseCertificatesFromPath(path string) (*x509.CertPool, error)
• type CachingPuller
  • func NewCachingPuller(h HashCache, i ImageCache, r ImageClient) *CachingPuller
  • func (f *CachingPuller) Image(ctx context.Context, r name.Reference, o ...ImageClientOption) (ociv1.Image, error)
• type HashCache
• type ImageCache
• type ImageClient
• type ImageClientOption
  • func WithCustomCA(rootCAs *x509.CertPool) ImageClientOption
  • func WithPullAuth(a *ImagePullAuth) ImageClientOption
  • func WithPullPolicy(p ImagePullPolicy) ImageClientOption
• type ImageClientOptions
• type ImagePullAuth
  • func (a ImagePullAuth) Authorization() (*authn.AuthConfig, error)
• type ImagePullPolicy
• type RemoteClient
  • func (i *RemoteClient) Image(ctx context.Context, ref name.Reference, o ...ImageClientOption) (ociv1.Image, error)

Functions

func ParseCertificatesFromPath

func ParseCertificatesFromPath(path string) (*x509.CertPool, error)

ParseCertificatesFromPath parses PEM file containing extra x509 certificates(s) and combines them with the built in root CA CertPool.

Types

type CachingPuller

type CachingPuller struct {
	// contains filtered or unexported fields
}

A CachingPuller pulls OCI images. Images are pulled either from a local cache or a remote depending on whether they are available locally and a supplied ImagePullPolicy.

func NewCachingPuller

func NewCachingPuller(h HashCache, i ImageCache, r ImageClient) *CachingPuller

NewCachingPuller returns an OCI image puller with a local cache.

func (*CachingPuller) Image

func (f *CachingPuller) Image(ctx context.Context, r name.Reference, o ...ImageClientOption) (ociv1.Image, error)

Image pulls the supplied image and all of its layers. The supplied config determines where the image may be pulled from - i.e. the local store or a remote. Images that are pulled from a remote are cached in the local store.

type HashCache

type HashCache interface {
	Hash(r name.Reference) (ociv1.Hash, error)
	WriteHash(r name.Reference, h ociv1.Hash) error
}

A HashCache maps OCI references to hashes.

type ImageCache

type ImageCache interface {
	Image(h ociv1.Hash) (ociv1.Image, error)
	WriteImage(img ociv1.Image) error
}

An ImageCache caches OCI images.

type ImageClient

type ImageClient interface {
	// Image pulls an OCI image.
	Image(ctx context.Context, ref name.Reference, o ...ImageClientOption) (ociv1.Image, error)
}

An ImageClient is an OCI registry client.

type ImageClientOption

type ImageClientOption func(c *ImageClientOptions)

An ImageClientOption configures an ImageClient.

func WithCustomCA

func WithCustomCA(rootCAs *x509.CertPool) ImageClientOption

WithCustomCA adds given root certificates to tls client configuration

func WithPullAuth

func WithPullAuth(a *ImagePullAuth) ImageClientOption

WithPullAuth specifies how a client should authenticate to a remote.

func WithPullPolicy

func WithPullPolicy(p ImagePullPolicy) ImageClientOption

WithPullPolicy specifies whether a client may pull from a remote.

type ImageClientOptions

type ImageClientOptions struct {
	// contains filtered or unexported fields
}

ImageClientOptions configure an ImageClient.

type ImagePullAuth

type ImagePullAuth struct {
	Username string
	Password string
	Auth     string

	// IdentityToken is used to authenticate the user and get
	// an access token for the registry.
	IdentityToken string

	// RegistryToken is a bearer token to be sent to a registry.
	RegistryToken string
}

ImagePullAuth configures authentication to a remote registry.

func (ImagePullAuth) Authorization

func (a ImagePullAuth) Authorization() (*authn.AuthConfig, error)

Authorization builds a go-containerregistry compatible AuthConfig.

type ImagePullPolicy

type ImagePullPolicy string

An ImagePullPolicy dictates when an image may be pulled from a remote.

const (
	// ImagePullPolicyIfNotPresent only pulls from a remote if the image is not
	// in the local cache. It is equivalent to ImagePullPolicyNever with a
	// fall-back to ImagePullPolicyAlways.
	ImagePullPolicyIfNotPresent ImagePullPolicy = "IfNotPresent"

	// ImagePullPolicyAlways always pulls at least the image manifest from the
	// remote. Layers are pulled if they are not in cache.
	ImagePullPolicyAlways ImagePullPolicy = "Always"

	// ImagePullPolicyNever never pulls anything from the remote. It resolves
	// OCI references to digests (i.e. SHAs) using a local cache of known
	// mappings.
	ImagePullPolicyNever ImagePullPolicy = "Never"
)

Image pull policies

type RemoteClient

type RemoteClient struct{}

A RemoteClient fetches OCI image manifests.

func (*RemoteClient) Image

func (i *RemoteClient) Image(ctx context.Context, ref name.Reference, o ...ImageClientOption) (ociv1.Image, error)

Image fetches an image manifest. The returned image lazily pulls its layers.