v27.0.3+incompatible Latest Latest

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

Go to latest
Published: Jun 28, 2024 License: Apache-2.0 Imports: 28 Imported by: 2,726



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



View Source
const (
	// DefaultNamespace is the default namespace
	DefaultNamespace = ""
	// 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 "" 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 = ""
	// IndexHostname is the index hostname, used for authentication and image search.
	IndexHostname = ""
	// IndexServer is used for user auth and image search
	IndexServer = "https://" + IndexHostname + "/v1/"
	// IndexName is the name of the index
	IndexName = ""

TODO(thaJeztah) both the "" and "" 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).

View Source
const AuthClientID = "docker"

AuthClientID is used the ClientID used for the token server


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


func CertsDir added in v1.8.0

func CertsDir() string

CertsDir is the directory where certificates are stored.

func ConvertToHostname added in v1.13.0

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 added in v1.10.0

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 added in v1.12.0

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

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

func ParseSearchIndexInfo added in v1.10.0

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 added in v1.11.0

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 added in v1.8.0

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 added in v1.7.0

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 added in v1.5.0

func ValidateIndexName(val string) (string, error)

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

func ValidateMirror added in v1.5.0

func ValidateMirror(val string) (string, error)

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


type APIEndpoint added in v1.8.0

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 deprecated added in v1.3.0

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 added in v1.3.0

func (av APIVersion) String() string

type PingResponseError added in v1.11.0

type PingResponseError struct {
	Err error

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

func (PingResponseError) Error added in v1.11.0

func (err PingResponseError) Error() string

type RepositoryInfo added in v1.5.0

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 added in v1.5.0

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 added in v0.11.0

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 added in v0.11.0

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

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

func (*Service) Auth added in v0.11.0

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 added in v1.8.0

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 added in v1.8.0

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 added in v1.5.0

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 added in v0.11.0

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 added in v1.11.0

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

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

type ServiceOptions added in v1.11.0

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.


Path Synopsis

Jump to

Keyboard shortcuts

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