distribution

package
v1.2.0-rc1 Latest Latest
Warning

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

Go to latest
Published: Apr 21, 2016 License: Apache-2.0, Apache-2.0 Imports: 9 Imported by: 0

README

Distribution

The Docker toolset to pack, ship, store, and deliver content.

This repository's main product is the Docker Registry 2.0 implementation for storing and distributing Docker images. It supersedes the docker/docker-registry project with a new API design, focused around security and performance.

Circle CI GoDoc

This repository contains the following components:

Component Description
registry An implementation of the Docker Registry HTTP API V2 for use with docker 1.6+.
libraries A rich set of libraries for interacting with,distribution components. Please see godoc for details. Note: These libraries are unstable.
specifications Distribution related specifications are available in docs/spec
documentation Docker's full documentation set is available at docs.docker.com. This repository contains the subset related just to the registry.
How does this integrate with Docker engine?

This project should provide an implementation to a V2 API for use in the Docker core project. The API should be embeddable and simplify the process of securely pulling and pushing content from docker daemons.

What are the long term goals of the Distribution project?

The Distribution project has the further long term goal of providing a secure tool chain for distributing content. The specifications, APIs and tools should be as useful with Docker as they are without.

Our goal is to design a professional grade and extensible content distribution system that allow users to:

  • Enjoy an efficient, secured and reliable way to store, manage, package and exchange content
  • Hack/roll their own on top of healthy open-source components
  • Implement their own home made solution through good specs, and solid extensions mechanism.

More about Registry 2.0

The new registry implementation provides the following benefits:

  • faster push and pull
  • new, more efficient implementation
  • simplified deployment
  • pluggable storage backend
  • webhook notifications

For information on upcoming functionality, please see ROADMAP.md.

Who needs to deploy a registry?

By default, Docker users pull images from Docker's public registry instance. Installing Docker gives users this ability. Users can also push images to a repository on Docker's public registry, if they have a Docker Hub account.

For some users and even companies, this default behavior is sufficient. For others, it is not.

For example, users with their own software products may want to maintain a registry for private, company images. Also, you may wish to deploy your own image repository for images used to test or in continuous integration. For these use cases and others, deploying your own registry instance may be the better choice.

Migration to Registry 2.0

For those who have previously deployed their own registry based on the Registry 1.0 implementation and wish to deploy a Registry 2.0 while retaining images, data migration is required. A tool to assist with migration efforts has been created. For more information see [docker/migrator] (https://github.com/docker/migrator).

Contribute

Please see CONTRIBUTING.md for details on how to contribute issues, fixes, and patches to this project. If you are contributing code, see the instructions for building a development environment.

Support

If any issues are encountered while using the Distribution project, several avenues are available for support:

IRC #docker-distribution on FreeNode
Issue Tracker github.com/docker/distribution/issues
Google Groups https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
Mailing List docker@dockerproject.org

License

This project is distributed under Apache License, Version 2.0.

Documentation

Overview

Package distribution will define the interfaces for the components of docker distribution. The goal is to allow users to reliably package, ship and store content related to docker images.

This is currently a work in progress. More details are available in the README.md.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrBlobExists returned when blob already exists
	ErrBlobExists = errors.New("blob exists")

	// ErrBlobDigestUnsupported when blob digest is an unsupported version.
	ErrBlobDigestUnsupported = errors.New("unsupported blob digest")

	// ErrBlobUnknown when blob is not found.
	ErrBlobUnknown = errors.New("unknown blob")

	// ErrBlobUploadUnknown returned when upload is not found.
	ErrBlobUploadUnknown = errors.New("blob upload unknown")

	// ErrBlobInvalidLength returned when the blob has an expected length on
	// commit, meaning mismatched with the descriptor or an invalid value.
	ErrBlobInvalidLength = errors.New("blob invalid length")
)
View Source
var ErrAccessDenied = errors.New("access denied")

ErrAccessDenied is returned when an access to a requested resource is denied.

View Source
var ErrManifestNotModified = errors.New("manifest not modified")

ErrManifestNotModified is returned when a conditional manifest GetByTag returns nil due to the client indicating it has the latest version

