registry

package
v1.9.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2015 License: Apache-2.0 Imports: 42 Imported by: 2,819

Documentation

Overview

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

Index

Constants

View Source 
const (
	// DefaultNamespace is the default namespace
	DefaultNamespace = "docker.io"
	// DefaultRegistryVersionHeader is the name of the default HTTP header
	// that carries Registry version info
	DefaultRegistryVersionHeader = "Docker-Distribution-Api-Version"

	// IndexServer is the v1 registry server used for user auth + account creation
	IndexServer = DefaultV1Registry + "/v1/"
	// IndexName is the name of the index
	IndexName = "docker.io"

	// NotaryServer is the endpoint serving the Notary trust server
	NotaryServer = "https://notary.docker.io"
)
View Source 
const (
	// DefaultV1Registry is the URI of the default v1 registry
	DefaultV1Registry = "https://index.docker.io"

	// DefaultV2Registry is the URI of the default v2 registry
	DefaultV2Registry = "https://registry-1.docker.io"

	// CertsDir is the directory where certificates are stored
	CertsDir = "/etc/docker/certs.d"
)
View Source 
const (
	APIVersionUnknown = iota
	APIVersion1
	APIVersion2
)

API Version identifiers.

Variables

View Source 
var (
	// ErrInvalidRepositoryName is an error returned if the repository name did
	// not have the correct form
	ErrInvalidRepositoryName = errors.New("Invalid repository name (ex: \"registry.domain.tld/myrepos\")")

	// V2Only controls access to legacy registries.  If it is set to true via the
	// command line flag the daemon will not attempt to contact v1 legacy registries
	V2Only = false
)
View Source 
var (
	// ErrAlreadyExists is an error returned if an image being pushed
	// already exists on the remote side
	ErrAlreadyExists = errors.New("Image already exists")
)
View Source 
var (
	// ErrRepoNotFound is returned if the repository didn't exist on the
	// remote side
	ErrRepoNotFound = errors.New("Repository not found")
)

Functions

func AuthTransport added in v1.7.0 

func AuthTransport(base http.RoundTripper, authConfig *cliconfig.AuthConfig, alwaysSetBasicAuth bool) http.RoundTripper

AuthTransport handles the auth layer when communicating with a v1 registry (private or official)

For private v1 registries, set alwaysSetBasicAuth to true.

For the official v1 registry, if there isn't already an Authorization header in the request, but there is an X-Docker-Token header set to true, then Basic Auth will be used to set the Authorization header. After sending the request with the provided base http.RoundTripper, if an X-Docker-Token header, representing a token, is present in the response, then it gets cached and sent in the Authorization header of all subsequent requests.

If the server sends a token without the client having requested it, it is ignored.

This RoundTripper also has a CancelRequest method important for correct timeout handling.

func ContinueOnError added in v1.8.0 

func ContinueOnError(err error) bool

ContinueOnError returns true if we should fallback to the next endpoint as a result of this error.

func DockerHeaders added in v1.7.0 

func DockerHeaders(metaHeaders http.Header) []transport.RequestModifier

DockerHeaders returns request modifiers that ensure requests have the User-Agent header set to dockerUserAgent and that metaHeaders are added.

func HTTPClient added in v1.7.0 

func HTTPClient(transport http.RoundTripper) *http.Client

HTTPClient returns a HTTP client structure which uses the given transport and contains the necessary headers for redirected requests

func Login added in v0.10.0 

func Login(authConfig *cliconfig.AuthConfig, registryEndpoint *Endpoint) (string, error)

Login tries to register/login to the registry server.

func NewTransport added in v1.7.0 

func NewTransport(tlsConfig *tls.Config) *http.Transport

NewTransport returns a new HTTP transport. If tlsConfig is nil, it uses the default TLS configuration.

func NormalizeLocalName added in v1.5.0 

func NormalizeLocalName(name string) string

NormalizeLocalName transforms a repository name into a normalize LocalName Passes through the name without transformation on error (image id, etc)

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(config *cliconfig.ConfigFile, index *IndexInfo) cliconfig.AuthConfig

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

func ValidateIndexName added in v1.5.0 

func ValidateIndexName(val string) (string, error)

ValidateIndexName validates an index name.

func ValidateMirror added in v1.5.0 

func ValidateMirror(val string) (string, error)

ValidateMirror validates an HTTP(S) registry mirror

func ValidateRepositoryName added in v1.5.0 

func ValidateRepositoryName(reposName string) error

ValidateRepositoryName validates a repository name

Types

type APIEndpoint added in v1.8.0 

type APIEndpoint struct {
	Mirror        bool
	URL           string
	Version       APIVersion
	Official      bool
	TrimHostname  bool
	TLSConfig     *tls.Config
	VersionHeader string
	Versions      []auth.APIVersion
}

