registry

Documentation

Overview

Package registry contains client primitives to interact with a remote Docker registry.

Index

• Constants
• Variables
• func CertsDir() string
• func ConvertToHostname(url string) string
• func GetAuthConfigKey(index *registry.IndexInfo) string
• func Headers(userAgent string, metaHeaders http.Header) []transport.RequestModifier
• func HostCertsDir(hostname string) string
• func NewStaticCredentialStore(auth *registry.AuthConfig) auth.CredentialStore
• func ParseSearchIndexInfo(reposName string) (*registry.IndexInfo, error)
• func PingV2Registry(endpoint *url.URL, transport http.RoundTripper) (challenge.Manager, error)
• func ReadCertsDirectory(tlsConfig *tls.Config, directory string) error
• func ResolveAuthConfig(authConfigs map[string]registry.AuthConfig, index *registry.IndexInfo) registry.AuthConfig
• func SetCertsDir(path string)
• func ValidateIndexName(val string) (string, error)
• func ValidateMirror(val string) (string, error)
• type APIEndpoint
• type APIVersion
  • func (av APIVersion) String() string
• type PingResponseError
  • func (err PingResponseError) Error() string
• type RepositoryInfo
  • func ParseRepositoryInfo(reposName reference.Named) (*RepositoryInfo, error)
• type Service
  • func NewService(options ServiceOptions) (*Service, error)
  • func (s *Service) Auth(ctx context.Context, authConfig *registry.AuthConfig, userAgent string) (status, token string, err error)
  • func (s *Service) IsInsecureRegistry(host string) bool
  • func (s *Service) LookupPullEndpoints(hostname string) (endpoints []APIEndpoint, err error)
  • func (s *Service) LookupPushEndpoints(hostname string) (endpoints []APIEndpoint, err error)
  • func (s *Service) ReplaceConfig(options ServiceOptions) (commit func(), err error)
  • func (s *Service) ResolveRepository(name reference.Named) (*RepositoryInfo, error)
  • func (s *Service) Search(ctx context.Context, searchFilters filters.Args, term string, limit int, ...) ([]registry.SearchResult, error)
  • func (s *Service) ServiceConfig() *registry.ServiceConfig
• type ServiceOptions

Constants

const (
	// DefaultNamespace is the default namespace
	DefaultNamespace = "docker.io"
	// DefaultRegistryHost is the hostname for the default (Docker Hub) registry
	// used for pushing and pulling images. This hostname is hard-coded to handle
	// the conversion from image references without registry name (e.g. "ubuntu",
	// or "ubuntu:latest"), as well as references using the "docker.io" domain
	// name, which is used as canonical reference for images on Docker Hub, but
	// does not match the domain-name of Docker Hub's registry.
	DefaultRegistryHost = "registry-1.docker.io"
	// IndexHostname is the index hostname, used for authentication and image search.
	IndexHostname = "index.docker.io"
	// IndexServer is used for user auth and image search
	IndexServer = "https://" + IndexHostname + "/v1/"
	// IndexName is the name of the index
	IndexName = "docker.io"
)

TODO(thaJeztah) both the "index.docker.io" and "registry-1.docker.io" domains are here for historic reasons and backward-compatibility. These domains are still supported by Docker Hub (and will continue to be supported), but there are new domains already in use, and plans to consolidate all legacy domains to new "canonical" domains. Once those domains are decided on, we should update these consts (but making sure to preserve compatibility with existing installs, clients, and user configuration).

const AuthClientID = "docker"

AuthClientID is used the ClientID used for the token server

Variables

var (
	// DefaultV2Registry is the URI of the default (Docker Hub) registry.
	DefaultV2Registry = &url.URL{
		Scheme: "https",
		Host:   DefaultRegistryHost,
	}
)

Functions

func CertsDir

func CertsDir() string

CertsDir is the directory where certificates are stored.

func ConvertToHostname

func ConvertToHostname(url string) string

ConvertToHostname normalizes a registry URL which has http|https prepended to just its hostname. It is used to match credentials, which may be either stored as hostname or as hostname including scheme (in legacy configuration files).

func GetAuthConfigKey

func GetAuthConfigKey(index *registry.IndexInfo) string

GetAuthConfigKey special-cases using the full index address of the official index as the AuthConfig key, and uses the (host)name[:port] for private indexes.

func Headers

func Headers(userAgent string, metaHeaders http.Header) []transport.RequestModifier

Headers returns request modifiers with a User-Agent and metaHeaders

func HostCertsDir

func HostCertsDir(hostname string) string

HostCertsDir returns the config directory for a specific host.

func NewStaticCredentialStore

func NewStaticCredentialStore(auth *registry.AuthConfig) auth.CredentialStore

NewStaticCredentialStore returns a credential store which always returns the same credential values.

func ParseSearchIndexInfo

func ParseSearchIndexInfo(reposName string) (*registry.IndexInfo, error)

ParseSearchIndexInfo will use repository name to get back an indexInfo.

TODO(thaJeztah) this function is only used by the CLI, and used to get information of the registry (to provide credentials if needed). We should move this function (or equivalent) to the CLI, as it's doing too much just for that.

func PingV2Registry

func PingV2Registry(endpoint *url.URL, transport http.RoundTripper) (challenge.Manager, error)