View Source
var ErrUnsupported = errors.New("operation unsupported")

ErrUnsupported is returned when an unimplemented or unsupported action is performed

View Source
var GlobalScope = Scope(fullScope{})

GlobalScope represents the full namespace scope which contains all other scopes.

Functions

This section is empty.

Types

type BlobDeleter added in v1.1.1

type BlobDeleter interface {
	Delete(ctx context.Context, dgst digest.Digest) error
}

BlobDeleter enables deleting blobs from storage.

type BlobDescriptorService added in v1.1.1

type BlobDescriptorService interface {
	BlobStatter

	// SetDescriptor assigns the descriptor to the digest. The provided digest and
	// the digest in the descriptor must map to identical content but they may
	// differ on their algorithm. The descriptor must have the canonical
	// digest of the content and the digest algorithm must match the
	// annotators canonical algorithm.
	//
	// Such a facility can be used to map blobs between digest domains, with
	// the restriction that the algorithm of the descriptor must match the
	// canonical algorithm (ie sha256) of the annotator.
	SetDescriptor(ctx context.Context, dgst digest.Digest, desc Descriptor) error

	// Clear enables descriptors to be unlinked
	Clear(ctx context.Context, dgst digest.Digest) error
}

BlobDescriptorService manages metadata about a blob by digest. Most implementations will not expose such an interface explicitly. Such mappings should be maintained by interacting with the BlobIngester. Hence, this is left off of BlobService and BlobStore.

type BlobEnumerator added in v1.1.1

type BlobEnumerator interface {
	// Enumerate calls ingester callback for each digest found in a blob store
	// until the callback returns an error or the blob store is processed.
	// io.EOF will be returned if all the digests are handled.
	Enumerate(ctx context.Context, ingester func(digest.Digest) error) error
}

BlobEnumerator allows to list blobs in storage.

type BlobIngester added in v1.1.1

type BlobIngester interface {
	// Put inserts the content p into the blob service, returning a descriptor
	// or an error.
	Put(ctx context.Context, mediaType string, p []byte) (Descriptor, error)

	// Create allocates a new blob writer to add a blob to this service. The
	// returned handle can be written to and later resumed using an opaque
	// identifier. With this approach, one can Close and Resume a BlobWriter
	// multiple times until the BlobWriter is committed or cancelled.
	Create(ctx context.Context) (BlobWriter, error)

	// Resume attempts to resume a write to a blob, identified by an id.
	Resume(ctx context.Context, id string) (BlobWriter, error)
}

BlobIngester ingests blob data.

type BlobProvider added in v1.1.1

type BlobProvider interface {
	// Get returns the entire blob identified by digest along with the descriptor.
	Get(ctx context.Context, dgst digest.Digest) ([]byte, error)

	// Open provides a ReadSeekCloser to the blob identified by the provided
	// descriptor. If the blob is not known to the service, an error will be
	// returned.
	Open(ctx context.Context, dgst digest.Digest) (ReadSeekCloser, error)
}

BlobProvider describes operations for getting blob data.

type BlobServer added in v1.1.1

type BlobServer interface {
	// ServeBlob attempts to serve the blob, identifed by dgst, via http. The
	// service may decide to redirect the client elsewhere or serve the data
	// directly.
	//
	// This handler only issues successful responses, such as 2xx or 3xx,
	// meaning it serves data or issues a redirect. If the blob is not
	// available, an error will be returned and the caller may still issue a
	// response.
	//
	// The implementation may serve the same blob from a different digest
	// domain. The appropriate headers will be set for the blob, unless they
	// have already been set by the caller.
	ServeBlob(ctx context.Context, w http.ResponseWriter, r *http.Request, dgst digest.Digest) error
}

BlobServer can serve blobs via http.

type BlobService

type BlobService interface {
	BlobStatter
	BlobProvider
	BlobIngester
}

BlobService combines the operations to access, read and write blobs. This can be used to describe remote blob services.

type BlobStatter added in v1.1.1

type BlobStatter interface {
	// Stat provides metadata about a blob identified by the digest. If the
	// blob is unknown to the describer, ErrBlobUnknown will be returned.
	Stat(ctx context.Context, dgst digest.Digest) (Descriptor, error)
}

BlobStatter makes blob descriptors available by digest. The service may provide a descriptor of a different digest if the provided digest is not canonical.

type BlobStore added in v1.1.1

type BlobStore interface {
	BlobService
	BlobServer
	BlobEnumerator
	BlobDeleter
}

BlobStore represent the entire suite of blob related operations. Such an implementation can access, enumerate, read, write, delete and serve blobs.

type BlobWriter added in v1.1.1

type BlobWriter interface {
	io.WriteSeeker
	io.ReaderFrom
	io.Closer

	// ID returns the identifier for this writer. The ID can be used with the
	// Blob service to later resume the write.
	ID() string

	// StartedAt returns the time this blob write was started.
	StartedAt() time.Time

	// Commit completes the blob writer process. The content is verified
	// against the provided provisional descriptor, which may result in an
	// error. Depending on the implementation, written data may be validated
	// against the provisional descriptor fields. If MediaType is not present,
	// the implementation may reject the commit or assign "application/octet-
	// stream" to the blob. The returned descriptor may have a different
	// digest depending on the blob store, referred to as the canonical
	// descriptor.
	Commit(ctx context.Context, provisional Descriptor) (canonical Descriptor, err error)

	// Cancel ends the blob write without storing any data and frees any
	// associated resources. Any data written thus far will be lost. Cancel
	// implementations should allow multiple calls even after a commit that
	// result in a no-op. This allows use of Cancel in a defer statement,
	// increasing the assurance that it is correctly called.
	Cancel(ctx context.Context) error

	// Get a reader to the blob being written by this BlobWriter
	Reader() (io.ReadCloser, error)
}

BlobWriter provides a handle for inserting data into a blob store. Instances should be obtained from BlobWriteService.Writer and BlobWriteService.Resume. If supported by the store, a writer can be recovered with the id.

type Descriptor

type Descriptor struct {
	// MediaType describe the type of the content. All text based formats are
	// encoded as utf-8.
	MediaType string `json:"mediaType,omitempty"`

	// Size in bytes of content.
	Size int64 `json:"size,omitempty"`

	// Digest uniquely identifies the content. A byte stream can be verified
	// against against this digest.
	Digest digest.Digest `json:"digest,omitempty"`
}

Descriptor describes targeted content. Used in conjunction with a blob store, a descriptor can be used to fetch, store and target any kind of blob. The struct also describes the wire protocol format. Fields should only be added but never changed.

type ErrBlobInvalidDigest added in v1.1.1

type ErrBlobInvalidDigest struct {
	Digest digest.Digest
	Reason error
}

ErrBlobInvalidDigest returned when digest check fails.

func (ErrBlobInvalidDigest) Error added in v1.1.1

func (err ErrBlobInvalidDigest) Error() string

type ErrManifestBlobUnknown added in v1.1.1

type ErrManifestBlobUnknown struct {
	Digest digest.Digest
}

ErrManifestBlobUnknown returned when a referenced blob cannot be found.

func (ErrManifestBlobUnknown) Error added in v1.1.1

func (err ErrManifestBlobUnknown) Error() string

type ErrManifestNameInvalid added in v1.1.1

type ErrManifestNameInvalid struct {
	Name   string
	Reason error
}

ErrManifestNameInvalid should be used to denote an invalid manifest name. Reason may set, indicating the cause of invalidity.

func (ErrManifestNameInvalid) Error added in v1.1.1

func (err ErrManifestNameInvalid) Error() string

type ErrManifestUnknown

type ErrManifestUnknown struct {
	Name string
	Tag  string
}

ErrManifestUnknown is returned if the manifest is not known by the registry.

func (ErrManifestUnknown) Error

func (err ErrManifestUnknown) Error() string

type ErrManifestUnknownRevision added in v1.1.1

type ErrManifestUnknownRevision struct {
	Name     string
	Revision digest.Digest
}

ErrManifestUnknownRevision is returned when a manifest cannot be found by revision within a repository.

func (ErrManifestUnknownRevision) Error added in v1.1.1

func (err ErrManifestUnknownRevision) Error() string

type ErrManifestUnverified

type ErrManifestUnverified struct{}

ErrManifestUnverified is returned when the registry is unable to verify the manifest.

func (ErrManifestUnverified) Error

func (ErrManifestUnverified) Error() string

type ErrManifestVerification

type ErrManifestVerification []error

ErrManifestVerification provides a type to collect errors encountered during manifest verification. Currently, it accepts errors of all types, but it may be narrowed to those involving manifest verification.

func (ErrManifestVerification) Error

func (errs ErrManifestVerification) Error() string

type ErrRepositoryNameInvalid

type ErrRepositoryNameInvalid struct {
	Name   string
	Reason error
}

ErrRepositoryNameInvalid should be used to denote an invalid repository name. Reason may set, indicating the cause of invalidity.

func (ErrRepositoryNameInvalid) Error

func (err ErrRepositoryNameInvalid) Error() string

type ErrRepositoryUnknown

type ErrRepositoryUnknown struct {
	Name string
}

ErrRepositoryUnknown is returned if the named repository is not known by the registry.

func (ErrRepositoryUnknown) Error

func (err ErrRepositoryUnknown) Error() string

type ManifestService

type ManifestService interface {
	// Exists returns true if the manifest exists.
	Exists(dgst digest.Digest) (bool, error)

	// Get retrieves the identified by the digest, if it exists.
	Get(dgst digest.Digest) (*schema1.SignedManifest, error)

	// Enumerate returns an array of manifest revisions in repository.
	Enumerate() ([]digest.Digest, error)

	// Delete removes the manifest, if it exists.
	Delete(dgst digest.Digest) error

	// Put creates or updates the manifest.
	Put(manifest *schema1.SignedManifest) error

	// Tags lists the tags under the named repository.
	Tags() ([]string, error)

	// ExistsByTag returns true if the manifest exists.
	ExistsByTag(tag string) (bool, error)

	// GetByTag retrieves the named manifest, if it exists.
	GetByTag(tag string, options ...ManifestServiceOption) (*schema1.SignedManifest, error)
}

ManifestService provides operations on image manifests.

type ManifestServiceOption added in v1.1.1

type ManifestServiceOption func(ManifestService) error

ManifestServiceOption is a function argument for Manifest Service methods

type Namespace

type Namespace interface {
	// Scope describes the names that can be used with this Namespace. The
	// global namespace will have a scope that matches all names. The scope
	// effectively provides an identity for the namespace.
	Scope() Scope

	// Repository should return a reference to the named repository. The
	// registry may or may not have the repository but should always return a
	// reference.
	Repository(ctx context.Context, name string) (Repository, error)

	// Repositories fills 'repos' with a lexigraphically sorted catalog of repositories
	// up to the size of 'repos' and returns the value 'n' for the number of entries
	// which were filled.  'last' contains an offset in the catalog, and 'err' will be
	// set to io.EOF if there are no more entries to obtain.
	Repositories(ctx context.Context, repos []string, last string) (n int, err error)

	// Blobs returns a reference to registry's blob service.
	Blobs() BlobService
}

Namespace represents a collection of repositories, addressable by name. Generally, a namespace is backed by a set of one or more services, providing facilities such as registry access, trust, and indexing.

type ReadSeekCloser added in v1.1.1

type ReadSeekCloser interface {
	io.ReadSeeker
	io.Closer
}

ReadSeekCloser is the primary reader type for blob data, combining io.ReadSeeker with io.Closer.

type Repository

type Repository interface {
	// Name returns the name of the repository.
	Name() string

	// Manifests returns a reference to this repository's manifest service.
	// with the supplied options applied.
	Manifests(ctx context.Context, options ...ManifestServiceOption) (ManifestService, error)

	// Blobs returns a reference to this repository's blob service.
	Blobs(ctx context.Context) BlobStore

	// Signatures returns a reference to this repository's signatures service.
	Signatures() SignatureService
}

Repository is a named collection of manifests and layers.

type Scope

type Scope interface {
	// Contains returns true if the name belongs to the namespace.
	Contains(name string) bool
}

Scope defines the set of items that match a namespace.

type SignatureService

