sysregistriesv2

Documentation

Index

• func AddShortNameAlias(ctx *types.SystemContext, name string, value string) error
• func ConfigDirPath(ctx *types.SystemContext) string
• func ConfigPath(ctx *types.SystemContext) string
• func ConfigurationSourceDescription(ctx *types.SystemContext) string
• func GetShortNameMode(ctx *types.SystemContext) (types.ShortNameMode, error)
• func InvalidateCache()
• func RemoveShortNameAlias(ctx *types.SystemContext, name string) error
• func ResolveShortNameAlias(ctx *types.SystemContext, name string) (reference.Named, string, error)
• func UnqualifiedSearchRegistries(ctx *types.SystemContext) ([]string, error)
• func UnqualifiedSearchRegistriesWithOrigin(ctx *types.SystemContext) ([]string, string, error)
• type Endpoint
• type InvalidRegistries
  • func (e *InvalidRegistries) Error() string
• type PullSource
• type Registry
  • func FindRegistry(ctx *types.SystemContext, ref string) (*Registry, error)
  • func GetRegistries(ctx *types.SystemContext) ([]Registry, error)
  • func (r *Registry) PullSourcesFromReference(ref reference.Named) ([]PullSource, error)
• type V1RegistriesConf
  • func (config *V1RegistriesConf) ConvertToV2() (*V2RegistriesConf, error)
  • func (config *V1RegistriesConf) Nonempty() bool
• type V1TOMLConfig
• type V1TOMLregistries
• type V2RegistriesConf
  • func TryUpdatingCache(ctx *types.SystemContext) (*V2RegistriesConf, error)
  • func (config *V2RegistriesConf) Nonempty() bool

Functions

func AddShortNameAlias

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

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

Note that it’s the caller’s responsibility to pass only a repository (reference.IsNameOnly) as the short name.

func ConfigDirPath

func ConfigDirPath(ctx *types.SystemContext) string

ConfigDirPath returns the path to the directory for drop-in registry configuration files. Deprecated: This API implies configuration is read from directories, and that there is only one. Please use ConfigurationSourceDescription to obtain a string usable for error messages.

func ConfigPath

func ConfigPath(ctx *types.SystemContext) string

ConfigPath returns the path to the system-wide registry configuration file. Deprecated: This API implies configuration is read from files, and that there is only one. Please use ConfigurationSourceDescription to obtain a string usable for error messages.

func ConfigurationSourceDescription

func ConfigurationSourceDescription(ctx *types.SystemContext) string

ConfigurationSourceDescription returns a string containres paths of registries.conf and registries.conf.d

func GetShortNameMode

func GetShortNameMode(ctx *types.SystemContext) (types.ShortNameMode, error)

GetShortNameMode returns the configured types.ShortNameMode.

func InvalidateCache

func InvalidateCache()

InvalidateCache invalidates the registry cache. This function is meant to be used for long-running processes that need to reload potential changes made to the cached registry config files.

func RemoveShortNameAlias

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

RemoveShortNameAlias clears the 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.

Note that it’s the caller’s responsibility to pass only a repository (reference.IsNameOnly) as the short name.

func ResolveShortNameAlias

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

ResolveShortNameAlias performs an alias resolution of the specified name. The user-specific short-name-aliases.conf has precedence over aliases in the assembled registries.conf. It returns the possibly resolved alias or nil, a human-readable description of the config where the alias is specified, and an error. The origin of the config file is crucial for an improved user experience such that users are able to resolve potential pull errors. Almost all callers should use pkg/shortnames instead.

Note that it’s the caller’s responsibility to pass only a repository (reference.IsNameOnly) as the short name.

func UnqualifiedSearchRegistries

func UnqualifiedSearchRegistries(ctx *types.SystemContext) ([]string, error)

UnqualifiedSearchRegistries returns a list of host[:port] entries to try for unqualified image search, in the returned order)

func UnqualifiedSearchRegistriesWithOrigin

func UnqualifiedSearchRegistriesWithOrigin(ctx *types.SystemContext) ([]string, string, error)

UnqualifiedSearchRegistriesWithOrigin returns a list of host[:port] entries to try for unqualified image search, in the returned order. It also returns a human-readable description of where these entries are specified (e.g., a registries.conf file).

Types

type Endpoint

type Endpoint struct {
	// The endpoint's remote location.
	Location string `toml:"location,omitempty"`
	// If true, certs verification will be skipped and HTTP (non-TLS)
	// connections will be allowed.
	Insecure bool `toml:"insecure,omitempty"`
}

Endpoint describes a remote location of a registry.

type InvalidRegistries

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

InvalidRegistries represents an invalid registry configurations. An example is when "registry.com" is defined multiple times in the configuration but with conflicting security settings.

