images

package
v0.42.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 39 Imported by: 0

Documentation

Overview

Package images is functionality related to interacting with oci images. This also stems from zarf-dev/zarf

Index

Constants

View Source
const (
	// DockerMediaTypeManifest is the Legacy Docker manifest format, replaced by OCI manifest
	DockerMediaTypeManifest = "application/vnd.docker.distribution.manifest.v2+json"
	// DockerMediaTypeManifestList is the legacy Docker manifest list, replaced by OCI index
	DockerMediaTypeManifestList = "application/vnd.docker.distribution.manifest.list.v2+json"
)

Variables

This section is empty.

Functions

func CertPool added in v0.42.0

func CertPool(caBundle []byte) (*x509.CertPool, error)

CertPool is the system roots plus the PEM certificates in caBundle.

It lives here rather than beside its other caller in pkg/distro because a pull and a mirror both have to trust a private CA the same way, and pkg/distro imports this package while the reverse would be a cycle.

func DescriptorPlatform added in v0.40.0

func DescriptorPlatform(ctx context.Context, src content.Fetcher, desc ocispec.Descriptor) (*ocispec.Platform, error)

DescriptorPlatform fills in the platform of a manifest descriptor, reading the image config when the descriptor does not carry one. It returns nil for an artifact that names no architecture, which is not an error: a signature or an SBOM has no platform to report.

It is exported for a caller that merges several sources into one view of a reference and so has to know which platform each one's copy answers for.

func IsIndex added in v0.34.0

func IsIndex(mediaType string) bool

IsIndex reports whether the media type represents an OCI image index.

func IsManifest added in v0.34.0

func IsManifest(mediaType string) bool

IsManifest reports whether the media type represents an OCI manifest.

func NewRegistryClient added in v0.39.0

func NewRegistryClient(ctx context.Context, hosts []string, opts ClientOptions) (*auth.Client, error)

NewRegistryClient builds the ORAS auth client every registry operation shares, and pre-authenticates it against each host it is about to be used with.

The pre-authentication is synchronous and that is the point: some credential helpers open a browser, and doing this concurrently opens one tab per image from a host while authenticating in any one of them fails to propagate to the others. Pinging each host once here puts the credentials in the client's cache before any concurrent work starts.

A ping failure is deliberately ignored. A host may be a stand-in that never answers -- the faked registry behind the docker fallback is one -- and the operation that follows is the honest place for a connection error to surface.

It is exported because a mirror pushes files alongside images, and both halves have to authenticate to the target the same way or a credentialled registry takes one and refuses the other.

func Ping

func Ping(ctx context.Context, plainHTTP bool, registryURL string, client *auth.Client) (err error)

Ping verifies if a user can connect to a registry

func Push added in v0.39.0

func Push(ctx context.Context, imageList []transform.Image, sourceDirectory, target string, opts PushOptions) error

Push copies every image in imageList out of the OCI layout at sourceDirectory and into target, which is a registry host optionally followed by a repository prefix -- "harbor.internal" or "harbor.internal/cargoship".

The destination reference swaps the host and keeps everything else, so registry.k8s.io/pause:3.10 is pushed as <target>/pause:3.10. That rule is not a preference: cargoship configures the engine to reach a mirror through a containerd hosts.toml, and containerd asks a mirror for the repository path unchanged. A reference rewritten any other way -- zarf's crc32 tag among them -- would be one the node never asks for.

An image the package holds for several architectures is tagged in the layout as an OCI image index, and the index is copied whole, so the registry ends up holding every architecture the package carried. That is the opposite of what the upload phase does with the same layout, where a docker-save tarball describes one image and a platform has to be chosen.

func ShouldUsePlainHTTP

func ShouldUsePlainHTTP(ctx context.Context, registryURL string, client *auth.Client) (bool, error)