APIEndpoint represents a remote API endpoint

func (APIEndpoint) ToV1Endpoint added in v1.8.0 

func (e APIEndpoint) ToV1Endpoint(metaHeaders http.Header) (*Endpoint, error)

ToV1Endpoint returns a V1 API endpoint based on the APIEndpoint

type APIVersion added in v1.3.0 

type APIVersion int

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

func (APIVersion) String added in v1.3.0 

func (av APIVersion) String() string

type AuthorizationChallenge added in v1.5.0 

type AuthorizationChallenge struct {
	Scheme     string
	Parameters map[string]string
}

AuthorizationChallenge carries information from a WWW-Authenticate response header.

type Endpoint added in v1.3.0 

type Endpoint struct {
	URL            *url.URL
	Version        APIVersion
	IsSecure       bool
	AuthChallenges []*AuthorizationChallenge
	URLBuilder     *v2.URLBuilder
	// contains filtered or unexported fields
}

Endpoint stores basic information about a registry endpoint.

func NewEndpoint added in v1.3.0 

func NewEndpoint(index *IndexInfo, metaHeaders http.Header, v APIVersion) (*Endpoint, error)

NewEndpoint parses the given address to return a registry endpoint. v can be used to specify a specific endpoint version

func (*Endpoint) Path added in v1.5.0 

func (e *Endpoint) Path(path string) string

Path returns a formatted string for the URL of this endpoint with the given path appended.

func (*Endpoint) Ping added in v1.3.0 

func (e *Endpoint) Ping() (PingResult, error)

Ping pings the remote endpoint with v2 and v1 pings to determine the API version. It returns a PingResult containing the discovered version. The PingResult also indicates whether the registry is standalone or not.

func (*Endpoint) String added in v1.3.0 

func (e *Endpoint) String() string

Get the formated URL for the root of this registry Endpoint

func (*Endpoint) VersionString added in v1.3.0 

func (e *Endpoint) VersionString(version APIVersion) string

VersionString returns a formatted string of this endpoint address using the given API Version.

type ErrNoSupport added in v1.8.0 

type ErrNoSupport struct{ Err error }

ErrNoSupport is an error type used for errors indicating that an operation is not supported. It encapsulates a more specific error.

func (ErrNoSupport) Error added in v1.8.0 

func (e ErrNoSupport) Error() string

type ImgData 

type ImgData struct {
	// ID is an opaque string that identifies the image
	ID              string `json:"id"`
	Checksum        string `json:"checksum,omitempty"`
	ChecksumPayload string `json:"-"`
	Tag             string `json:",omitempty"`
}

ImgData is used to transfer image checksums to and from the registry

type IndexInfo added in v1.5.0 

type IndexInfo struct {
	// Name is the name of the registry, such as "docker.io"
	Name string
	// Mirrors is a list of mirrors, expressed as URIs
	Mirrors []string
	// Secure is set to false if the registry is part of the list of
	// insecure registries. Insecure registries accept HTTP and/or accept
	// HTTPS with certificates from unknown CAs.
	Secure bool
	// Official indicates whether this is an official registry
	Official bool
}

IndexInfo contains information about a registry

RepositoryInfo Examples: 

{
  "Index" : {
    "Name" : "docker.io",
    "Mirrors" : ["https://registry-2.docker.io/v1/", "https://registry-3.docker.io/v1/"],
    "Secure" : true,
    "Official" : true,
  },
  "RemoteName" : "library/debian",
  "LocalName" : "debian",
  "CanonicalName" : "docker.io/debian"
  "Official" : true,
}

{
  "Index" : {
    "Name" : "127.0.0.1:5000",
    "Mirrors" : [],
    "Secure" : false,
    "Official" : false,
  },
  "RemoteName" : "user/repo",
  "LocalName" : "127.0.0.1:5000/user/repo",
  "CanonicalName" : "127.0.0.1:5000/user/repo",
  "Official" : false,
}

func ParseIndexInfo added in v1.9.0 

func ParseIndexInfo(reposName string) (*IndexInfo, error)

ParseIndexInfo will use repository name to get back an indexInfo.

func (*IndexInfo) GetAuthConfigKey added in v1.5.0 

func (index *IndexInfo) GetAuthConfigKey() 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.

type Options added in v1.5.0 

type Options struct {
	Mirrors            opts.ListOpts
	InsecureRegistries opts.ListOpts
}

Options holds command line options.

func (*Options) InstallFlags added in v1.5.0 

func (options *Options) InstallFlags(cmd *flag.FlagSet, usageFn func(string) string)

InstallFlags adds command-line options to the top-level flag parser for the current process.

type PingResult added in v1.8.0 

