vbatts/registry
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Retooling to allow for docs build

Browse source 
Adding docs build to the Makefile
Adding in Sven's changes to the Makefile
Removing DS_store file
Updating per Stephen's comments
Update with Stephen's final comment

Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony 2015-04-01 11:28:34 -07:00
parent 0eb50c18ea
commit 636a19b212
20 changed files with 43 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/Dockerfile Normal file
View file

@ -0,0 +1,17 @@
FROM docs/base:latest
MAINTAINER Mary <mary@docker.com> (@moxiegirl)
# to get the git info for this repo
COPY . /src
# Reset the /docs dir so we can replace the theme meta with the new repo's git info
RUN git reset --hard
#
#
RUN git describe --match 'v[0-9]*' --dirty='.m' --always > /docs/VERSION
COPY docs/* /docs/sources/distribution/
COPY docs/mkdocs.yml /docs/mkdocs-distribution.yml
# Then build everything together, ready for mkdocs
RUN /docs/build.sh

50
docs/architecture.md Normal file
View file

@ -0,0 +1,50 @@
# Architecture
**TODO(stevvooe):** Discuss the architecture of the registry, internally and
externally, in a few different deployment scenarios.
## Design
### Eventual Consistency
> **NOTE:** This section belongs somewhere, perhaps in a design document. We
> are leaving this here so the information is not lost.
Running the registry on eventually consistent backends has been part of the
design from the beginning. This section covers some of the approaches to
dealing with this reality.
There are a few classes of issues that we need to worry about when
implementing something on top of the storage drivers:
1. Read-After-Write consistency (see this [article on
s3](http://shlomoswidler.com/2009/12/read-after-write-consistency-in-amazon.html)).
2. [Write-Write Conflicts](http://en.wikipedia.org/wiki/Write%E2%80%93write_conflict).
In reality, the registry must worry about these kinds of errors when doing the
following:
1. Accepting data into a temporary upload file may not have latest data block
yet (read-after-write).
2. Moving uploaded data into its blob location (write-write race).
3. Modifying the "current" manifest for given tag (write-write race).
4. A whole slew of operations around deletes (read-after-write, delete-write
races, garbage collection, etc.).
The backend path layout employs a few techniques to avoid these problems:
1. Large writes are done to private upload directories. This alleviates most
of the corruption potential under multiple writers by avoiding multiple
writers.
2. Constraints in storage driver implementations, such as support for writing
after the end of a file to extend it.
3. Digest verification to avoid data corruption.
4. Manifest files are stored by digest and cannot change.
5. All other non-content files (links, hashes, etc.) are written as an atomic
unit. Anything that requires additions and deletions is broken out into
separate "files". Last writer still wins.
Unfortunately, one must play this game when trying to build something like
this on top of eventually consistent storage systems. If we run into serious
problems, we can wrap the storagedrivers in a shared consistency layer but
that would increase complexity and hinder registry cluster performance.

417
docs/configuration.md Normal file
View file

@ -0,0 +1,417 @@
# Configuration
Below is a comprehensive example of all possible configuration options for the registry. Some options are mutually exclusive, and each section is explained in more detail below, but this is a good starting point from which you may delete the sections you do not need to create your own configuration. A copy of this configuration can be found at config.sample.yml.
```yaml
version: 0.1
log:
level: debug
formatter: text
fields:
service: registry
environment: staging
loglevel: debug # deprecated: use "log"
storage:
filesystem:
rootdirectory: /tmp/registry
azure:
accountname: accountname
accountkey: base64encodedaccountkey
container: containername
s3:
accesskey: awsaccesskey
secretkey: awssecretkey
region: us-west-1
bucket: bucketname
encrypt: true
secure: true
v4auth: true
chunksize: 5242880
rootdirectory: /s3/object/name/prefix
cache:
layerinfo: inmemory
auth:
silly:
realm: silly-realm
service: silly-service
token:
realm: token-realm
service: token-service
issuer: registry-token-issuer
rootcertbundle: /root/certs/bundle
middleware:
registry:
- name: ARegistryMiddleware
options:
foo: bar
repository:
- name: ARepositoryMiddleware
options:
foo: bar
storage:
- name: cloudfront
options:
baseurl: https://my.cloudfronted.domain.com/
privatekey: /path/to/pem
keypairid: cloudfrontkeypairid
duration: 3000
reporting:
bugsnag:
apikey: bugsnagapikey
releasestage: bugsnagreleasestage
endpoint: bugsnagendpoint
newrelic:
licensekey: newreliclicensekey
name: newrelicname
http:
addr: localhost:5000
prefix: /my/nested/registry/
secret: asecretforlocaldevelopment
tls:
certificate: /path/to/x509/public
key: /path/to/x509/private
clientcas:
- /path/to/ca.pem
- /path/to/another/ca.pem
debug:
addr: localhost:5001
notifications:
endpoints:
- name: alistener
disabled: false
url: https://my.listener.com/event
headers: <http.Header>
timeout: 500
threshold: 5
backoff: 1000
redis:
addr: localhost:6379
password: asecret
db: 0
dialtimeout: 10ms
readtimeout: 10ms
writetimeout: 10ms
pool:
maxidle: 16
maxactive: 64
idletimeout: 300s
```
N.B. In some instances a configuration option may be marked **optional** but contain child options marked as **required**. This indicates that a parent may be omitted with all its children, however, if the parent is included, the children marked **required** must be included.
## version
```yaml
version: 0.1
```
The version option is **required** and indicates the version of the configuration being used. It is expected to remain a top-level field, to allow for a consistent version check before parsing the remainder of the configuration file.
N.B. The version of the registry software may be found at [/version/version.go](https://github.com/docker/distribution/blob/master/version/version.go)
## log
The log subsection configures the behavior of the logging system. The logging
system outputs everything to stdout. The granularity and format of the log
messages can be adjusted with this configuration section.
```yaml
log:
level: debug
formatter: text
fields:
service: registry
environment: staging
```
- level: **Optional** - Sets the sensitivity of logging output. Permitted
values are `error`, `warn`, `info` and `debug`. The default is `info`.
- formatter: **Optional** - This selects the format of logging output, which
mostly affects how keyed attributes for a log line are encoded. Options are
"text", "json" or "logstash". The default is "text".
- fields: **Optional** - A map of field names to values that will be added to
every log line for the context. This is useful for identifying log messages
source after being mixed in other systems.
## loglevel
> **DEPRECATED:** Please use [log](#log) instead.
```yaml
loglevel: debug
```
Permitted values are `error`, `warn`, `info` and `debug`. The default is
`info`.
## storage
```yaml
storage:
filesystem:
rootdirectory: /tmp/registry
azure:
accountname: accountname
accountkey: base64encodedaccountkey
container: containername
s3:
accesskey: awsaccesskey
secretkey: awssecretkey
region: us-west-1
bucket: bucketname
encrypt: true
secure: true
v4auth: true
chunksize: 5242880
rootdirectory: /s3/object/name/prefix
cache:
layerinfo: inmemory
```
The storage option is **required** and defines which storage backend is in use. At the moment only one backend may be configured, an error is returned when the registry is started with more than one storage backend configured.
A `cache` subsection can be used to enable caching of data accessed in the
storage backend. Currently, the only available cache provides fast access to
layer metadata. This if configured using the `layerinfo` field. The following
cache implementations are available:
- redis: using the redis pool to cache layer meta data.
- inmemory: use an in memory map to cache layer meta data.
The following backends may be configured, **all options for a given storage backend are required**:
### filesystem
This storage backend uses the local disk to store registry files. It is ideal for development and may be appropriate for some small scale production applications.
- rootdirectory: **Required** - This is the absolute path to directory in which the repository will store data.
### azure
This storage backend uses Microsoft's Azure Storage platform.
- accountname: **Required** - Azure account name
- accountkey: **Required** - Azure account key
- container: **Required** - Name of the Azure container into which data will be stored
### S3
This storage backend uses Amazon's Simple Storage Service (a.k.a. S3).
- accesskey: **Required** - Your AWS Access Key
- secretkey: **Required** - Your AWS Secret Key.
- region: **Required** - The AWS region in which your bucket exists. For the moment, the Go AWS library in use does not use the newer DNS based bucket routing.
- bucket: **Required** - The bucket name in which you want to store the registry's data.
- encrypt: TODO: fill in description
- secure: TODO: fill in description
- v4auth: This indicates whether Version 4 of AWS's authentication should be used. Generally you will want to set this to true.
- chunksize: TODO: fill in description
- rootdirectory: **Optional** - This is a prefix that will be applied to all S3 keys to allow you to segment data in your bucket if necessary.
## auth
```yaml
auth:
silly:
realm: silly-realm
service: silly-service
token:
realm: token-realm
service: token-service
issuer: registry-token-issuer
rootcertbundle: /root/certs/bundle
```
The auth option is **optional** as there are use cases (i.e. a mirror that only permits pulls) for which authentication may not be desired. There are currently 2 possible auth providers, "silly" and "token", only one auth provider may be configured at the moment:
### silly
The "silly" auth is only for development purposes. It simply checks for the existence of the "Authorization" header in the HTTP request, with no regard for the value of the header. If the header does not exist, it will respond with a challenge response, echoing back the realm, service, and scope that access was denied for.
The values of the ```realm``` and ```service``` options are used in authentication reponses, both options are **required**
- realm: **Required** - The realm in which the registry server authenticates.
- service: **Required** - The service being authenticated.
### token
Token based authentication allows the authentication system to be decoupled from the registry. It is a well established authentication paradigm with a high degree of security.
- realm: **Required** - The realm in which the registry server authenticates.
- service: **Required** - The service being authenticated.
- issuer: **Required** - The name of the token issuer. The issuer inserts this into the token so it must match the value configured for the issuer.
- rootcertbundle: **Required** - The absolute path to the root certificate bundle containing the public part of the certificates that will be used to sign authentication tokens.
For more information about Token based authentication configuration, see the [specification.](spec/auth/token.md)
## middleware
The middleware option is **optional** and allows middlewares to be injected at named hook points. A requirement of all middlewares is that they implement the same interface as the object they're wrapping. This means a registry middleware must implement the `distribution.Registry` interface, repository middleware must implement `distribution.Respository`, and storage middleware must implement `driver.StorageDriver`.
Currently only one middleware, cloudfront, a storage middleware, is included in the registry.
```yaml
middleware:
registry:
- name: ARegistryMiddleware
options:
foo: bar
repository:
- name: ARepositoryMiddleware
options:
foo: bar
storage:
- name: cloudfront
options:
baseurl: https://my.cloudfronted.domain.com/
privatekey: /path/to/pem
keypairid: cloudfrontkeypairid
duration: 3000
```
Each middleware entry has `name` and `options` entries. The `name` must correspond to the name under which the middleware registers itself. The `options` field is a map that details custom configuration required to initialize the middleware. It is treated as a map[string]interface{} and as such will support any interesting structures desired, leaving it up to the middleware initialization function to best determine how to handle the specific interpretation of the options.
### cloudfront
- baseurl: **Required** - SCHEME://HOST[/PATH] at which Cloudfront is served.
- privatekey: **Required** - Private Key for Cloudfront provided by AWS
- keypairid: **Required** - Key Pair ID provided by AWS
- duration: **Optional** - Duration for which a signed URL should be valid
## reporting
```yaml
reporting:
bugsnag:
apikey: bugsnagapikey
releasestage: bugsnagreleasestage
endpoint: bugsnagendpoint
newrelic:
licensekey: newreliclicensekey
name: newrelicname
```
The reporting option is **optional** and configures error and metrics reporting tools. At the moment only two services are supported, New Relic and Bugsnag, a valid configuration may contain both.
### bugsnag
- apikey: **Required** - API Key provided by Bugsnag
- releasestage: **Optional** - TODO: fill in description
- endpoint: **Optional** - TODO: fill in description
### newrelic
- licensekey: **Required** - License key provided by New Relic
- name: **Optional** - New Relic application name
## http
```yaml
http:
addr: localhost:5000
prefix: /my/nested/registry/
secret: asecretforlocaldevelopment
tls:
certificate: /path/to/x509/public
key: /path/to/x509/private
clientcas:
- /path/to/ca.pem
- /path/to/another/ca.pem
debug:
addr: localhost:5001
```
The http option details the configuration for the HTTP server that hosts the registry.
- addr: **Required** - The HOST:PORT for which the server should accept connections.
- prefix: **Optional** - If the server will not run at the root path, this should specify the prefix (the part of the path before ```v2```). It should have both preceding and trailing slashes.
- secret: A random piece of data. It is used to sign state that may be stored with the client to protect against tampering. For production use you should generate a random piece of data using a cryptographically secure random generator.
### tls
The tls option within http is **optional** and allows you to configure SSL for the server. If you already have a server such as Nginx or Apache running on the same host as the registry, you may prefer to configure SSL termination there and proxy connections to the registry server.
- certificate: **Required** - Absolute path to x509 cert file
- key: **Required** - Absolute path to x509 private key file
- clientcas: **Optional** - An array of absolute paths to a x509 CA file
### debug
The debug option is **optional** and allows you to configure a debug server that can be helpful in diagnosing problems. It is of most use to contributers to the distribution repository and should generally be disabled in production deployments.
- addr: **Required** - The HOST:PORT on which the debug server should accept connections.
## notifications
```yaml
notifications:
endpoints:
- name: alistener
disabled: false
url: https://my.listener.com/event
headers: <http.Header>
timeout: 500
threshold: 5
backoff: 1000
```
The notifications option is **optional** and currently may contain a single option, ```endpoints```.
### endpoints
Endpoints is a list of named services (URLs) that can accept event notifications.
- name: **Required** - A human readable name for the service.
- disabled: **Optional** - A boolean to enable/disable notifications for a service.
- url: **Required** - The URL to which events should be published.
- headers: **Required** - TODO: fill in description
- timeout: **Required** - TODO: fill in description
- threshold: **Required** - TODO: fill in description
- backoff: **Required** - TODO: fill in description
## redis
```yaml
redis:
addr: localhost:6379
password: asecret
db: 0
dialtimeout: 10ms
readtimeout: 10ms
writetimeout: 10ms
pool:
maxidle: 16
maxactive: 64
idletimeout: 300s
```
Declare parameters for constructing the redis connections. Registry instances
may use the redis instance for several applications. The current purpose is
caching information about immutable blobs. Most of the options below control
how the registry connects to redis. The behavior of the pool can be controlled
with the [pool](#pool) subsection.
- addr: **Required** - Address (host and port) of redis instance.
- password: **Optional** - A password used to authenticate to the redis instance.
- db: **Optional** - Selects the db for each connection.
- dialtimeout: **Optional** - Timeout for connecting to a redis instance.
- readtimeout: **Optional** - Timeout for reading from redis connections.
- writetimeout: **Optional** - Timeout for writing to redis connections.
### pool
```yaml
pool:
maxidle: 16
maxactive: 64
idletimeout: 300s
```
Configure the behavior of the redis connection pool.
- maxidle: **Optional** - sets the maximum number of idle connections.
- maxactive: **Optional** - sets the maximum number of connections that should
be opened before blocking a connection request.
- idletimeout: **Optional** - sets the amount time to wait before closing
inactive connections.

44
docs/deploying.md Normal file
View file

@ -0,0 +1,44 @@
# Deploying
**TODO(stevvooe):** This should discuss various deployment scenarios for
production-ready deployments. These may be backed by ready-made docker images
but this should explain how they were created and what considerations were
present.
# Middleware Configuration
This section describes how to configure storage middleware in the registry to enable layers to be served via a CDN, thus reducing requests to the storage layer. Currently [Amazon Cloudfront](http://aws.amazon.com/cloudfront/) is supported and must be used in conjunction with the S3 storage driver.
## Cloudfront
## Parameters
`name`: The name of the storage middleware. Currently `cloudfront` is an accepted value.
`disabled`: This can be set to false to easily disable the middleware.
`options` : A set of key/value options to configure the middleware:
* `baseurl` : The cloudfront base URL
* `privatekey` : The location of your AWS private key on the filesystem
* `keypairid` : The ID of your Cloudfront keypair.
* `duration` : The duration in minutes for which the URL is valid. Default is 20.
Note: Cloudfront keys exist separately to other AWS keys. See [here](http://docs.aws.amazon.com/AWSSecurityCredentials/1.0/AboutAWSCredentials.html#KeyPairs) for more information.
## Example
```
middleware:
storage:
- name: cloudfront
disabled: false
options:
baseurl: http://d111111abcdef8.cloudfront.net
privatekey: /path/to/asecret.pem
keypairid: asecret
duration: 60
```

39
docs/glossary.md Normal file
View file

@ -0,0 +1,39 @@
# Glossary
**TODO(stevvooe):** Define and describe distribution related terms. Ideally,
we reference back to the actual documentation and specifications where
appropriate.
**TODO(stevvooe):** The following list is a start but woefully incomplete.
<dl>
<dt>Blob</dt>
<dd>
The primary unit of registry storage. A string of bytes identified by
content-address, known as a _digest_.
</dd>
<dt>Image</dt>
<dd>An image is a collection of content from which a docker container can be created.</dd>
<dt>Layer</dt>
<dd>
A tar file representing the partial content of a filesystem. Several
layers can be "stacked" to make up the root filesystem.
</dd>
<dt>Manifest</dt>
<dd>Describes a collection layers that make up an image.</dd>
<dt>Registry</dt>
<dd>A registry is a collection of repositories.</dd>
<dt>Repository</dt>
<dd>
A repository is a collection of docker images, made up of manifests, tags
and layers. The base unit of these components are blobs.
</dd>
<dt>Tag</dt>
<dd>Tag provides a common name to an image.</dd>
</dl>

0
docs/install.md Normal file
View file

6
docs/mkdocs.yml Normal file
View file

@ -0,0 +1,6 @@
- ['distribution/overview.md', 'User Guide', 'Docker Distribution' ]
- ['distribution/install.md', 'Installation', 'Docker Distribution']
- ['distribution/architecture.md', 'Reference', 'Distribution Architecture']

308
docs/notifications.md Normal file
View file

@ -0,0 +1,308 @@
# Notifications
> **TODO:** Link out to the architecture document on notification support.
The Registry supports sending webhook notifications in response to events
happening within the registry. Notifications are sent in response to manifest
pushes and pulls and layer pushes and pulls. These actions are serialized into
events. The events are queued into a registry-internal broadcast system which
queues and dispatches events to [_Endpoints_](#endpoints).
> **TODO:** Insert diagram of event system.
## Endpoints
Notifications are sent to _endpoints_ via HTTP requests. Each configurated
endpoint has isolated queues, retry configuration and http targets within each
instance of a registry. When an action happens within the registry, it is
converted into an event which is dropped into an inmemory queue. When the
event reaches the end of the queue, an http request is made to the endpoint
until the request succeeds. The events are sent serially to each endpoint but
order is not guaranteed.
## Configuration
To setup a registry instance to send notifications to endpoints, one must add
them to the configuration. A simple example follows:
```yaml
notifications:
endpoints:
- name: alistener
url: https://mylistener.example.com/event
headers:
Authorization: [Bearer <your token, if needed>]
timeout: 500ms
threshold: 5
backoff: 1s
```
The above would configure the registry with an endpoint to send events to
"https://mylistener.example.com/event", with the header "Authorization: Bearer
<your token, if needed>". The request would timeout after 500 milliseconds. If
5 failures happen consecutively, the registry will backoff for 1 second before
trying again.
For details on the fields, please see the [configuration documentation](configuration.md#notifications).
A properly configured endpoint should lead to a log message from the registry
upon startup:
```
INFO[0000] configuring endpoint alistener (https://mylistener.example.com/event), timeout=500ms, headers=map[Authorization:[Bearer <your token if needed>]] app.id=812bfeb2-62d6-43cf-b0c6-152f541618a3 environment=development service=registry
```
## Events
Events have a well-defined JSON structure and are sent as the body of
notification requests. One or more events are sent in a structure called an
envelope. Each event has a unique id that can be used to uniqify incoming
requests, if required. Along with that, an _action_ is provided with a
_target, identifying the object mutated during the event.
The fields available in an event are described in detail in the
[godoc](http://godoc.org/github.com/docker/distribution/notifications#Event).
> **TODO:** Let's break out the fields here rather than rely on the godoc.
The following is an example of a JSON event, sent in response to the push of a
manifest:
```json
{
"id": "asdf-asdf-asdf-asdf-0",
"timestamp": "2006-01-02T15:04:05Z",
"action": "push",
"target": {
"mediaType": "application/vnd.docker.distribution.manifest.v1+json",
"length": 1,
"digest": "sha256:0123456789abcdef0",
"repository": "library/test",
"url": "http://example.com/v2/library/test/manifests/latest"
},
"request": {
"id": "asdfasdf",
"addr": "client.local",
"host": "registrycluster.local",
"method": "PUT",
"useragent": "test/0.1"
},
"actor": {
"name": "test-actor"
},
"source": {
"addr": "hostname.local:port"
}
}
```
## Envelope
The envelope contains one or more events, with the following json structure:
```json
{
"events": [ ... ],
}
```
While events may be sent in the same envelope, the set of events within that
envelope have no implied relationship. For example, the registry may choose to
group unrelated events and send them in the same envelope to reduce the total
number of requests.
The full package has the mediatype
"application/vnd.docker.distribution.events.v1+json", which will be set on the
request coming to an endpoint.
An example of a full event may look as follows:
```json
GET /callback
Host: application/vnd.docker.distribution.events.v1+json
Authorization: Bearer <your token, if needed>
Content-Type: application/vnd.docker.distribution.events.v1+json
{
"events": [
{
"id": "asdf-asdf-asdf-asdf-0",
"timestamp": "2006-01-02T15:04:05Z",
"action": "push",
"target": {
"mediaType": "application/vnd.docker.distribution.manifest.v1+json",
"length": 1,
"digest": "sha256:0123456789abcdef0",
"repository": "library/test",
"url": "http://example.com/v2/library/test/manifests/latest"
},
"request": {
"id": "asdfasdf",
"addr": "client.local",
"host": "registrycluster.local",
"method": "PUT",
"useragent": "test/0.1"
},
"actor": {
"name": "test-actor"
},
"source": {
"addr": "hostname.local:port"
}
},
{
"id": "asdf-asdf-asdf-asdf-1",
"timestamp": "2006-01-02T15:04:05Z",
"action": "push",
"target": {
"mediaType": "application/vnd.docker.container.image.rootfs.diff+x-gtar",
"length": 2,
"digest": "tarsum.v2+sha256:0123456789abcdef1",
"repository": "library/test",
"url": "http://example.com/v2/library/test/manifests/latest"
},
"request": {
"id": "asdfasdf",
"addr": "client.local",
"host": "registrycluster.local",
"method": "PUT",
"useragent": "test/0.1"
},
"actor": {
"name": "test-actor"
},
"source": {
"addr": "hostname.local:port"
}
},
{
"id": "asdf-asdf-asdf-asdf-2",
"timestamp": "2006-01-02T15:04:05Z",
"action": "push",
"target": {
"mediaType": "application/vnd.docker.container.image.rootfs.diff+x-gtar",
"length": 3,
"digest": "tarsum.v2+sha256:0123456789abcdef2",
"repository": "library/test",
"url": "http://example.com/v2/library/test/manifests/latest"
},
"request": {
"id": "asdfasdf",
"addr": "client.local",
"host": "registrycluster.local",
"method": "PUT",
"useragent": "test/0.1"
},
"actor": {
"name": "test-actor"
},
"source": {
"addr": "hostname.local:port"
}
}
]
}
```
## Responses
The registry is fairly accepting of the response codes from endpoints. If an
endpoint responds with any 2xx or 3xx response code (after following
redirects), the message will be considered delivered and discarded.
In turn, it is recommended that endpoints are accepting of incoming responses,
as well. While the format of event envelopes are standardized by media type,
any "pickyness" about validation may cause the queue to backup on the
registry.
## Monitoring
The state of the endpoints are reported via the debug/vars http interface,
usually configured to "http://localhost:5001/debug/vars". Information such as
configuration and metrics are available by endpoint.
The following provides and example of a few endpoints that have experience
several failures and have since recovered:
```json
"notifications":{
"endpoints":[
{
"name":"local-8082",
"url":"http://localhost:5003/callback",
"Headers":{
"Authorization":[
"Bearer \u003can example token\u003e"
]
},
"Timeout":1000000000,
"Threshold":10,
"Backoff":1000000000,
"Metrics":{
"Pending":76,
"Events":76,
"Successes":0,
"Failures":0,
"Errors":46,
"Statuses":{
}
}
},
{
"name":"local-8083",
"url":"http://localhost:8083/callback",
"Headers":null,
"Timeout":1000000000,
"Threshold":10,
"Backoff":1000000000,
"Metrics":{
"Pending":0,
"Events":76,
"Successes":76,
"Failures":0,
"Errors":28,
"Statuses":{
"202 Accepted":76
}
}
}
]
}
```
If using notification as part of a larger application, it is _critical_ to
monitor the size ("Pending" above) of the endpoint queues. If failures or
queue sizes are increasing, it can indicate a larger problem.
The logs are also a valuable resource for monitoring problems. A failing
endpoint will lead to messages similar to the following:
```
ERRO[0340] retryingsink: error writing events: httpSink{http://localhost:5003/callback}: error posting: Post http://localhost:5003/callback: dial tcp 127.0.0.1:5003: connection refused, retrying
WARN[0340] httpSink{http://localhost:5003/callback} encountered too many errors, backing off
```
The above indicates that several errors have led to a backoff and the registry
will wait before retrying.
## Considerations
Currently, the queues are inmemory, so endpoints should be _reasonably
reliable_. They are designed to make a best-effort to send the messages but if
an instance is lost, messages may be dropped. If an endpoint goes down, care
should be taken to ensure that the registry instance is not terminated before
the endpoint comes back up or messages will be lost.
This can be mitigated by running endpoints in close proximity to the registry
instances. One could run an endpoint that pages to disk and then forwards a
request to provide better durability.
The notification system is designed around a series of interchangeable _sinks_
which can be wired up to achieve interesting behavior. If this system doesn't
provide acceptable guarantees, adding a transactional `Sink` to the registry
is a possibility, although it may have an effect on request service time.
Please see the
[godoc](http://godoc.org/github.com/docker/distribution/notifications#Sink)
for more information.

6
docs/overview.md Normal file
View file

@ -0,0 +1,6 @@
# Overview
**TODO(stevvooe):** Table of contents.
**TODO(stevvooe):** Include a full overview of each component and dispatch the
user to the correct documentation.

2665
docs/spec/api.md Normal file
View file

File diff suppressed because it is too large Load diff

796
docs/spec/api.md.tmpl Normal file
View file

@ -0,0 +1,796 @@
# Docker Registry HTTP API V2
## Introduction
The _Docker Registry HTTP API_ is the protocol to facilitate distribution of
images to the docker engine. It interacts with instances of the docker
registry, which is a service to manage information about docker images and
enable their distribution. The specification covers the operation of version 2
of this API, known as _Docker Registry HTTP API V2_.
While the V1 registry protocol is usable, there are several problems with the
architecture that have led to this new version. The main driver of this
specification these changes to the docker the image format, covered in
docker/docker#8093. The new, self-contained image manifest simplifies image
definition and improves security. This specification will build on that work,
leveraging new properties of the manifest format to improve performance,
reduce bandwidth usage and decrease the likelihood of backend corruption.
For relevant details and history leading up to this specification, please see
the following issues:
- [docker/docker#8093](https://github.com/docker/docker/issues/8093)
- [docker/docker#9015](https://github.com/docker/docker/issues/9015)
- [docker/docker-registry#612](https://github.com/docker/docker-registry/issues/612)
### Scope
This specification covers the URL layout and protocols of the interaction
between docker registry and docker core. This will affect the docker core
registry API and the rewrite of docker-registry. Docker registry
implementations may implement other API endpoints, but they are not covered by
this specification.
This includes the following features:
- Namespace-oriented URI Layout
- PUSH/PULL registry server for V2 image manifest format
- Resumable layer PUSH support
- V2 Client library implementation
While authentication and authorization support will influence this
specification, details of the protocol will be left to a future specification.
Relevant header definitions and error codes are present to provide an
indication of what a client may encounter.
#### Future
There are features that have been discussed during the process of cutting this
specification. The following is an incomplete list:
- Immutable image references
- Multiple architecture support
- Migration from v2compatibility representation
These may represent features that are either out of the scope of this
specification, the purview of another specification or have been deferred to a
future version.
### Use Cases
For the most part, the use cases of the former registry API apply to the new
version. Differentiating use cases are covered below.
#### Image Verification
A docker engine instance would like to run verified image named
"library/ubuntu", with the tag "latest". The engine contacts the registry,
requesting the manifest for "library/ubuntu:latest". An untrusted registry
returns a manifest. Before proceeding to download the individual layers, the
engine verifies the manifest's signature, ensuring that the content was
produced from a trusted source and no tampering has occured. After each layer
is downloaded, the engine verifies the digest of the layer, ensuring that the
content matches that specified by the manifest.
#### Resumable Push
Company X's build servers lose connectivity to docker registry before
completing an image layer transfer. After connectivity returns, the build
server attempts to re-upload the image. The registry notifies the build server
that the upload has already been partially attempted. The build server
responds by only sending the remaining data to complete the image file.
#### Resumable Pull
Company X is having more connectivity problems but this time in their
deployment datacenter. When downloading an image, the connection is
interrupted before completion. The client keeps the partial data and uses http
`Range` requests to avoid downloading repeated data.
#### Layer Upload De-duplication
Company Y's build system creates two identical docker layers from build
processes A and B. Build process A completes uploading the layer before B.
When process B attempts to upload the layer, the registry indicates that its
not necessary because the layer is already known.
If process A and B upload the same layer at the same time, both operations
will proceed and the first to complete will be stored in the registry (Note:
we may modify this to prevent dogpile with some locking mechanism).
### Changes
The V2 specification has been written to work as a living document, specifying
only what is certain and leaving what is not specified open or to future
changes. Only non-conflicting additions should be made to the API and accepted
changes should avoid preventing future changes from happening.
This section should be updated when changes are made to the specification,
indicating what is different. Optionally, we may start marking parts of the
specification to correspond with the versions enumerated here.
<dl>
<dt>2.0.1</dt>
<dd>
<ul>
<li>Added support for immutable manifest references in manifest endpoints.</li>
<li>Deleting a manifest by tag has been deprecated.</li>
<li>Specified `Docker-Content-Digest` header for appropriate entities.</li>
<li>Added error code for unsupported operations.</li>
</ul>
</dd>
<dt>2.0</dt>
<dd>
This is the baseline specification.
</dd>
</dl>
## Overview
This section covers client flows and details of the API endpoints. The URI
layout of the new API is structured to support a rich authentication and
authorization model by leveraging namespaces. All endpoints will be prefixed
by the API version and the repository name:
/v2/<name>/
For example, an API endpoint that will work with the `library/ubuntu`
repository, the URI prefix will be:
/v2/library/ubuntu/
This scheme provides rich access control over various operations and methods
using the URI prefix and http methods that can be controlled in variety of
ways.
Classically, repository names have always been two path components where each
path component is less than 30 characters. The V2 registry API does not
enforce this. The rules for a repository name are as follows:
1. A repository name is broken up into _path components_. A component of a
repository name must be at least two lowercase, alpha-numeric characters,
optionally separated by periods, dashes or underscores. More strictly, it
must match the regular expression `[a-z0-9]+(?:[._-][a-z0-9]+)*` and the
matched result must be 2 or more characters in length.
2. The name of a repository must have at least two path components, separated
by a forward slash.
3. The total length of a repository name, including slashes, must be less the
256 characters.
These name requirements _only_ apply to the registry API and should accept a
superset of what is supported by other docker ecosystem components.
All endpoints should support aggressive http caching, compression and range
headers, where appropriate. The new API attempts to leverage HTTP semantics
where possible but may break from standards to implement targeted features.
For detail on individual endpoints, please see the [_Detail_](#detail)
section.
### Errors
Actionable failure conditions, covered in detail in their relevant sections,
are reported as part of 4xx responses, in a json response body. One or more
errors will be returned in the following format:
{
"errors:" [{
"code": <error identifier>,
"message": <message describing condition>,
"detail": <unstructured>
},
...
]
}
The `code` field will be a unique identifier, all caps with underscores by
convention. The `message` field will be a human readable string. The optional
`detail` field may contain arbitrary json data providing information the
client can use to resolve the issue.
While the client can take action on certain error codes, the registry may add
new error codes over time. All client implementations should treat unknown
error codes as `UNKNOWN`, allowing future error codes to be added without
breaking API compatibility. For the purposes of the specification error codes
will only be added and never removed.
For a complete account of all error codes, please see the _Detail_ section.
### API Version Check
A minimal endpoint, mounted at `/v2/` will provide version support information
based on its response statuses. The request format is as follows:
GET /v2/
If a `200 OK` response is returned, the registry implements the V2(.1)
registry API and the client may proceed safely with other V2 operations.
Optionally, the response may contain information about the supported paths in
the response body. The client should be prepared to ignore this data.
If a `401 Unauthorized` response is returned, the client should take action
based on the contents of the "WWW-Authenticate" header and try the endpoint
again. Depending on access control setup, the client may still have to
authenticate against different resources, even if this check succeeds.
If `404 Not Found` response status, or other unexpected status, is returned,
the client should proceed with the assumption that the registry does not
implement V2 of the API.
### Pulling An Image
An "image" is a combination of a JSON manifest and individual layer files. The
process of pulling an image centers around retrieving these two components.
The first step in pulling an image is to retrieve the manifest. For reference,
the relevant manifest fields for the registry are the following:
field | description |
----------|------------------------------------------------|
name | The name of the image. |
tag | The tag for this version of the image. |
fsLayers | A list of layer descriptors (including tarsum) |
signature | A JWS used to verify the manifest content |
For more information about the manifest format, please see
[docker/docker#8093](https://github.com/docker/docker/issues/8093).
When the manifest is in hand, the client must verify the signature to ensure
the names and layers are valid. Once confirmed, the client will then use the
tarsums to download the individual layers. Layers are stored in as blobs in
the V2 registry API, keyed by their tarsum digest.
#### Pulling an Image Manifest
The image manifest can be fetched with the following url:
```
GET /v2/<name>/manifests/<reference>
```
The `name` and `reference` parameter identify the image and are required. The
reference may include a tag or digest.
A `404 Not Found` response will be returned if the image is unknown to the
registry. If the image exists and the response is successful, the image
manifest will be returned, with the following format (see docker/docker#8093
for details):
{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": <tarsum>
},
...
]
],
"history": <v1 images>,
"signature": <JWS>
}
The client should verify the returned manifest signature for authenticity
before fetching layers.
#### Pulling a Layer
Layers are stored in the blob portion of the registry, keyed by tarsum digest.
Pulling a layer is carried out by a standard http request. The URL is as
follows:
GET /v2/<name>/blobs/<tarsum>
Access to a layer will be gated by the `name` of the repository but is
identified uniquely in the registry by `tarsum`. The `tarsum` parameter is an
opaque field, to be interpreted by the tarsum library.
This endpoint may issue a 307 (302 for <HTTP 1.1) redirect to another service
for downloading the layer and clients should be prepared to handle redirects.
This endpoint should support aggressive HTTP caching for image layers. Support
for Etags, modification dates and other cache control headers should be
included. To allow for incremental downloads, `Range` requests should be
supported, as well.
### Pushing An Image
Pushing an image works in the opposite order as a pull. After assembling the
image manifest, the client must first push the individual layers. When the
layers are fully pushed into the registry, the client should upload the signed
manifest.
The details of each step of the process are covered in the following sections.
#### Pushing a Layer
All layer uploads use two steps to manage the upload process. The first step
starts the upload in the registry service, returning a url to carry out the
second step. The second step uses the upload url to transfer the actual data.
Uploads are started with a POST request which returns a url that can be used
to push data and check upload status.
The `Location` header will be used to communicate the upload location after
each request. While it won't change in the this specification, clients should
use the most recent value returned by the API.
##### Starting An Upload
To begin the process, a POST request should be issued in the following format:
```
POST /v2/<name>/blobs/uploads/
```
The parameters of this request are the image namespace under which the layer
will be linked. Responses to this request are covered below.
##### Existing Layers
The existence of a layer can be checked via a `HEAD` request to the blob store
API. The request should be formatted as follows:
```
HEAD /v2/<name>/blobs/<digest>
```
If the layer with the tarsum specified in `digest` is available, a 200 OK
response will be received, with no actual body content (this is according to
http specification). The response will look as follows:
```
200 OK
Content-Length: <length of blob>
Docker-Content-Digest: <digest>
```
When this response is received, the client can assume that the layer is
already available in the registry under the given name and should take no
further action to upload the layer. Note that the binary digests may differ
for the existing registry layer, but the tarsums will be guaranteed to match.
##### Uploading the Layer
If the POST request is successful, a `202 Accepted` response will be returned
with the upload URL in the `Location` header:
```
202 Accepted
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The rest of the upload process can be carried out with the returned url,
called the "Upload URL" from the `Location` header. All responses to the
upload url, whether sending data or getting status, will be in this format.
Though the URI format (`/v2/<name>/blobs/uploads/<uuid>`) for the `Location`
header is specified, clients should treat it as an opaque url and should never
try to assemble the it. While the `uuid` parameter may be an actual UUID, this
proposal imposes no constraints on the format and clients should never impose
any.
If clients need to correlate local upload state with remote upload state, the
contents of the `Docker-Upload-UUID` header should be used. Such an id can be
used to key the last used location header when implementing resumable uploads.
##### Upload Progress
The progress and chunk coordination of the upload process will be coordinated
through the `Range` header. While this is a non-standard use of the `Range`
header, there are examples of [similar approaches](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) in APIs with heavy use.
For an upload that just started, for an example with a 1000 byte layer file,
the `Range` header would be as follows:
```
Range: bytes=0-0
```
To get the status of an upload, issue a GET request to the upload URL:
```
GET /v2/<name>/blobs/uploads/<uuid>
Host: <registry host>
```
The response will be similar to the above, except will return 204 status:
```
204 No Content
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Docker-Upload-UUID: <uuid>
```
Note that the HTTP `Range` header byte ranges are inclusive and that will be
honored, even in non-standard use cases.
##### Monolithic Upload
A monolithic upload is simply a chunked upload with a single chunk and may be
favored by clients that would like to avoided the complexity of chunking. To
carry out a "monolithic" upload, one can simply put the entire content blob to
the provided URL:
```
PUT /v2/<name>/blobs/uploads/<uuid>?digest=<tarsum>[&digest=sha256:<hex digest>]
Content-Length: <size of layer>
Content-Type: application/octet-stream
<Layer Binary Data>
```
The "digest" parameter must be included with the PUT request. Please see the
_Completed Upload_ section for details on the parameters and expected
responses.
Additionally, the upload can be completed with a single `POST` request to
the uploads endpoint, including the "size" and "digest" parameters:
```
POST /v2/<name>/blobs/uploads/?digest=<tarsum>[&digest=sha256:<hex digest>]
Content-Length: <size of layer>
Content-Type: application/octet-stream
<Layer Binary Data>
```
On the registry service, this should allocate a download, accept and verify
the data and return the same response as the final chunk of an upload. If the
POST request fails collecting the data in any way, the registry should attempt
to return an error response to the client with the `Location` header providing
a place to continue the download.
The single `POST` method is provided for convenience and most clients should
implement `POST` + `PUT` to support reliable resume of uploads.
##### Chunked Upload
To carry out an upload of a chunk, the client can specify a range header and
only include that part of the layer file:
```
PATCH /v2/<name>/blobs/uploads/<uuid>
Content-Length: <size of chunk>
Content-Range: <start of range>-<end of range>
Content-Type: application/octet-stream
<Layer Chunk Binary Data>
```
There is no enforcement on layer chunk splits other than that the server must
receive them in order. The server may enforce a minimum chunk size. If the
server cannot accept the chunk, a `416 Requested Range Not Satisfiable`
response will be returned and will include a `Range` header indicating the
current status:
```
416 Requested Range Not Satisfiable
Location: /v2/<name>/blobs/uploads/<uuid>
Range: 0-<last valid range>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
If this response is received, the client should resume from the "last valid
range" and upload the subsequent chunk. A 416 will be returned under the
following conditions:
- Invalid Content-Range header format
- Out of order chunk: the range of the next chunk must start immediately after
the "last valid range" from the previous response.
When a chunk is accepted as part of the upload, a `202 Accepted` response will
be returned, including a `Range` header with the current upload status:
```
202 Accepted
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
##### Completed Upload
For an upload to be considered complete, the client must submit a `PUT`
request on the upload endpoint with a digest parameter. If it is not provided,
the upload will not be considered complete. The format for the final chunk
will be as follows:
```
PUT /v2/<name>/blob/uploads/<uuid>?digest=<tarsum>[&digest=sha256:<hex digest>]
Content-Length: <size of chunk>
Content-Range: <start of range>-<end of range>
Content-Type: application/octet-stream
<Last Layer Chunk Binary Data>
```
Optionally, if all chunks have already been uploaded, a `PUT` request with a
`digest` parameter and zero-length body may be sent to complete and validated
the upload. Multiple "digest" parameters may be provided with different
digests. The server may verify none or all of them but _must_ notify the
client if the content is rejected.
When the last chunk is received and the layer has been validated, the client
will receive a `201 Created` response:
```
201 Created
Location: /v2/<name>/blobs/<tarsum>
Content-Length: 0
Docker-Content-Digest: <digest>
```
The `Location` header will contain the registry URL to access the accepted
layer file. The `Docker-Content-Digest` header returns the canonical digest of
the uploaded blob which may differ from the provided digest. Most clients may
ignore the value but if it is used, the client should verify the value against
the uploaded blob data.
###### Digest Parameter
The "digest" parameter is designed as an opaque parameter to support
verification of a successful transfer. The initial version of the registry API
will support a tarsum digest, in the standard tarsum format. For example, a
HTTP URI parameter might be as follows:
```
tarsum.v1+sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b
```
Given this parameter, the registry will verify that the provided content does
result in this tarsum. Optionally, the registry can support other other digest
parameters for non-tarfile content stored as a layer. A regular hash digest
might be specified as follows:
```
sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b
```
Such a parameter would be used to verify that the binary content (as opposed
to the tar content) would be verified at the end of the upload process.
For the initial version, registry servers are only required to support the
tarsum format.
##### Canceling an Upload
An upload can be cancelled by issuing a DELETE request to the upload endpoint.
The format will be as follows:
```
DELETE /v2/<name>/blobs/uploads/<uuid>
```
After this request is issued, the upload uuid will no longer be valid and the
registry server will dump all intermediate data. While uploads will time out
if not completed, clients should issue this request if they encounter a fatal
error but still have the ability to issue an http request.
##### Errors
If an 502, 503 or 504 error is received, the client should assume that the
download can proceed due to a temporary condition, honoring the appropriate
retry mechanism. Other 5xx errors should be treated as terminal.
If there is a problem with the upload, a 4xx error will be returned indicating
the problem. After receiving a 4xx response (except 416, as called out above),
the upload will be considered failed and the client should take appropriate
action.
Note that the upload url will not be available forever. If the upload uuid is
unknown to the registry, a `404 Not Found` response will be returned and the
client must restart the upload process.
#### Pushing an Image Manifest
Once all of the layers for an image are uploaded, the client can upload the
image manifest. An image can be pushed using the following request format:
PUT /v2/<name>/manifests/<reference>
{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": <tarsum>
},
...
]
],
"history": <v1 images>,
"signature": <JWS>,
...
}
The `name` and `reference` fields of the response body must match those specified in
the URL. The `reference` field may be a "tag" or a "digest".
If there is a problem with pushing the manifest, a relevant 4xx response will
be returned with a JSON error message. Please see the _PUT Manifest section
for details on possible error codes that may be returned.
If one or more layers are unknown to the registry, `BLOB_UNKNOWN` errors are
returned. The `detail` field of the error response will have a `digest` field
identifying the missing blob, which will be a tarsum. An error is returned for
each unknown blob. The response format is as follows:
{
"errors:" [{
"code": "BLOB_UNKNOWN",
"message": "blob unknown to registry",
"detail": {
"digest": <tarsum>
}
},
...
]
}
#### Listing Image Tags
It may be necessary to list all of the tags under a given repository. The tags
for an image repository can be retrieved with the following request:
GET /v2/<name>/tags/list
The response will be in the following format:
200 OK
Content-Type: application/json
{
"name": <name>,
"tags": [
<tag>,
...
]
}
For repositories with a large number of tags, this response may be quite
large, so care should be taken by the client when parsing the response to
reduce copying.
### Deleting an Image
An image may be deleted from the registry via its `name` and `reference`. A
delete may be issued with the following request format:
DELETE /v2/<name>/manifests/<reference>
For deletes, `reference` *must* be a digest or the delete will fail. If the
image exists and has been successfully deleted, the following response will be
issued:
202 Accepted
Content-Length: None
If the image had already been deleted or did not exist, a `404 Not Found`
response will be issued instead.
## Detail
> **Note**: This section is still under construction. For the purposes of
> implementation, if any details below differ from the described request flows
> above, the section below should be corrected. When they match, this note
> should be removed.
The behavior of the endpoints are covered in detail in this section, organized
by route and entity. All aspects of the request and responses are covered,
including headers, parameters and body formats. Examples of requests and their
corresponding responses, with success and failure, are enumerated.
> **Note**: The sections on endpoint detail are arranged with an example
> request, a description of the request, followed by information about that
> request.
A list of methods and URIs are covered in the table below:
|Method|Path|Entity|Description|
-------|----|------|------------
{{range $route := .RouteDescriptors}}{{range $method := .Methods}}| {{$method.Method}} | `{{$route.Path|prettygorilla}}` | {{$route.Entity}} | {{$method.Description}} |
{{end}}{{end}}
The detail for each endpoint is covered in the following sections.
### Errors
The error codes encountered via the API are enumerated in the following table:
|Code|Message|Description|
-------|----|------|------------
{{range $err := .ErrorDescriptors}} `{{$err.Value}}` | {{$err.Message}} | {{$err.Description|removenewlines}}
{{end}}
{{range $route := .RouteDescriptors}}
### {{.Entity}}
{{.Description}}
{{range $method := $route.Methods}}
#### {{.Method}} {{$route.Entity}}
{{.Description}}
{{if .Requests}}{{range .Requests}}{{if .Name}}
##### {{.Name}}{{end}}
```
{{$method.Method}} {{$route.Path|prettygorilla}}{{if .QueryParameters}}?{{range .QueryParameters}}{{.Name}}={{.Format}}{{end}}{{end}}{{range .Headers}}
{{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}}
Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}}
{{.Body.Format}}{{end}}
```
{{.Description}}
{{if or .Headers .PathParameters .QueryParameters}}
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
{{range .Headers}}|`{{.Name}}`|header|{{.Description}}|
{{end}}{{range .PathParameters}}|`{{.Name}}`|path|{{.Description}}|
{{end}}{{range .QueryParameters}}|`{{.Name}}`|query|{{.Description}}|
{{end}}{{end}}
{{if .Successes}}
{{range .Successes}}
###### On Success: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}}
```
{{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}}
{{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}}
Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}}
{{.Body.Format}}{{end}}
```
{{.Description}}
{{if .Headers}}The following headers will be returned with the response:
|Name|Description|
|----|-----------|
{{range .Headers}}|`{{.Name}}`|{{.Description}}|
{{end}}{{end}}{{end}}{{end}}
{{if .Failures}}
{{range .Failures}}
###### On Failure: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}}
```
{{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}}
{{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}}
Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}}
{{.Body.Format}}{{end}}
```
{{.Description}}
{{if .Headers}}
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
{{range .Headers}}|`{{.Name}}`|{{.Description}}|
{{end}}{{end}}
{{if .ErrorCodes}}
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
-------|----|------|------------
{{range $err := .ErrorCodes}}| `{{$err}}` | {{$err.Descriptor.Message}} | {{$err.Descriptor.Description|removenewlines}} |
{{end}}
{{end}}{{end}}{{end}}{{end}}{{end}}{{end}}
{{end}}

413
docs/spec/auth/token.md Normal file
View file

@ -0,0 +1,413 @@
# Docker Registry v2 authentication via central service
Today a Docker Registry can run in standalone mode in which there are no
authorization checks. While adding your own HTTP authorization requirements in
a proxy placed between the client and the registry can give you greater access
control, we'd like a native authorization mechanism that's public key based
with access control lists managed separately with the ability to have fine
granularity in access control on a by-key, by-user, by-namespace, and
by-repository basis. In v1 this can be configured by specifying an
`index_endpoint` in the registry's config. Clients present tokens generated by
the index and tokens are validated on-line by the registry with every request.
This results in a complex authentication and authorization loop that occurs
with every registry operation. Some people are very familiar with this image:
![index auth](https://docs.docker.com/static_files/docker_pull_chart.png)
The above image outlines the 6-step process in accessing the Official Docker
Registry.
1. Contact the Docker Hub to know where I should download “samalba/busybox”
2. Docker Hub replies:
a. samalba/busybox is on Registry A
b. here are the checksums for samalba/busybox (for all layers)
c. token
3. Contact Registry A to receive the layers for samalba/busybox (all of them to
the base image). Registry A is authoritative for “samalba/busybox” but keeps
a copy of all inherited layers and serve them all from the same location.
4. Registry contacts Docker Hub to verify if token/user is allowed to download
images.
5. Docker Hub returns true/false lettings registry know if it should proceed or
error out.
6. Get the payload for all layers.
The goal of this document is to outline a way to eliminate steps 4 and 5 from
the above process by using cryptographically signed tokens and no longer
require the client to authenticate each request with a username and password
stored locally in plain text.
The new registry workflow is more like this:
![v2 registry auth](https://docs.google.com/drawings/d/1EHZU9uBLmcH0kytDClBv6jv6WR4xZjE8RKEUw1mARJA/pub?w=480&h=360)
1. Attempt to begin a push/pull operation with the registry.
2. If the registry requires authorization it will return a `401 Unauthorized`
HTTP response with information on how to authenticate.
3. The registry client makes a request to the authorization service for a
signed JSON Web Token.
4. The authorization service returns a token.
5. The client retries the original request with the token embedded in the
request header.
6. The Registry authorizes the client and begins the push/pull session as
usual.
## Requirements
- Registry Clients capable of generating key pairs which can be used to
authenticate to an authorization server.
- An authorization server capable of managing user accounts, their public keys,
and access controls to their resources hosted by any given service (such as
repositories in a Docker Registry).
- A Docker Registry capable of trusting the authorization server to sign tokens
which clients can use for authorization and the ability to verify these
tokens for single use or for use during a sufficiently short period of time.
## Authorization Server Endpoint Descriptions
This document borrows heavily from the [JSON Web Token Draft Spec](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32)
The described server is meant to serve as a user account and key manager and a
centralized access control list for resources hosted by other services which
wish to authenticate and manage authorizations using this services accounts and
their public keys.
Such a service could be used by the official docker registry to authenticate
clients and verify their authorization to docker image repositories.
Docker will need to be updated to interact with an authorization server to get
an authorization token.
## How to authenticate
Today, registry clients first contact the index to initiate a push or pull.
For v2, clients should contact the registry first. If the registry server
requires authentication it will return a `401 Unauthorized` response with a
`WWW-Authenticate` header detailing how to authenticate to this registry.
For example, say I (username `jlhawn`) am attempting to push an image to the
repository `samalba/my-app`. For the registry to authorize this, I either need
`push` access to the `samalba/my-app` repository or `push` access to the whole
`samalba` namespace in general. The registry will first return this response:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="https://auth.docker.com/v2/token/",service="registry.docker.com",scope="repository:samalba/my-app:push"
```
This format is documented in [Section 3 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-3)
The client will then know to make a `GET` request to the URL
`https://auth.docker.com/v2/token/` using the `service` and `scope` values from
the `WWW-Authenticate` header.
## Requesting a Token
#### Query Parameters
<dl>
<dt>
<code>service</code>
</dt>
<dd>
The name of the service which hosts the resource.
</dd>
<dt>
<code>scope</code>
</dt>
<dd>
The resource in question, formatted as one of the space-delimited
entries from the <code>scope</code> parameters from the <code>WWW-Authenticate</code> header
shown above. This query parameter should be specified multiple times if
there is more than one <code>scope</code> entry from the <code>WWW-Authenticate</code>
header. The above example would be specified as:
<code>scope=repository:samalba/my-app:push</code>.
</dd>
<dt>
<code>account</code>
</dt>
<dd>
The name of the account which the client is acting as. Optional if it
can be inferred from client authentication.
</dd>
</dl>
#### Description
Requests an authorization token for access to a specific resource hosted by a
specific service provider. Requires the client to authenticate either using a
TLS client certificate or using basic authentication (or any other kind of
digest/challenge/response authentication scheme if the client doesn't support
TLS client certs). If the key in the client certificate is linked to an account
then the token is issued for that account key. If the key in the certificate is
linked to multiple accounts then the client must specify the `account` query
parameter. The returned token is in JWT (JSON Web Token) format, signed using
the authorization server's private key.
#### Example
For this example, the client makes an HTTP request to the following endpoint
over TLS using a client certificate with the server being configured to allow a
non-verified issuer during the handshake (i.e., a self-signed client cert is
okay).
```
GET /v2/token/?service=registry.docker.com&scope=repository:samalba/my-app:push&account=jlhawn HTTP/1.1
Host: auth.docker.com
```
The server first inspects the client certificate to extract the subject key and
lookup which account it is associated with. The client is now authenticated
using that account.
The server next searches its access control list for the account's access to
the repository `samalba/my-app` hosted by the service `registry.docker.com`.
The server will now construct a JSON Web Token to sign and return. A JSON Web
Token has 3 main parts:
1. Headers
The header of a JSON Web Token is a standard JOSE header. The "typ" field
will be "JWT" and it will also contain the "alg" which identifies the
signing algorithm used to produce the signature. It will also usually have
a "kid" field, the ID of the key which was used to sign the token.
Here is an example JOSE Header for a JSON Web Token (formatted with
whitespace for readability):
```
{
"typ": "JWT",
"alg": "ES256",
"kid": "PYYO:TEWU:V7JH:26JV:AQTZ:LJC3:SXVJ:XGHA:34F2:2LAQ:ZRMK:Z7Q6"
}
```
It specifies that this object is going to be a JSON Web token signed using
the key with the given ID using the Elliptic Curve signature algorithm
using a SHA256 hash.
2. Claim Set
The Claim Set is a JSON struct containing these standard registered claim
name fields:
<dl>
<dt>
<code>iss</code> (Issuer)
</dt>
<dd>
The issuer of the token, typically the fqdn of the authorization
server.
</dd>
<dt>
<code>sub</code> (Subject)
</dt>
<dd>
The subject of the token; the id of the client which requested it.
</dd>
<dt>
<code>aud</code> (Audience)
</dt>
<dd>
The intended audience of the token; the id of the service which
will verify the token to authorize the client/subject.
</dd>
<dt>
<code>exp</code> (Expiration)
</dt>
<dd>
The token should only be considered valid up to this specified date
and time.
</dd>
<dt>
<code>nbf</code> (Not Before)
</dt>
<dd>
The token should not be considered valid before this specified date
and time.
</dd>
<dt>
<code>iat</code> (Issued At)
</dt>
<dd>
Specifies the date and time which the Authorization server
generated this token.
</dd>
<dt>
<code>jti</code> (JWT ID)
</dt>
<dd>
A unique identifier for this token. Can be used by the intended
audience to prevent replays of the token.
</dd>
</dl>
The Claim Set will also contain a private claim name unique to this
authorization server specification:
<dl>
<dt>
<code>access</code>
</dt>
<dd>
An array of access entry objects with the following fields:
<dl>
<dt>
<code>type</code>
</dt>
<dd>
The type of resource hosted by the service.
</dd>
<dt>
<code>name</code>
</dt>
<dd>
The name of the recource of the given type hosted by the
service.
</dd>
<dt>
<code>actions</code>
</dt>
<dd>
An array of strings which give the actions authorized on
this resource.
</dd>
</dl>
</dd>
</dl>
Here is an example of such a JWT Claim Set (formatted with whitespace for
readability):
```
{
"iss": "auth.docker.com",
"sub": "jlhawn",
"aud": "registry.docker.com",
"exp": 1415387315,
"nbf": 1415387015,
"iat": 1415387015,
"jti": "tYJCO1c6cnyy7kAn0c7rKPgbV1H1bFws",
"access": [
{
"type": "repository",
"name": "samalba/my-app",
"actions": [
"push"
]
}
]
}
```
3. Signature
The authorization server will produce a JOSE header and Claim Set with no
extraneous whitespace, i.e., the JOSE Header from above would be
```
{"typ":"JWT","alg":"ES256","kid":"PYYO:TEWU:V7JH:26JV:AQTZ:LJC3:SXVJ:XGHA:34F2:2LAQ:ZRMK:Z7Q6"}
```
and the Claim Set from above would be
```
{"iss":"auth.docker.com","sub":"jlhawn","aud":"registry.docker.com","exp":1415387315,"nbf":1415387015,"iat":1415387015,"jti":"tYJCO1c6cnyy7kAn0c7rKPgbV1H1bFws","access":[{"type":"repository","name":"samalba/my-app","actions":["push"]}]}
```
The utf-8 representation of this JOSE header and Claim Set are then
url-safe base64 encoded (sans trailing '=' buffer), producing:
```
eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IlBZWU86VEVXVTpWN0pIOjI2SlY6QVFUWjpMSkMzOlNYVko6WEdIQTozNEYyOjJMQVE6WlJNSzpaN1E2In0
```
for the JOSE Header and
```
eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJqbGhhd24iLCJhdWQiOiJyZWdpc3RyeS5kb2NrZXIuY29tIiwiZXhwIjoxNDE1Mzg3MzE1LCJuYmYiOjE0MTUzODcwMTUsImlhdCI6MTQxNTM4NzAxNSwianRpIjoidFlKQ08xYzZjbnl5N2tBbjBjN3JLUGdiVjFIMWJGd3MiLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InNhbWFsYmEvbXktYXBwIiwiYWN0aW9ucyI6WyJwdXNoIl19XX0
```
for the Claim Set. These two are concatenated using a '.' character,
yielding the string:
```
eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IlBZWU86VEVXVTpWN0pIOjI2SlY6QVFUWjpMSkMzOlNYVko6WEdIQTozNEYyOjJMQVE6WlJNSzpaN1E2In0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJqbGhhd24iLCJhdWQiOiJyZWdpc3RyeS5kb2NrZXIuY29tIiwiZXhwIjoxNDE1Mzg3MzE1LCJuYmYiOjE0MTUzODcwMTUsImlhdCI6MTQxNTM4NzAxNSwianRpIjoidFlKQ08xYzZjbnl5N2tBbjBjN3JLUGdiVjFIMWJGd3MiLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InNhbWFsYmEvbXktYXBwIiwiYWN0aW9ucyI6WyJwdXNoIl19XX0
```
This is then used as the payload to a the `ES256` signature algorithm
specified in the JOSE header and specified fully in [Section 3.4 of the JSON Web Algorithms (JWA)
draft specification](https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-38#section-3.4)
This example signature will use the following ECDSA key for the server:
```
{
"kty": "EC",
"crv": "P-256",
"kid": "PYYO:TEWU:V7JH:26JV:AQTZ:LJC3:SXVJ:XGHA:34F2:2LAQ:ZRMK:Z7Q6",
"d": "R7OnbfMaD5J2jl7GeE8ESo7CnHSBm_1N2k9IXYFrKJA",
"x": "m7zUpx3b-zmVE5cymSs64POG9QcyEpJaYCD82-549_Q",
"y": "dU3biz8sZ_8GPB-odm8Wxz3lNDr1xcAQQPQaOcr1fmc"
}
```
A resulting signature of the above payload using this key is:
```
QhflHPfbd6eVF4lM9bwYpFZIV0PfikbyXuLx959ykRTBpe3CYnzs6YBK8FToVb5R47920PVLrh8zuLzdCr9t3w
```
Concatenating all of these together with a `.` character gives the
resulting JWT:
```
eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IlBZWU86VEVXVTpWN0pIOjI2SlY6QVFUWjpMSkMzOlNYVko6WEdIQTozNEYyOjJMQVE6WlJNSzpaN1E2In0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJqbGhhd24iLCJhdWQiOiJyZWdpc3RyeS5kb2NrZXIuY29tIiwiZXhwIjoxNDE1Mzg3MzE1LCJuYmYiOjE0MTUzODcwMTUsImlhdCI6MTQxNTM4NzAxNSwianRpIjoidFlKQ08xYzZjbnl5N2tBbjBjN3JLUGdiVjFIMWJGd3MiLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InNhbWFsYmEvbXktYXBwIiwiYWN0aW9ucyI6WyJwdXNoIl19XX0.QhflHPfbd6eVF4lM9bwYpFZIV0PfikbyXuLx959ykRTBpe3CYnzs6YBK8FToVb5R47920PVLrh8zuLzdCr9t3w
```
This can now be placed in an HTTP response and returned to the client to use to
authenticate to the audience service:
```
HTTP/1.1 200 OK
Content-Type: application/json
{"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IlBZWU86VEVXVTpWN0pIOjI2SlY6QVFUWjpMSkMzOlNYVko6WEdIQTozNEYyOjJMQVE6WlJNSzpaN1E2In0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJqbGhhd24iLCJhdWQiOiJyZWdpc3RyeS5kb2NrZXIuY29tIiwiZXhwIjoxNDE1Mzg3MzE1LCJuYmYiOjE0MTUzODcwMTUsImlhdCI6MTQxNTM4NzAxNSwianRpIjoidFlKQ08xYzZjbnl5N2tBbjBjN3JLUGdiVjFIMWJGd3MiLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InNhbWFsYmEvbXktYXBwIiwiYWN0aW9ucyI6WyJwdXNoIl19XX0.QhflHPfbd6eVF4lM9bwYpFZIV0PfikbyXuLx959ykRTBpe3CYnzs6YBK8FToVb5R47920PVLrh8zuLzdCr9t3w"}
```
## Using the signed token
Once the client has a token, it will try the registry request again with the
token placed in the HTTP `Authorization` header like so:
```
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IkJWM0Q6MkFWWjpVQjVaOktJQVA6SU5QTDo1RU42Ok40SjQ6Nk1XTzpEUktFOkJWUUs6M0ZKTDpQT1RMIn0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJCQ0NZOk9VNlo6UUVKNTpXTjJDOjJBVkM6WTdZRDpBM0xZOjQ1VVc6NE9HRDpLQUxMOkNOSjU6NUlVTCIsImF1ZCI6InJlZ2lzdHJ5LmRvY2tlci5jb20iLCJleHAiOjE0MTUzODczMTUsIm5iZiI6MTQxNTM4NzAxNSwiaWF0IjoxNDE1Mzg3MDE1LCJqdGkiOiJ0WUpDTzFjNmNueXk3a0FuMGM3cktQZ2JWMUgxYkZ3cyIsInNjb3BlIjoiamxoYXduOnJlcG9zaXRvcnk6c2FtYWxiYS9teS1hcHA6cHVzaCxwdWxsIGpsaGF3bjpuYW1lc3BhY2U6c2FtYWxiYTpwdWxsIn0.Y3zZSwaZPqy4y9oRBVRImZyv3m_S9XDHF1tWwN7mL52C_IiA73SJkWVNsvNqpJIn5h7A2F8biv_S2ppQ1lgkbw
```
This is also described in [Section 2.1 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-2.1)
## Verifying the token
The registry must now verify the token presented by the user by inspecting the
claim set within. The registry will:
- Ensure that the issuer (`iss` claim) is an authority it trusts.
- Ensure that the registry identifies as the audience (`aud` claim).
- Check that the current time is between the `nbf` and `exp` claim times.
- If enforcing single-use tokens, check that the JWT ID (`jti` claim) value has
not been seen before.
- To enforce this, the registry may keep a record of `jti`s it has seen for
up to the `exp` time of the token to prevent token replays.
- Check the `access` claim value and use the identified resources and the list
of actions authorized to determine whether the token grants the required
level of access for the operation the client is attempting to perform.
- Verify that the signature of the token is valid.
At no point in this process should the registry need to <em>call back</em> to
the authorization server. If anything, it would only need to update a list of
trusted public keys for verifying token signatures or use a separate API
(still to be spec'd) to add/update resource records on the authorization
server.

77
docs/spec/json.md Normal file
View file

@ -0,0 +1,77 @@
# Docker Distribution JSON Canonicalization
## Introduction
To provide consistent content hashing of JSON objects throughout Docker
Distribution APIs, a canonical JSON format has been defined. Adopting such a
canonicalization also aids in caching JSON responses.
## Rules
Compliant JSON should conform to the following rules:
1. All generated JSON should comply with [RFC
7159](http://www.ietf.org/rfc/rfc7159.txt).
2. Resulting "JSON text" shall always be encoded in UTF-8.
3. Unless a canonical key order is defined for a particular schema, object
keys shall always appear in lexically sorted order.
4. All whitespace between tokens should be removed.
5. No "trailing commas" are allowed in object or array definitions.
## Examples
The following is a simple example of a canonicalized JSON string:
```json
{"asdf":1,"qwer":[],"zxcv":[{},true,1000000000,"tyui"]}
```
## Reference
### Other Canonicalizations
The OLPC project specifies [Canonical
JSON](http://wiki.laptop.org/go/Canonical_JSON). While this is used in
[TUF](http://theupdateframework.com/), which may be used with other
distribution-related protocols, this alternative format has been proposed in
case the original source changes. Specifications complying with either this
specification or an alternative should explicitly call out the
canonicalization format. Except for key ordering, this specification is mostly
compatible.
### Go
In Go, the [`encoding/json`](http://golang.org/pkg/encoding/json/) library
will emit canonical JSON by default. Simply using `json.Marshal` will suffice
in most cases:
```go
incoming := map[string]interface{}{
"asdf": 1,
"qwer": []interface{}{},
"zxcv": []interface{}{
map[string]interface{}{},
true,
int(1e9),
"tyui",
},
}
canonical, err := json.Marshal(incoming)
if err != nil {
// ... handle error
}
```
To apply canonical JSON format spacing to an existing serialized JSON buffer, one
can use
[`json.Indent`](http://golang.org/src/encoding/json/indent.go?s=1918:1989#L65)
with the following arguments:
```go
incoming := getBytes()
var canonical bytes.Buffer
if err := json.Indent(&canonical, incoming, "", ""); err != nil {
// ... handle error
}
```

17
docs/storagedriver/azure.md Normal file
View file

@ -0,0 +1,17 @@
# Docker Registry Microsoft Azure Blob Storage Driver
An implementation of the `storagedriver.StorageDriver` interface which uses [Microsoft Azure Blob Storage][azure-blob-storage] for object storage.
## Parameters
The following parameters must be used to authenticate and configure the storage driver (case-sensitive):
* `accountname`: Name of the Azure Storage Account.
* `accountkey`: Primary or Secondary Key for the Storage Account.
* `container`: Name of the root storage container in which all registry data will be stored. Must comply the storage container name [requirements][create-container-api].
* `realm`: (optional) Domain name suffix for the Storage Service API endpoint. Defaults to `core.windows.net`. For example realm for "Azure in China" would be `core.chinacloudapi.cn` and realm for "Azure Government" would be `core.usgovcloudapi.net`.
[azure-blob-storage]: http://azure.microsoft.com/en-us/services/storage/
[create-container-api]: https://msdn.microsoft.com/en-us/library/azure/dd179468.aspx

8
docs/storagedriver/filesystem.md Normal file
View file

@ -0,0 +1,8 @@
Docker-Registry Filesystem Storage Driver
=========================================
An implementation of the `storagedriver.StorageDriver` interface which uses the local filesystem.
## Parameters
`rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to `/tmp/registry/storage`.

10
docs/storagedriver/inmemory.md Normal file
View file

@ -0,0 +1,10 @@
Docker-Registry In-Memory Storage Driver
=========================================
An implementation of the `storagedriver.StorageDriver` interface which uses local memory for object storage.
**IMPORTANT**: This storage driver *does not* persist data across runs, and primarily exists for testing.
## Parameters
None

26
docs/storagedriver/s3.md Normal file
View file

@ -0,0 +1,26 @@
Docker-Registry S3 Storage Driver
=========================================
An implementation of the `storagedriver.StorageDriver` interface which uses Amazon S3 for object storage.
## Parameters
`accesskey`: Your aws access key.
`secretkey`: Your aws secret key.
**Note** You can provide empty strings for your access and secret keys if you plan on running the driver on an ec2 instance and will handle authentication with the instance's credentials.
`region`: The name of the aws region in which you would like to store objects (for example `us-east-1`). For a list of regions, you can look at http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
`bucket`: The name of your s3 bucket where you wish to store objects (needs to already be created prior to driver initialization).
`encrypt`: (optional) Whether you would like your data encrypted on the server side (defaults to false if not specified).
`secure`: (optional) Whether you would like to transfer data to the bucket over ssl or not. Defaults to true (meaning transfering over ssl) if not specified. Note that while setting this to false will improve performance, it is not recommended due to security concerns.
`v4auth`: (optional) Whether you would like to use aws signature version 4 with your requests. This defaults to true if not specified (note that the eu-central-1 region does not work with version 2 signatures, so the driver will error out if initialized with this region and v4auth set to false)
`chunksize`: (optional) The default part size for multipart uploads (performed by WriteStream) to s3. The default is 10 MB. Keep in mind that the minimum part size for s3 is 5MB. You might experience better performance for larger chunk sizes depending on the speed of your connection to s3.
`rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to the empty string (bucket root).

50
docs/storagedrivers.md Normal file
View file

@ -0,0 +1,50 @@
Docker-Registry Storage Driver
==============================
This document describes the registry storage driver model, implementation, and explains how to contribute new storage drivers.
Provided Drivers
================
This storage driver package comes bundled with several drivers:
- [inmemory](storagedriver/inmemory.md): A temporary storage driver using a local inmemory map. This exists solely for reference and testing.
- [filesystem](storagedriver/filesystem.md): A local storage driver configured to use a directory tree in the local filesystem.
- [s3](storagedriver/s3.md): A driver storing objects in an Amazon Simple Storage Solution (S3) bucket.
- [azure](storagedriver/azure.md): A driver storing objects in [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/).
Storage Driver API
==================
The storage driver API is designed to model a filesystem-like key/value storage in a manner abstract enough to support a range of drivers from the local filesystem to Amazon S3 or other distributed object storage systems.
Storage drivers are required to implement the `storagedriver.StorageDriver` interface provided in `storagedriver.go`, which includes methods for reading, writing, and deleting content, as well as listing child objects of a specified prefix key.
Storage drivers are intended (but not required) to be written in go, providing compile-time validation of the `storagedriver.StorageDriver` interface, although an IPC driver wrapper means that it is not required for drivers to be included in the compiled registry. The `storagedriver/ipc` package provides a client/server protocol for running storage drivers provided in external executables as a managed child server process.
Driver Selection and Configuration
==================================
The preferred method of selecting a storage driver is using the `StorageDriverFactory` interface in the `storagedriver/factory` package. These factories provide a common interface for constructing storage drivers with a parameters map. The factory model is based off of the [Register](http://golang.org/pkg/database/sql/#Register) and [Open](http://golang.org/pkg/database/sql/#Open) methods in the builtin [database/sql](http://golang.org/pkg/database/sql) package.
Storage driver factories may be registered by name using the `factory.Register` method, and then later invoked by calling `factory.Create` with a driver name and parameters map. If no driver is registered with the given name, this factory will attempt to find an executable storage driver with the executable name "registry-storage-\<driver name\>" and return an IPC storage driver wrapper managing the driver subprocess. If no such storage driver can be found, `factory.Create` will return an `InvalidStorageDriverError`.
Driver Contribution
===================
## Writing new storage drivers
To create a valid storage driver, one must implement the `storagedriver.StorageDriver` interface and make sure to expose this driver via the factory system and as a distributable IPC server executable.
### In-process drivers
Storage drivers should call `factory.Register` with their driver name in an `init` method, allowing callers of `factory.New` to construct instances of this driver without requiring modification of imports throughout the codebase.
### Out-of-process drivers
As many users will run the registry as a pre-constructed docker container, storage drivers should also be distributable as IPC server executables. Drivers written in go should model the main method provided in `storagedriver/filesystem/registry-storage-filesystem/filesystem.go`. Parameters to IPC drivers will be provided as a JSON-serialized map in the first argument to the process. These parameters should be validated and then a blocking call to `ipc.StorageDriverServer` should be made with a new storage driver.
Out-of-process drivers must also implement the `ipc.IPCStorageDriver` interface, which exposes a `Version` check for the storage driver. This is used to validate storage driver api compatibility at driver load-time.
## Testing
Storage driver test suites are provided in `storagedriver/testsuites/testsuites.go` and may be used for any storage driver written in go. Two methods are provided for registering test suites, `RegisterInProcessSuite` and `RegisterIPCSuite`, which run the same set of tests for the driver imported or managed over IPC respectively.
## Drivers written in other languages
Although storage drivers are strongly recommended to be written in go for consistency, compile-time validation, and support, the IPC framework allows for a level of language-agnosticism. Non-go drivers must implement the storage driver protocol by mimicing StorageDriverServer in `storagedriver/ipc/server.go`. As the IPC framework is a layer on top of [docker/libchan](https://github.com/docker/libchan), this currently limits language support to Java via [ndeloof/chan](https://github.com/ndeloof/jchan) and Javascript via [GraftJS/jschan](https://github.com/GraftJS/jschan), although contributions to the libchan project are welcome.