ShouldUsePlainHTTP returns true if the registryURL is an http endpoint This is inspired by the Crane functionality to determine the schema to be used - https://github.com/google/go-containerregistry/blob/main/pkg/v1/remote/transport/ping.go Zarf relies heavily on this logic, as the internal registry communicates over HTTP, however we want Zarf to be flexible should the registry be over https in the future

func StaticCredential added in v0.42.0

func StaticCredential(host, username, password string) auth.CredentialFunc

StaticCredential turns a username and password into something ClientOptions takes, and returns nil when neither was given -- which NewRegistryClient reads as "use the Docker configuration". It is exported because a mirror pushes files alongside images and both halves have to authenticate the same way.

func Transport added in v0.42.2

func Transport(opts ClientOptions) (*http.Transport, error)

Transport is the HTTP transport a set of ClientOptions implies: TLS as the CA bundle, the client certificate and InsecureSkipTLSVerify describe it, and the dialer where one carries the connection somewhere other than the reference's own host.

Exported because not every consumer of these settings reaches a registry through a client of ours. Zarf's OCI package takes an *http.Transport through oci.WithTransport, which is how a publish and a package pull reach a registry behind a tunnel or a private CA, and building the same thing a second time beside each of them is how two transports come to disagree about one registry. orasTransport is this plus the retry policy.

Types

type ClientCertificate added in v0.42.2

type ClientCertificate struct {
	// Certificate is the PEM-encoded certificate, and any intermediates it needs.
	Certificate []byte
	// Key is the PEM-encoded private key for it.
	Key []byte
}

ClientCertificate is a PEM-encoded client certificate and the key that goes with it, for a registry that requires one of every client.

It is the other half of CABundle: that one says which server certificates to trust, this one says what to present when the server asks. A zarf-managed registry needs only the first -- it is configured `clientauth: verify-client-cert-if-given`, so a certificate is verified where one is offered and never demanded -- while a Harbor or a Nexus set to require one needs this.

Bytes rather than paths, for the reason distro.LoadOptions.CABundle gives: a caller holding the pair in memory, a controller reading it out of a Kubernetes secret among them, does not have to write either to a file first.

func (ClientCertificate) IsZero added in v0.42.2

func (c ClientCertificate) IsZero() bool

IsZero reports whether neither half is set, which is the ordinary case.

func (ClientCertificate) Parse added in v0.42.2

func (c ClientCertificate) Parse() (tls.Certificate, error)

Parse returns the certificate as crypto/tls wants it.

A pair with one half missing is an error rather than a zero certificate: it is a credential somebody meant to supply, and the alternative is a TLS handshake the server closes with no indication of why.

type ClientOptions added in v0.42.0

type ClientOptions struct {
	InsecureSkipTLSVerify bool
	ResponseHeaderTimeout time.Duration
	// Credential authenticates every host the client is used with. Nil, which is the usual
	// case, reads credentials from the Docker configuration file instead.
	Credential auth.CredentialFunc
	// DialContext opens the TCP connection every registry request travels over. Nil, which is
	// the usual case, dials the reference's own host.
	//
	// Setting it decouples where the bytes go from what the reference says, which is what lets
	// a registry be reached through a tunnel: an SSH channel to a cluster node carries the
	// connection while the references stay the ones a node will ask for. The address the dialer
	// is handed is the reference's, and a tunnelling dialer is free to ignore it.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// CABundle is trusted in addition to the system roots. A registry serving a certificate
	// from a private CA -- which a zarf-managed-mTLS registry does -- is reached by supplying
	// its CA here, rather than by turning verification off.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one. Zero, which is the usual
	// case, presents none. See ClientCertificate.
	ClientCertificate ClientCertificate
}

ClientOptions are the transport and credential settings NewRegistryClient needs.

func (ClientOptions) IsZero added in v0.42.2

func (o ClientOptions) IsZero() bool

IsZero reports whether a set of options asks for nothing a default transport does not already do, in which case a caller handing a transport to somebody else should hand them none.

type ImageSource added in v0.38.0