func (*InvalidRegistries) Error

func (e *InvalidRegistries) Error() string

Error returns the error string.

type PullSource

type PullSource struct {
	Endpoint  Endpoint
	Reference reference.Named
}

PullSource consists of an Endpoint and a Reference. Note that the reference is rewritten according to the registries prefix and the Endpoint's location.

type Registry

type Registry struct {
	// Prefix is used for matching images, and to translate one namespace to
	// another.  If `Prefix="example.com/bar"`, `location="example.com/foo/bar"`
	// and we pull from "example.com/bar/myimage:latest", the image will
	// effectively be pulled from "example.com/foo/bar/myimage:latest".
	// If no Prefix is specified, it defaults to the specified location.
	Prefix string `toml:"prefix"`
	// A registry is an Endpoint too
	Endpoint
	// The registry's mirrors.
	Mirrors []Endpoint `toml:"mirror,omitempty"`
	// If true, pulling from the registry will be blocked.
	Blocked bool `toml:"blocked,omitempty"`
	// If true, mirrors will only be used for digest pulls. Pulling images by
	// tag can potentially yield different images, depending on which endpoint
	// we pull from.  Forcing digest-pulls for mirrors avoids that issue.
	MirrorByDigestOnly bool `toml:"mirror-by-digest-only,omitempty"`
}

Registry represents a registry.

func FindRegistry

func FindRegistry(ctx *types.SystemContext, ref string) (*Registry, error)

FindRegistry returns the Registry with the longest prefix for ref, which is a registry, repository namespace repository or image reference (as formatted by reference.Domain(), reference.Named.Name() or reference.Reference.String() — note that this requires the name to start with an explicit hostname!). If no Registry prefixes the image, nil is returned.

func GetRegistries

func GetRegistries(ctx *types.SystemContext) ([]Registry, error)

GetRegistries loads and returns the registries specified in the config. Note the parsed content of registry config files is cached. For reloading, use `InvalidateCache` and re-call `GetRegistries`.

func (*Registry) PullSourcesFromReference

func (r *Registry) PullSourcesFromReference(ref reference.Named) ([]PullSource, error)

PullSourcesFromReference returns a slice of PullSource's based on the passed reference.

type V1RegistriesConf

type V1RegistriesConf struct {
	V1TOMLConfig `toml:"registries"`
}

V1RegistriesConf is the sysregistries v1 configuration format.

func (*V1RegistriesConf) ConvertToV2

func (config *V1RegistriesConf) ConvertToV2() (*V2RegistriesConf, error)

ConvertToV2 returns a v2 config corresponding to a v1 one.

func (*V1RegistriesConf) Nonempty

func (config *V1RegistriesConf) Nonempty() bool

Nonempty returns true if config contains at least one configuration entry.

type V1TOMLConfig

type V1TOMLConfig struct {
	Search   V1TOMLregistries `toml:"search"`
	Insecure V1TOMLregistries `toml:"insecure"`
	Block    V1TOMLregistries `toml:"block"`
}

V1TOMLConfig is for backwards compatibility to sysregistries v1

type V1TOMLregistries

type V1TOMLregistries struct {
	Registries []string `toml:"registries"`
}

V1TOMLregistries is for backwards compatibility to sysregistries v1

type V2RegistriesConf

type V2RegistriesConf struct {
	Registries []Registry `toml:"registry"`
	// An array of host[:port] (not prefix!) entries to use for resolving unqualified image references
	UnqualifiedSearchRegistries []string `toml:"unqualified-search-registries"`

	// ShortNameMode defines how short-name resolution should be handled by
	// _consumers_ of this package.  Depending on the mode, the user should
	// be prompted with a choice of using one of the unqualified-search
	// registries when referring to a short name.
	//
	// Valid modes are: * "prompt": prompt if stdout is a TTY, otherwise
	// use all unqualified-search registries * "enforcing": always prompt
	// and error if stdout is not a TTY * "disabled": do not prompt and
	// potentially use all unqualified-search registries
	ShortNameMode string `toml:"short-name-mode"`
	// contains filtered or unexported fields
}

V2RegistriesConf is the sysregistries v2 configuration format.

func TryUpdatingCache

func TryUpdatingCache(ctx *types.SystemContext) (*V2RegistriesConf, error)

TryUpdatingCache loads the configuration from the provided `SystemContext` without using the internal cache. On success, the loaded configuration will be added into the internal registry cache. It returns the resulting configuration; this is DEPRECATED and may not correctly reflect any future data handled by this package.

func (*V2RegistriesConf) Nonempty

func (config *V2RegistriesConf) Nonempty() bool

Nonempty returns true if config contains at least one configuration entry.