shortnames

Documentation

Index

• func Add(ctx *types.SystemContext, name string, value reference.Named) error
• func IsShortName(input string) bool
• func Remove(ctx *types.SystemContext, name string) error
• func ResolveLocally(ctx *types.SystemContext, name string) ([]reference.Named, error)
• type PullCandidate
  • func (c *PullCandidate) Record() error
• type Resolved
  • func Resolve(ctx *types.SystemContext, name string) (*Resolved, error)
  • func (r *Resolved) Description() string
  • func (r *Resolved) FormatPullErrors(pullErrors []error) error

Functions

func Add

func Add(ctx *types.SystemContext, name string, value reference.Named) error

Add records the specified name-value pair as a new short-name alias to the user-specific aliases.conf. It may override an existing alias for `name`.

func IsShortName

func IsShortName(input string) bool

IsShortName returns true if the specified input is a "short name". A "short name" refers to a container image without a fully-qualified reference, and is hence missing a registry (or domain). Names including a digest are not short names.

Examples:

• short names: "image:tag", "library/fedora"
• not short names: "quay.io/image", "localhost/image:tag", "server.org:5000/lib/image", "image@sha256:..."

func Remove

func Remove(ctx *types.SystemContext, name string) error

Remove clears the short-name alias for the specified name. It throws an error in case name does not exist in the machine-generated short-name-alias.conf. In such case, the alias must be specified in one of the registries.conf files, which is the users' responsibility.

func ResolveLocally

func ResolveLocally(ctx *types.SystemContext, name string) ([]reference.Named, error)

ResolveLocally resolves the specified name to either one or more local images. If the specified name is already a fully-qualified reference (i.e., not a short name), it is returned as is. In case, it's a short name, the returned slice of named references looks as follows:

1. If present, the short-name alias
2. "localhost/" as used by many container engines such as Podman and Buildah
3. Unqualified-search registries from the registries.conf files

Note that tags and digests are stripped from the specified name before looking up an alias. Stripped off tags and digests are later on appended to all candidates. If neither tag nor digest is specified, candidates are normalized with the "latest" tag. The returned slice contains at least one item.

Types

type PullCandidate

type PullCandidate struct {
	// Fully-qualified reference with tag or digest.
	Value reference.Named
	// contains filtered or unexported fields
}

PullCandidate is a resolved name. Once the Value has been used successfully, users MUST call `(*PullCandidate).Record(..)` to possibly record it as a new short-name alias.

func (*PullCandidate) Record

func (c *PullCandidate) Record() error

Record may store a short-name alias for the PullCandidate.

type Resolved

type Resolved struct {
	PullCandidates []PullCandidate
	// contains filtered or unexported fields
}

Resolved encapsulates all data for a resolved image name.

func Resolve

func Resolve(ctx *types.SystemContext, name string) (*Resolved, error)

Resolve resolves the specified name to either one or more fully-qualified image references that the short name may be *pulled* from. If the specified name is already a fully-qualified reference (i.e., not a short name), it is returned as is. In case, it's a short name, it's resolved according to the ShortNameMode in the SystemContext (if specified) or in the registries.conf.

Note that tags and digests are stripped from the specified name before looking up an alias. Stripped off tags and digests are later on appended to all candidates. If neither tag nor digest is specified, candidates are normalized with the "latest" tag. An error is returned if there is no matching alias and no unqualified-search registries are configured.

Note that callers *must* call `(PullCandidate).Record` after a returned item has been pulled successfully; this callback will record a new short-name alias (depending on the specified short-name mode).

Furthermore, before attempting to pull callers *should* call `(Resolved).Description` and afterwards use `(Resolved).FormatPullErrors` in case of pull errors.

func (*Resolved) Description

func (r *Resolved) Description() string

Description returns a human-readable description about the resolution process (e.g., short-name alias, unqualified-search registries, etc.). It is meant to be printed before attempting to pull the pull candidates to make the short-name resolution more transparent to user.

If the returned string is empty, it is not meant to be printed.

func (*Resolved) FormatPullErrors

func (r *Resolved) FormatPullErrors(pullErrors []error) error

FormatPullErrors is a convenience function to format errors that occurred while trying to pull all of the resolved pull candidates.

Note that nil is returned if len(pullErrors) == 0. Otherwise, the amount of pull errors must equal the amount of pull candidates.