type ImageSource interface {
	// HasImage reports whether the source holds ref, spelled as the image list spells it.
	HasImage(ref string) bool
	// Target resolves those same references to content.
	Target() oras.ReadOnlyTarget
	// Describe names the source in log lines.
	Describe() string
}

ImageSource is a local, already-populated source of images -- content that was collected elsewhere and carried in, rather than fetched from the registry the reference names.

type ImageWithManifest

type ImageWithManifest struct {
	Image    transform.Image
	Manifest ocispec.Manifest
}

ImageWithManifest represents an image reference and its associated OCI manifest.

func Pull

func Pull(ctx context.Context, imageList []transform.Image, destinationDirectory string, opts PullOptions) ([]ImageWithManifest, error)

Pull pulls all images to the destination directory.

type PullOptions

type PullOptions struct {
	OCIConcurrency int
	// Arches lists the CPU architectures to pull each image for. An image pulled for more than one
	// architecture is tagged as an OCI image index, so the architectures share whatever layers they
	// have in common instead of being stored twice.
	Arches                []string
	RegistryOverrides     []RegistryOverride
	CacheDirectory        string
	PlainHTTP             bool
	InsecureSkipTLSVerify bool
	ResponseHeaderTimeout time.Duration
	// Source is a local store of images, such as a hauler store, consulted before the
	// registry an image names. An image the source does not hold is pulled from its registry
	// as usual, so a partial source works.
	Source ImageSource
}

PullOptions is the configuration for pulling images.

type PushOptions added in v0.39.0

type PushOptions struct {
	OCIConcurrency        int
	PlainHTTP             bool
	InsecureSkipTLSVerify bool
	ResponseHeaderTimeout time.Duration
	// Retries is how many times a single image copy is attempted before the push fails.
	// Zero takes the same default the rest of the OCI paths use.
	Retries int
	// Username and Password authenticate the push against the target. Empty, which is the
	// usual case, falls back to the Docker configuration file.
	Username string
	Password string
	// DialContext opens the connection the push travels over. See ClientOptions.DialContext.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// CABundle is trusted in addition to the system roots. See ClientOptions.CABundle.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one. See ClientCertificate.
	ClientCertificate ClientCertificate
}

PushOptions is the configuration for pushing images out of a package's OCI layout.

type RegistryOverride

type RegistryOverride struct {
	// Source describes the source registry.
	// May be of the form:
	// - docker.io/library
	// - docker.io
	Source string
	// Override replaces the source registry as a string prefix.
	Override string
}

RegistryOverride describes an override for a specific registry.

func ApplyOverride added in v0.40.0

func ApplyOverride(ref string, overrides []RegistryOverride) (string, RegistryOverride, bool)

ApplyOverride rewrites ref through the first registry override whose source is a prefix of it, returning the rewritten reference, the override that matched, and whether one did.

The first match wins, which relies on the overrides being sorted longest prefix first -- ParseRegistryOverrides does that -- so that docker.io/library supersedes docker.io.

This is shared rather than inlined because an oci:// file source is a registry reference too, and an operator who redirects a registry means it for everything cargoship pulls from there. Two copies of a prefix rule would drift.

type Report

type Report func(bytesRead, totalBytes int64)

Report defines a function to log progress

func DefaultReport

func DefaultReport(l *slog.Logger, msg string, imageName string) Report

DefaultReport returns a default report function

type TrackedTarget

type TrackedTarget struct {
	oras.Target
	*Tracker
}

TrackedTarget wraps an oras.Target to track progress

func NewTrackedTarget

func NewTrackedTarget(target oras.Target, totalBytes int64, reporter Report) *TrackedTarget

NewTrackedTarget creates a new TrackedTarget

type Tracker

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

Tracker reports progress against totalBytes as bytesRead gets updated

func (*Tracker) StartReporting

func (tt *Tracker) StartReporting(ctx context.Context)

StartReporting starts the reporting goroutine

func (*Tracker) StopReporting

func (tt *Tracker) StopReporting()

StopReporting stops the reporting goroutine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL