README
¶
name
Documentation
¶
Overview ¶
Package name defines structured types for representing image references.
What's in a name? For image references, not nearly enough!
Image references look a lot like URLs, but they differ in that they don't contain the scheme (http or https), they can end with a :tag or a @digest (the latter being validated), and they perform defaulting for missing components.
Since image references don't contain the scheme, we do our best to infer if we use http or https from the given hostname. We allow http fallback for any host that looks like localhost (localhost, 127.0.0.1, ::1), ends in ".local", or is in the "private" address space per RFC 1918. For everything else, we assume https only. To override this heuristic, use the Insecure option.
Image references with a digest signal to us that we should verify the content of the image matches the digest. E.g. when pulling a Digest reference, we'll calculate the sha256 of the manifest returned by the registry and error out if it doesn't match what we asked for.
For defaulting, we interpret "ubuntu" as "index.docker.io/library/ubuntu:latest" because we add the missing repo "library", the missing registry "index.docker.io", and the missing tag "latest". To disable this defaulting, use the StrictValidation option. This is useful e.g. to only allow image references that explicitly set a tag or digest, so that you don't accidentally pull "latest".
Index ¶
Constants ¶
const ( // DefaultRegistry is the registry name that will be used if no registry // provided and the default is not overridden. DefaultRegistry = "index.docker.io" // DefaultTag is the tag name that will be used if no tag provided and the // default is not overridden. DefaultTag = "latest" )
Variables ¶
This section is empty.
Functions ¶
func Insecure ¶
func Insecure(opts *options)
Insecure is an Option that allows image references to be fetched without TLS.
func IsErrBadName
deprecated
func StrictValidation ¶
func StrictValidation(opts *options)
StrictValidation is an Option that requires image references to be fully specified; i.e. no defaulting for registry (dockerhub), repo (library), or tag (latest).
func WeakValidation ¶
func WeakValidation(opts *options)
WeakValidation is an Option that sets defaults when parsing names, see StrictValidation.
Types ¶
type Digest ¶
type Digest struct {
Repository
// contains filtered or unexported fields
}
Digest stores a digest name in a structured form.
type ErrBadName ¶
type ErrBadName struct {
// contains filtered or unexported fields
}
ErrBadName is an error for when a bad docker name is supplied.
func (*ErrBadName) Error ¶
func (e *ErrBadName) Error() string
type Option ¶
type Option func(*options)
Option is a functional option for name parsing.
func WithDefaultRegistry ¶ added in v0.2.0
WithDefaultRegistry sets the default registry that will be used if one is not provided.
func WithDefaultTag ¶ added in v0.2.0
WithDefaultTag sets the default tag that will be used if one is not provided.
type OptionFn ¶ added in v0.2.0
type OptionFn func() Option
OptionFn is a function that returns an option.
type Reference ¶
type Reference interface {
fmt.Stringer
// Context accesses the Repository context of the reference.
Context() Repository
// Identifier accesses the type-specific portion of the reference.
Identifier() string
// Name is the fully-qualified reference name.
Name() string
// Scope is the scope needed to access this reference.
Scope(string) string
}
Reference defines the interface that consumers use when they can take either a tag or a digest.
func MustParseReference ¶ added in v0.5.0
MustParseReference behaves like ParseReference, but panics instead of returning an error. It's intended for use in tests, or when a value is expected to be valid at code authoring time.
To discourage its use in scenarios where the value is not known at code authoring time, it must be passed a string constant:
const str = "valid/string"
MustParseReference(str)
MustParseReference("another/valid/string")
MustParseReference(str + "/and/more")
These will not compile:
var str = "valid/string"
MustParseReference(str)
MustParseReference(strings.Join([]string{"valid", "string"}, "/"))
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores a docker registry name in a structured form.
func NewInsecureRegistry
deprecated
func NewRegistry ¶
NewRegistry returns a Registry based on the given name. Strict validation requires explicit, valid RFC 3986 URI authorities to be given.
func (Registry) RegistryStr ¶
RegistryStr returns the registry component of the Registry.
func (Registry) Scheme ¶
Scheme returns https scheme for all the endpoints except localhost or when explicitly defined.
type Repository ¶
type Repository struct {
Registry
// contains filtered or unexported fields
}
Repository stores a docker repository name in a structured form.
func NewRepository ¶
func NewRepository(name string, opts ...Option) (Repository, error)
NewRepository returns a new Repository representing the given name, according to the given strictness.
func (Repository) Digest ¶
func (r Repository) Digest(identifier string) Digest
Digest returns a Digest in this Repository.
func (Repository) Name ¶
func (r Repository) Name() string
Name returns the name from which the Repository was derived.
func (Repository) RepositoryStr ¶
func (r Repository) RepositoryStr() string
RepositoryStr returns the repository component of the Repository.
func (Repository) Scope ¶
func (r Repository) Scope(action string) string
Scope returns the scope required to perform the given action on the registry. TODO(jonjohnsonjr): consider moving scopes to a separate package.
func (Repository) String ¶
func (r Repository) String() string
func (Repository) Tag ¶
func (r Repository) Tag(identifier string) Tag
Tag returns a Tag in this Repository.
type Tag ¶
type Tag struct {
Repository
// contains filtered or unexported fields
}
Tag stores a docker tag name in a structured form.
func NewTag ¶
NewTag returns a new Tag representing the given name, according to the given strictness.
Source Files