type PingResult struct {
	// Version is the registry version supplied by the registry in a HTTP
	// header
	Version string `json:"version"`
	// Standalone is set to true if the registry indicates it is a
	// standalone registry in the X-Docker-Registry-Standalone
	// header
	Standalone bool `json:"standalone"`
}

PingResult contains the information returned when pinging a registry. It indicates the registry's version and whether the registry claims to be a standalone registry.

type Reference added in v1.8.0 

type Reference interface {
	// HasDigest returns whether the reference has a verifiable
	// content addressable reference which may be considered secure.
	HasDigest() bool

	// ImageName returns an image name for the given repository
	ImageName(string) string

	// Returns a string representation of the reference
	String() string
}

Reference represents a tag or digest within a repository

func DigestReference added in v1.8.0 

func DigestReference(dgst digest.Digest) Reference

DigestReference creates a digest reference using a digest

func ParseReference added in v1.8.0 

func ParseReference(ref string) Reference

ParseReference parses a reference into either a digest or tag reference

type RepositoryData 

type RepositoryData struct {
	// ImgList is a list of images in the repository
	ImgList map[string]*ImgData
	// Endpoints is a list of endpoints returned in X-Docker-Endpoints
	Endpoints []string
	// Tokens is currently unused (remove it?)
	Tokens []string
}

RepositoryData tracks the image list, list of endpoints, and list of tokens for a repository

type RepositoryInfo added in v1.5.0 

type RepositoryInfo struct {
	// Index points to registry information
	Index *IndexInfo
	// RemoteName is the remote name of the repository, such as
	// "library/ubuntu-12.04-base"
	RemoteName string
	// LocalName is the local name of the repository, such as
	// "ubuntu-12.04-base"
	LocalName string
	// CanonicalName is the canonical name of the repository, such as
	// "docker.io/library/ubuntu-12.04-base"
	CanonicalName string
	// 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
}

RepositoryInfo describes a repository

func ParseRepositoryInfo added in v1.5.0 

func ParseRepositoryInfo(reposName string) (*RepositoryInfo, error)

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

func (*RepositoryInfo) GetSearchTerm added in v1.5.0 

func (repoInfo *RepositoryInfo) GetSearchTerm() string

GetSearchTerm special-cases using local name for official index, and remote name for private indexes.

type SearchResult added in v0.6.6 

type SearchResult struct {
	// StarCount indicates the number of stars this repository has
	StarCount int `json:"star_count"`
	// IsOfficial indicates whether the result is an official repository or not
	IsOfficial bool `json:"is_official"`
	// Name is the name of the repository
	Name string `json:"name"`
	// IsOfficial indicates whether the result is trusted
	IsTrusted bool `json:"is_trusted"`
	// IsAutomated indicates whether the result is automated
	IsAutomated bool `json:"is_automated"`
	// Description is a textual description of the repository
	Description string `json:"description"`
}

SearchResult describes a search result returned from a registry

type SearchResults 

type SearchResults struct {
	// Query contains the query string that generated the search results
	Query string `json:"query"`
	// NumResults indicates the number of results the query returned
	NumResults int `json:"num_results"`
	// Results is a slice containing the acutal results for the search
	Results []SearchResult `json:"results"`
}

SearchResults lists a collection search results returned from a registry

type Service added in v0.11.0 

type Service struct {
	Config *ServiceConfig
}

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 *Options) *Service

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(authConfig *cliconfig.AuthConfig) (string, 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) LookupPullEndpoints added in v1.8.0 

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

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

func (*Service) LookupPushEndpoints added in v1.8.0 

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

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

func (*Service) ResolveIndex added in v1.5.0 

func (s *Service) ResolveIndex(name string) (*IndexInfo, error)

ResolveIndex takes indexName and returns index info

func (*Service) ResolveRepository added in v1.5.0 

func (s *Service) ResolveRepository(name string) (*RepositoryInfo, error)

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

func (*Service) ResolveRepositoryBySearch added in v1.9.0 

func (s *Service) ResolveRepositoryBySearch(name string) (*RepositoryInfo, error)

ResolveRepositoryBySearch 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(term string, authConfig *cliconfig.AuthConfig, headers map[string][]string) (*SearchResults, error)

Search queries the public registry for images matching the specified search terms, and returns the results.

func (*Service) TLSConfig added in v1.8.0 

func (s *Service) TLSConfig(hostname string) (*tls.Config, error)

TLSConfig constructs a client TLS configuration based on server defaults

type ServiceConfig added in v1.5.0 

type ServiceConfig struct {
	InsecureRegistryCIDRs []*netIPNet           `json:"InsecureRegistryCIDRs"`
	IndexConfigs          map[string]*IndexInfo `json:"IndexConfigs"`
	Mirrors               []string
}