type SignatureService interface {
	// Get retrieves all of the signature blobs for the specified digest.
	Get(dgst digest.Digest) ([][]byte, error)

	// Enumerate retrieves all signature digests for given manifest revision,
	// if it exists.
	Enumerate(dgst digest.Digest) ([]digest.Digest, error)

	// Put stores the signature for the provided digest.
	Put(dgst digest.Digest, signatures ...[]byte) error

	// Delete removes all signature links of particular manifest revision.
	Delete(revision digest.Digest) error
}

SignatureService provides operations on signatures.

Directories

Path Synopsis
cmd
registry-api-descriptor-template
registry-api-descriptor-template uses the APIDescriptor defined in the api/v2 package to execute templates passed to the command line.
registry-api-descriptor-template uses the APIDescriptor defined in the api/v2 package to execute templates passed to the command line.
Package context provides several utilities for working with golang.org/x/net/context in http requests.
Package context provides several utilities for working with golang.org/x/net/context in http requests.
Package digest provides a generalized type to opaquely represent message digests and their operations within the registry.
Package digest provides a generalized type to opaquely represent message digests and their operations within the registry.
Package health provides a generic health checking framework.
Package health provides a generic health checking framework.
api
Package reference provides a general type to represent any way of referencing images within the registry.
Package reference provides a general type to represent any way of referencing images within the registry.
Package registry provides the main entrypoints for running a registry.
Package registry provides the main entrypoints for running a registry.
api/v2
Package v2 describes routes, urls and the error codes used in the Docker Registry JSON HTTP API V2.
Package v2 describes routes, urls and the error codes used in the Docker Registry JSON HTTP API V2.
auth
Package auth defines a standard interface for request access controllers.
Package auth defines a standard interface for request access controllers.
auth/htpasswd
Package htpasswd provides a simple authentication scheme that checks for the user credential hash in an htpasswd formatted file in a configuration-determined location.
Package htpasswd provides a simple authentication scheme that checks for the user credential hash in an htpasswd formatted file in a configuration-determined location.
auth/silly
Package silly provides a simple authentication scheme that checks for the existence of an Authorization header and issues access if is present and non-empty.
Package silly provides a simple authentication scheme that checks for the existence of an Authorization header and issues access if is present and non-empty.
storage
Package storage contains storage services for use in the registry application.
Package storage contains storage services for use in the registry application.
storage/cache
Package cache provides facilities to speed up access to the storage backend.
Package cache provides facilities to speed up access to the storage backend.
storage/driver/azure
Package azure provides a storagedriver.StorageDriver implementation to store blobs in Microsoft Azure Blob Storage Service.
Package azure provides a storagedriver.StorageDriver implementation to store blobs in Microsoft Azure Blob Storage Service.
storage/driver/base
Package base provides a base implementation of the storage driver that can be used to implement common checks.
Package base provides a base implementation of the storage driver that can be used to implement common checks.
storage/driver/gcs
Package gcs implements the Google Cloud Storage driver backend.
Package gcs implements the Google Cloud Storage driver backend.
storage/driver/middleware/cloudfront
Package middleware - cloudfront wrapper for storage libs N.B. currently only works with S3, not arbitrary sites
Package middleware - cloudfront wrapper for storage libs N.B. currently only works with S3, not arbitrary sites
storage/driver/oss
Package oss implements the Aliyun OSS Storage driver backend.
Package oss implements the Aliyun OSS Storage driver backend.
storage/driver/rados
Package rados implements the rados storage driver backend.
Package rados implements the rados storage driver backend.
storage/driver/s3
Package s3 provides a storagedriver.StorageDriver implementation to store blobs in Amazon S3 cloud storage.
Package s3 provides a storagedriver.StorageDriver implementation to store blobs in Amazon S3 cloud storage.
storage/driver/swift
Package swift provides a storagedriver.StorageDriver implementation to store blobs in Openstack Swift object storage.
Package swift provides a storagedriver.StorageDriver implementation to store blobs in Openstack Swift object storage.
Package uuid provides simple UUID generation.
Package uuid provides simple UUID generation.

Jump to

Keyboard shortcuts

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