PingV2Registry attempts to ping a v2 registry and on success return a challenge manager for the supported authentication types. If a response is received but cannot be interpreted, a PingResponseError will be returned.

func ReadCertsDirectory

func ReadCertsDirectory(tlsConfig *tls.Config, directory string) error

ReadCertsDirectory reads the directory for TLS certificates including roots and certificate pairs and updates the provided TLS configuration.

func ResolveAuthConfig

func ResolveAuthConfig(authConfigs map[string]registry.AuthConfig, index *registry.IndexInfo) registry.AuthConfig

ResolveAuthConfig matches an auth configuration to a server address or a URL

func SetCertsDir

func SetCertsDir(path string)

SetCertsDir allows the default certs directory to be changed. This function is used at daemon startup to set the correct location when running in rootless mode.

func ValidateIndexName

func ValidateIndexName(val string) (string, error)

ValidateIndexName validates an index name. It is used by the daemon to validate the daemon configuration.

func ValidateMirror

func ValidateMirror(val string) (string, error)

ValidateMirror validates an HTTP(S) registry mirror. It is used by the daemon to validate the daemon configuration.

Types

type APIEndpoint

type APIEndpoint struct {
	Mirror                         bool
	URL                            *url.URL
	Version                        APIVersion // Deprecated: v1 registries are deprecated, and endpoints are always v2.
	AllowNondistributableArtifacts bool
	Official                       bool
	TrimHostname                   bool
	TLSConfig                      *tls.Config
}

APIEndpoint represents a remote API endpoint

type APIVersion

type APIVersion int

APIVersion is an integral representation of an API version (presently either 1 or 2)

Deprecated: v1 registries are deprecated, and endpoints are always v2.

const (
	APIVersion1 APIVersion = 1 // Deprecated: v1 registries are deprecated, and endpoints are always v2.
	APIVersion2 APIVersion = 2 // Deprecated: v1 registries are deprecated, and endpoints are always v2.
)

API Version identifiers.

func (APIVersion) String

func (av APIVersion) String() string

type PingResponseError

type PingResponseError struct {
	Err error
}

PingResponseError is used when the response from a ping was received but invalid.

func (PingResponseError) Error

func (err PingResponseError) Error() string

type RepositoryInfo

type RepositoryInfo struct {
	Name reference.Named
	// Index points to registry information
	Index *registry.IndexInfo
	// Official indicates whether the repository is considered official.
	// If the registry is official, and the normalized name does not
	// contain a '/' (e.g. "foo"), then it is considered an official repo.
	Official bool
	// Class represents the class of the repository, such as "plugin"
	// or "image".
	Class string
}

RepositoryInfo describes a repository

func ParseRepositoryInfo

func ParseRepositoryInfo(reposName reference.Named) (*RepositoryInfo, error)

ParseRepositoryInfo performs the breakdown of a repository name into a RepositoryInfo, but lacks registry configuration.

It is used by the Docker cli to interact with registry-related endpoints.

type Service

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

Service is a registry service. It tracks configuration data such as a list of mirrors.

func NewService

func NewService(options ServiceOptions) (*Service, error)

NewService returns a new instance of Service ready to be installed into an engine.

func (*Service) Auth

func (s *Service) Auth(ctx context.Context, authConfig *registry.AuthConfig, userAgent string) (status, token string, err error)

Auth contacts the public registry with the provided credentials, and returns OK if authentication was successful. It can be used to verify the validity of a client's credentials.

func (*Service) IsInsecureRegistry

func (s *Service) IsInsecureRegistry(host string) bool

IsInsecureRegistry returns true if the registry at given host is configured as insecure registry.

func (*Service) LookupPullEndpoints

func (s *Service) LookupPullEndpoints(hostname string) (endpoints []APIEndpoint, err error)

LookupPullEndpoints creates a list of v2 endpoints to try to pull from, in order of preference. It gives preference to mirrors over the actual registry, and HTTPS over plain HTTP.

func (*Service) LookupPushEndpoints

func (s *Service) LookupPushEndpoints(hostname string) (endpoints []APIEndpoint, err error)

LookupPushEndpoints creates a list of v2 endpoints to try to push to, in order of preference. It gives preference to HTTPS over plain HTTP. Mirrors are not included.

func (*Service) ReplaceConfig

func (s *Service) ReplaceConfig(options ServiceOptions) (commit func(), err error)

ReplaceConfig prepares a transaction which will atomically replace the registry service's configuration when the returned commit function is called.

func (*Service) ResolveRepository

func (s *Service) ResolveRepository(name reference.Named) (*RepositoryInfo, error)

ResolveRepository splits a repository name into its components and configuration of the associated registry.

func (*Service) Search

func (s *Service) Search(ctx context.Context, searchFilters filters.Args, term string, limit int, authConfig *registry.AuthConfig, headers map[string][]string) ([]registry.SearchResult, error)

Search queries the public registry for repositories matching the specified search term and filters.

func (*Service) ServiceConfig

func (s *Service) ServiceConfig() *registry.ServiceConfig

ServiceConfig returns a copy of the public registry service's configuration.

type ServiceOptions

type ServiceOptions struct {
	AllowNondistributableArtifacts []string `json:"allow-nondistributable-artifacts,omitempty"`
	Mirrors                        []string `json:"registry-mirrors,omitempty"`
	InsecureRegistries             []string `json:"insecure-registries,omitempty"`
}

ServiceOptions holds command line options.