ServiceConfig stores daemon registry services configuration.

func NewServiceConfig added in v1.5.0 

func NewServiceConfig(options *Options) *ServiceConfig

NewServiceConfig returns a new instance of ServiceConfig

func (*ServiceConfig) NewIndexInfo added in v1.5.0 

func (config *ServiceConfig) NewIndexInfo(indexName string) (*IndexInfo, error)

NewIndexInfo returns IndexInfo configuration from indexName

func (*ServiceConfig) NewRepositoryInfo added in v1.5.0 

func (config *ServiceConfig) NewRepositoryInfo(reposName string, bySearch bool) (*RepositoryInfo, error)

NewRepositoryInfo validates and breaks down a repository name into a RepositoryInfo

type Session added in v1.2.0 

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

A Session is used to communicate with a V1 registry

func NewSession added in v1.2.0 

func NewSession(client *http.Client, authConfig *cliconfig.AuthConfig, endpoint *Endpoint) (r *Session, err error)

NewSession creates a new session TODO(tiborvass): remove authConfig param once registry client v2 is vendored

func (*Session) GetAuthConfig added in v1.2.0 

func (r *Session) GetAuthConfig(withPasswd bool) *cliconfig.AuthConfig

GetAuthConfig returns the authentication settings for a session TODO(tiborvass): remove this once registry client v2 is vendored

func (*Session) GetRemoteHistory added in v1.2.0 

func (r *Session) GetRemoteHistory(imgID, registry string) ([]string, error)

GetRemoteHistory retrieves the history of a given image from the registry. It returns a list of the parent's JSON files (including the requested image).

func (*Session) GetRemoteImageJSON added in v1.2.0 

func (r *Session) GetRemoteImageJSON(imgID, registry string) ([]byte, int64, error)

GetRemoteImageJSON retrieves an image's JSON metadata from the registry.

func (*Session) GetRemoteImageLayer added in v1.2.0 

func (r *Session) GetRemoteImageLayer(imgID, registry string, imgSize int64) (io.ReadCloser, error)

GetRemoteImageLayer retrieves an image layer from the registry

func (*Session) GetRemoteTag added in v1.8.0 

func (r *Session) GetRemoteTag(registries []string, repository string, askedTag string) (string, error)

GetRemoteTag retrieves the tag named in the askedTag argument from the given repository. It queries each of the registries supplied in the registries argument, and returns data from the first one that answers the query successfully.

func (*Session) GetRemoteTags added in v1.2.0 

func (r *Session) GetRemoteTags(registries []string, repository string) (map[string]string, error)

GetRemoteTags retrieves all tags from the given repository. It queries each of the registries supplied in the registries argument, and returns data from the first one that answers the query successfully. It returns a map with tag names as the keys and image IDs as the values.

func (*Session) GetRepositoryData added in v1.2.0 

func (r *Session) GetRepositoryData(remote string) (*RepositoryData, error)

GetRepositoryData returns lists of images and endpoints for the repository

func (*Session) ID added in v1.8.0 

func (r *Session) ID() string

ID returns this registry session's ID.

func (*Session) LookupRemoteImage added in v1.2.0 

func (r *Session) LookupRemoteImage(imgID, registry string) error

LookupRemoteImage checks if an image exists in the registry

func (*Session) PushImageChecksumRegistry added in v1.2.0 

func (r *Session) PushImageChecksumRegistry(imgData *ImgData, registry string) error

PushImageChecksumRegistry uploads checksums for an image

func (*Session) PushImageJSONIndex added in v1.2.0 

func (r *Session) PushImageJSONIndex(remote string, imgList []*ImgData, validate bool, regs []string) (*RepositoryData, error)

PushImageJSONIndex uploads an image list to the repository

func (*Session) PushImageJSONRegistry added in v1.2.0 

func (r *Session) PushImageJSONRegistry(imgData *ImgData, jsonRaw []byte, registry string) error

PushImageJSONRegistry pushes JSON metadata for a local image to the registry

func (*Session) PushImageLayerRegistry added in v1.2.0 

func (r *Session) PushImageLayerRegistry(imgID string, layer io.Reader, registry string, jsonRaw []byte) (checksum string, checksumPayload string, err error)

PushImageLayerRegistry sends the checksum of an image layer to the registry

func (*Session) PushRegistryTag added in v1.2.0 

func (r *Session) PushRegistryTag(remote, revision, tag, registry string) error

PushRegistryTag pushes a tag on the registry. Remote has the format '<user>/<repo>

func (*Session) SearchRepositories added in v1.2.0 

func (r *Session) SearchRepositories(term string) (*SearchResults, error)

SearchRepositories performs a search against the remote repository

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.