+
+
+ 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](LICENSE).
diff --git a/vendor/github.com/docker/distribution/RELEASE-CHECKLIST.md b/vendor/github.com/docker/distribution/RELEASE-CHECKLIST.md
new file mode 100644
index 0000000000..73eba5a871
--- /dev/null
+++ b/vendor/github.com/docker/distribution/RELEASE-CHECKLIST.md
@@ -0,0 +1,44 @@
+## Registry Release Checklist
+
+10. Compile release notes detailing features and since the last release.
+
+ Update the `CHANGELOG.md` file and create a PR to master with the updates.
+Once that PR has been approved by maintainers the change may be cherry-picked
+to the release branch (new release branches may be forked from this commit).
+
+20. Update the version file: `https://github.com/docker/distribution/blob/master/version/version.go`
+
+30. Update the `MAINTAINERS` (if necessary), `AUTHORS` and `.mailmap` files.
+
+```
+make AUTHORS
+```
+
+40. Create a signed tag.
+
+ Distribution uses semantic versioning. Tags are of the format
+`vx.y.z[-rcn]`. You will need PGP installed and a PGP key which has been added
+to your Github account. The comment for the tag should include the release
+notes, use previous tags as a guide for formatting consistently. Run
+`git tag -s vx.y.z[-rcn]` to create tag and `git -v vx.y.z[-rcn]` to verify tag,
+check comment and correct commit hash.
+
+50. Push the signed tag
+
+60. Create a new [release](https://github.com/docker/distribution/releases). In the case of a release candidate, tick the `pre-release` checkbox.
+
+70. Update the registry binary in [distribution library image repo](https://github.com/docker/distribution-library-image) by running the update script and opening a pull request.
+
+80. Update the official image. Add the new version in the [official images repo](https://github.com/docker-library/official-images) by appending a new version to the `registry/registry` file with the git hash pointed to by the signed tag. Update the major version to point to the latest version and the minor version to point to new patch release if necessary.
+e.g. to release `2.3.1`
+
+ `2.3.1 (new)`
+
+ `2.3.0 -> 2.3.0` can be removed
+
+ `2 -> 2.3.1`
+
+ `2.3 -> 2.3.1`
+
+90. Build a new distribution/registry image on [Docker hub](https://hub.docker.com/u/distribution/dashboard) by adding a new automated build with the new tag and re-building the images.
+
diff --git a/vendor/github.com/docker/distribution/ROADMAP.md b/vendor/github.com/docker/distribution/ROADMAP.md
new file mode 100644
index 0000000000..701127afec
--- /dev/null
+++ b/vendor/github.com/docker/distribution/ROADMAP.md
@@ -0,0 +1,267 @@
+# Roadmap
+
+The Distribution Project consists of several components, some of which are
+still being defined. This document defines the high-level goals of the
+project, identifies the current components, and defines the release-
+relationship to the Docker Platform.
+
+* [Distribution Goals](#distribution-goals)
+* [Distribution Components](#distribution-components)
+* [Project Planning](#project-planning): release-relationship to the Docker Platform.
+
+This road map is a living document, providing an overview of the goals and
+considerations made in respect of the future of the project.
+
+## Distribution Goals
+
+- Replace the existing [docker registry](github.com/docker/docker-registry)
+ implementation as the primary implementation.
+- Replace the existing push and pull code in the docker engine with the
+ distribution package.
+- Define a strong data model for distributing docker images
+- Provide a flexible distribution tool kit for use in the docker platform
+- Unlock new distribution models
+
+## Distribution Components
+
+Components of the Distribution Project are managed via github [milestones](https://github.com/docker/distribution/milestones). Upcoming
+features and bugfixes for a component will be added to the relevant milestone. If a feature or
+bugfix is not part of a milestone, it is currently unscheduled for
+implementation.
+
+* [Registry](#registry)
+* [Distribution Package](#distribution-package)
+
+***
+
+### Registry
+
+The new Docker registry is the main portion of the distribution repository.
+Registry 2.0 is the first release of the next-generation registry. This was
+primarily focused on implementing the [new registry
+API](https://github.com/docker/distribution/blob/master/docs/spec/api.md),
+with a focus on security and performance.
+
+Following from the Distribution project goals above, we have a set of goals
+for registry v2 that we would like to follow in the design. New features
+should be compared against these goals.
+
+#### Data Storage and Distribution First
+
+The registry's first goal is to provide a reliable, consistent storage
+location for Docker images. The registry should only provide the minimal
+amount of indexing required to fetch image data and no more.
+
+This means we should be selective in new features and API additions, including
+those that may require expensive, ever growing indexes. Requests should be
+servable in "constant time".
+
+#### Content Addressability
+
+All data objects used in the registry API should be content addressable.
+Content identifiers should be secure and verifiable. This provides a secure,
+reliable base from which to build more advanced content distribution systems.
+
+#### Content Agnostic
+
+In the past, changes to the image format would require large changes in Docker
+and the Registry. By decoupling the distribution and image format, we can
+allow the formats to progress without having to coordinate between the two.
+This means that we should be focused on decoupling Docker from the registry
+just as much as decoupling the registry from Docker. Such an approach will
+allow us to unlock new distribution models that haven't been possible before.
+
+We can take this further by saying that the new registry should be content
+agnostic. The registry provides a model of names, tags, manifests and content
+addresses and that model can be used to work with content.
+
+#### Simplicity
+
+The new registry should be closer to a microservice component than its
+predecessor. This means it should have a narrower API and a low number of
+service dependencies. It should be easy to deploy.
+
+This means that other solutions should be explored before changing the API or
+adding extra dependencies. If functionality is required, can it be added as an
+extension or companion service.
+
+#### Extensibility
+
+The registry should provide extension points to add functionality. By keeping
+the scope narrow, but providing the ability to add functionality.
+
+Features like search, indexing, synchronization and registry explorers fall
+into this category. No such feature should be added unless we've found it
+impossible to do through an extension.
+
+#### Active Feature Discussions
+
+The following are feature discussions that are currently active.
+
+If you don't see your favorite, unimplemented feature, feel free to contact us
+via IRC or the mailing list and we can talk about adding it. The goal here is
+to make sure that new features go through a rigid design process before
+landing in the registry.
+
+##### Proxying to other Registries
+
+A _pull-through caching_ mode exists for the registry, but is restricted from
+within the docker client to only mirror the official Docker Hub. This functionality
+can be expanded when image provenance has been specified and implemented in the
+distribution project.
+
+##### Metadata storage
+
+Metadata for the registry is currently stored with the manifest and layer data on
+the storage backend. While this is a big win for simplicity and reliably maintaining
+state, it comes with the cost of consistency and high latency. The mutable registry
+metadata operations should be abstracted behind an API which will allow ACID compliant
+storage systems to handle metadata.
+
+##### Peer to Peer transfer
+
+Discussion has started here: https://docs.google.com/document/d/1rYDpSpJiQWmCQy8Cuiaa3NH-Co33oK_SC9HeXYo87QA/edit
+
+##### Indexing, Search and Discovery
+
+The original registry provided some implementation of search for use with
+private registries. Support has been elided from V2 since we'd like to both
+decouple search functionality from the registry. The makes the registry
+simpler to deploy, especially in use cases where search is not needed, and
+let's us decouple the image format from the registry.
+
+There are explorations into using the catalog API and notification system to
+build external indexes. The current line of thought is that we will define a
+common search API to index and query docker images. Such a system could be run
+as a companion to a registry or set of registries to power discovery.
+
+The main issue with search and discovery is that there are so many ways to
+accomplish it. There are two aspects to this project. The first is deciding on
+how it will be done, including an API definition that can work with changing
+data formats. The second is the process of integrating with `docker search`.
+We expect that someone attempts to address the problem with the existing tools
+and propose it as a standard search API or uses it to inform a standardization
+process. Once this has been explored, we integrate with the docker client.
+
+Please see the following for more detail:
+
+- https://github.com/docker/distribution/issues/206
+
+##### Deletes
+
+> __NOTE:__ Deletes are a much asked for feature. Before requesting this
+feature or participating in discussion, we ask that you read this section in
+full and understand the problems behind deletes.
+
+While, at first glance, implementing deleting seems simple, there are a number
+mitigating factors that make many solutions not ideal or even pathological in
+the context of a registry. The following paragraph discuss the background and
+approaches that could be applied to arrive at a solution.
+
+The goal of deletes in any system is to remove unused or unneeded data. Only
+data requested for deletion should be removed and no other data. Removing
+unintended data is worse than _not_ removing data that was requested for
+removal but ideally, both are supported. Generally, according to this rule, we
+err on holding data longer than needed, ensuring that it is only removed when
+we can be certain that it can be removed. With the current behavior, we opt to
+hold onto the data forever, ensuring that data cannot be incorrectly removed.
+
+To understand the problems with implementing deletes, one must understand the
+data model. All registry data is stored in a filesystem layout, implemented on
+a "storage driver", effectively a _virtual file system_ (VFS). The storage
+system must assume that this VFS layer will be eventually consistent and has
+poor read- after-write consistency, since this is the lower common denominator
+among the storage drivers. This is mitigated by writing values in reverse-
+dependent order, but makes wider transactional operations unsafe.
+
+Layered on the VFS model is a content-addressable _directed, acyclic graph_
+(DAG) made up of blobs. Manifests reference layers. Tags reference manifests.
+Since the same data can be referenced by multiple manifests, we only store
+data once, even if it is in different repositories. Thus, we have a set of
+blobs, referenced by tags and manifests. If we want to delete a blob we need
+to be certain that it is no longer referenced by another manifest or tag. When
+we delete a manifest, we also can try to delete the referenced blobs. Deciding
+whether or not a blob has an active reference is the crux of the problem.
+
+Conceptually, deleting a manifest and its resources is quite simple. Just find
+all the manifests, enumerate the referenced blobs and delete the blobs not in
+that set. An astute observer will recognize this as a garbage collection
+problem. As with garbage collection in programming languages, this is very
+simple when one always has a consistent view. When one adds parallelism and an
+inconsistent view of data, it becomes very challenging.
+
+A simple example can demonstrate this. Let's say we are deleting a manifest
+_A_ in one process. We scan the manifest and decide that all the blobs are
+ready for deletion. Concurrently, we have another process accepting a new
+manifest _B_ referencing one or more blobs from the manifest _A_. Manifest _B_
+is accepted and all the blobs are considered present, so the operation
+proceeds. The original process then deletes the referenced blobs, assuming
+they were unreferenced. The manifest _B_, which we thought had all of its data
+present, can no longer be served by the registry, since the dependent data has
+been deleted.
+
+Deleting data from the registry safely requires some way to coordinate this
+operation. The following approaches are being considered:
+
+- _Reference Counting_ - Maintain a count of references to each blob. This is
+ challenging for a number of reasons: 1. maintaining a consistent consensus
+ of reference counts across a set of Registries and 2. Building the initial
+ list of reference counts for an existing registry. These challenges can be
+ met with a consensus protocol like Paxos or Raft in the first case and a
+ necessary but simple scan in the second..
+- _Lock the World GC_ - Halt all writes to the data store. Walk the data store
+ and find all blob references. Delete all unreferenced blobs. This approach
+ is very simple but requires disabling writes for a period of time while the
+ service reads all data. This is slow and expensive but very accurate and
+ effective.
+- _Generational GC_ - Do something similar to above but instead of blocking
+ writes, writes are sent to another storage backend while reads are broadcast
+ to the new and old backends. GC is then performed on the read-only portion.
+ Because writes land in the new backend, the data in the read-only section
+ can be safely deleted. The main drawbacks of this approach are complexity
+ and coordination.
+- _Centralized Oracle_ - Using a centralized, transactional database, we can
+ know exactly which data is referenced at any given time. This avoids
+ coordination problem by managing this data in a single location. We trade
+ off metadata scalability for simplicity and performance. This is a very good
+ option for most registry deployments. This would create a bottleneck for
+ registry metadata. However, metadata is generally not the main bottleneck
+ when serving images.
+
+Please let us know if other solutions exist that we have yet to enumerate.
+Note that for any approach, implementation is a massive consideration. For
+example, a mark-sweep based solution may seem simple but the amount of work in
+coordination offset the extra work it might take to build a _Centralized
+Oracle_. We'll accept proposals for any solution but please coordinate with us
+before dropping code.
+
+At this time, we have traded off simplicity and ease of deployment for disk
+space. Simplicity and ease of deployment tend to reduce developer involvement,
+which is currently the most expensive resource in software engineering. Taking
+on any solution for deletes will greatly effect these factors, trading off
+very cheap disk space for a complex deployment and operational story.
+
+Please see the following issues for more detail:
+
+- https://github.com/docker/distribution/issues/422
+- https://github.com/docker/distribution/issues/461
+- https://github.com/docker/distribution/issues/462
+
+### Distribution Package
+
+At its core, the Distribution Project is a set of Go packages that make up
+Distribution Components. At this time, most of these packages make up the
+Registry implementation.
+
+The package itself is considered unstable. If you're using it, please take care to vendor the dependent version.
+
+For feature additions, please see the Registry section. In the future, we may break out a
+separate Roadmap for distribution-specific features that apply to more than
+just the registry.
+
+***
+
+### Project Planning
+
+An [Open-Source Planning Process](https://github.com/docker/distribution/wiki/Open-Source-Planning-Process) is used to define the Roadmap. [Project Pages](https://github.com/docker/distribution/wiki) define the goals for each Milestone and identify current progress.
+
diff --git a/vendor/github.com/docker/distribution/circle.yml b/vendor/github.com/docker/distribution/circle.yml
new file mode 100644
index 0000000000..085ef4f73c
--- /dev/null
+++ b/vendor/github.com/docker/distribution/circle.yml
@@ -0,0 +1,94 @@
+# Pony-up!
+machine:
+ pre:
+ # Install gvm
+ - bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/1.0.22/binscripts/gvm-installer)
+ # Install codecov for coverage
+ - pip install --user codecov
+
+ post:
+ # go
+ - gvm install go1.10 --prefer-binary --name=stable
+
+ environment:
+ # Convenient shortcuts to "common" locations
+ CHECKOUT: /home/ubuntu/$CIRCLE_PROJECT_REPONAME
+ BASE_DIR: src/github.com/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
+ # Trick circle brainflat "no absolute path" behavior
+ BASE_STABLE: ../../../$HOME/.gvm/pkgsets/stable/global/$BASE_DIR
+ DOCKER_BUILDTAGS: "include_oss include_gcs"
+ # Workaround Circle parsing dumb bugs and/or YAML wonkyness
+ CIRCLE_PAIN: "mode: set"
+
+ hosts:
+ # Not used yet
+ fancy: 127.0.0.1
+
+dependencies:
+ pre:
+ # Copy the code to the gopath of all go versions
+ - >
+ gvm use stable &&
+ mkdir -p "$(dirname $BASE_STABLE)" &&
+ cp -R "$CHECKOUT" "$BASE_STABLE"
+
+ override:
+ # Install dependencies for every copied clone/go version
+ - gvm use stable && go get github.com/lk4d4/vndr:
+ pwd: $BASE_STABLE
+
+ post:
+ # For the stable go version, additionally install linting tools
+ - >
+ gvm use stable &&
+ go get github.com/axw/gocov/gocov github.com/golang/lint/golint
+
+test:
+ pre:
+ # Output the go versions we are going to test
+ # - gvm use old && go version
+ - gvm use stable && go version
+
+ # Ensure validation of dependencies
+ - git fetch origin:
+ pwd: $BASE_STABLE
+ - gvm use stable && if test -n "`git diff --stat=1000 origin/master | grep -E \"^[[:space:]]*vendor\"`"; then make dep-validate; fi:
+ pwd: $BASE_STABLE
+
+ # First thing: build everything. This will catch compile errors, and it's
+ # also necessary for go vet to work properly (see #807).
+ - gvm use stable && go install $(go list ./... | grep -v "/vendor/"):
+ pwd: $BASE_STABLE
+
+ # FMT
+ - gvm use stable && make fmt:
+ pwd: $BASE_STABLE
+
+ # VET
+ - gvm use stable && make vet:
+ pwd: $BASE_STABLE
+
+ # LINT
+ - gvm use stable && make lint:
+ pwd: $BASE_STABLE
+
+ override:
+ # Test stable, and report
+ - gvm use stable; export ROOT_PACKAGE=$(go list .); go list -tags "$DOCKER_BUILDTAGS" ./... | grep -v "/vendor/" | xargs -L 1 -I{} bash -c 'export PACKAGE={}; go test -tags "$DOCKER_BUILDTAGS" -test.short -coverprofile=$GOPATH/src/$PACKAGE/coverage.out -coverpkg=$(./coverpkg.sh $PACKAGE $ROOT_PACKAGE) $PACKAGE':
+ timeout: 1000
+ pwd: $BASE_STABLE
+
+ # Test stable with race
+ - gvm use stable; export ROOT_PACKAGE=$(go list .); go list -tags "$DOCKER_BUILDTAGS" ./... | grep -v "/vendor/" | grep -v "registry/handlers" | grep -v "registry/storage/driver" | xargs -L 1 -I{} bash -c 'export PACKAGE={}; go test -race -tags "$DOCKER_BUILDTAGS" -test.short $PACKAGE':
+ timeout: 1000
+ pwd: $BASE_STABLE
+ post:
+ # Report to codecov
+ - bash <(curl -s https://codecov.io/bash):
+ pwd: $BASE_STABLE
+
+ ## Notes
+ # Do we want these as well?
+ # - go get code.google.com/p/go.tools/cmd/goimports
+ # - test -z "$(goimports -l -w ./... | tee /dev/stderr)"
+ # http://labix.org/gocheck
diff --git a/vendor/github.com/docker/distribution/coverpkg.sh b/vendor/github.com/docker/distribution/coverpkg.sh
new file mode 100644
index 0000000000..25d419ae82
--- /dev/null
+++ b/vendor/github.com/docker/distribution/coverpkg.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Given a subpackage and the containing package, figures out which packages
+# need to be passed to `go test -coverpkg`: this includes all of the
+# subpackage's dependencies within the containing package, as well as the
+# subpackage itself.
+DEPENDENCIES="$(go list -f $'{{range $f := .Deps}}{{$f}}\n{{end}}' ${1} | grep ${2} | grep -v github.com/docker/distribution/vendor)"
+echo "${1} ${DEPENDENCIES}" | xargs echo -n | tr ' ' ','
diff --git a/vendor/github.com/docker/distribution/vendor.conf b/vendor/github.com/docker/distribution/vendor.conf
new file mode 100644
index 0000000000..df06259ebb
--- /dev/null
+++ b/vendor/github.com/docker/distribution/vendor.conf
@@ -0,0 +1,52 @@
+github.com/Azure/azure-sdk-for-go 4650843026a7fdec254a8d9cf893693a254edd0b
+github.com/Azure/go-autorest eaa7994b2278094c904d31993d26f56324db3052
+github.com/sirupsen/logrus 3d4380f53a34dcdc95f0c1db702615992b38d9a4
+github.com/aws/aws-sdk-go 5bcc0a238d880469f949fc7cd24e35f32ab80cbd
+github.com/bshuster-repo/logrus-logstash-hook d2c0ecc1836d91814e15e23bb5dc309c3ef51f4a
+github.com/beorn7/perks 4c0e84591b9aa9e6dcfdf3e020114cd81f89d5f9
+github.com/bugsnag/bugsnag-go b1d153021fcd90ca3f080db36bec96dc690fb274
+github.com/bugsnag/osext 0dd3f918b21bec95ace9dc86c7e70266cfc5c702
+github.com/bugsnag/panicwrap e2c28503fcd0675329da73bf48b33404db873782
+github.com/denverdino/aliyungo afedced274aa9a7fcdd47ac97018f0f8db4e5de2
+github.com/dgrijalva/jwt-go a601269ab70c205d26370c16f7c81e9017c14e04
+github.com/docker/go-metrics 399ea8c73916000c64c2c76e8da00ca82f8387ab
+github.com/docker/goamz f0a21f5b2e12f83a505ecf79b633bb2035cf6f85
+github.com/docker/libtrust fa567046d9b14f6aa788882a950d69651d230b21
+github.com/garyburd/redigo 535138d7bcd717d6531c701ef5933d98b1866257
+github.com/go-ini/ini 2ba15ac2dc9cdf88c110ec2dc0ced7fa45f5678c
+github.com/golang/protobuf 8d92cf5fc15a4382f8964b08e1f42a75c0591aa3
+github.com/gorilla/handlers 60c7bfde3e33c201519a200a4507a158cc03a17b
+github.com/gorilla/mux 599cba5e7b6137d46ddf58fb1765f5d928e69604
+github.com/inconshreveable/mousetrap 76626ae9c91c4f2a10f34cad8ce83ea42c93bb75
+github.com/jmespath/go-jmespath bd40a432e4c76585ef6b72d3fd96fb9b6dc7b68d
+github.com/marstr/guid 8bd9a64bf37eb297b492a4101fb28e80ac0b290f
+github.com/satori/go.uuid f58768cc1a7a7e77a3bd49e98cdd21419399b6a3
+github.com/matttproud/golang_protobuf_extensions c12348ce28de40eed0136aa2b644d0ee0650e56c
+github.com/miekg/dns 271c58e0c14f552178ea321a545ff9af38930f39
+github.com/mitchellh/mapstructure 482a9fd5fa83e8c4e7817413b80f3eb8feec03ef
+github.com/ncw/swift b964f2ca856aac39885e258ad25aec08d5f64ee6
+github.com/prometheus/client_golang c332b6f63c0658a65eca15c0e5247ded801cf564
+github.com/prometheus/client_model 99fa1f4be8e564e8a6b613da7fa6f46c9edafc6c
+github.com/prometheus/common 89604d197083d4781071d3c65855d24ecfb0a563
+github.com/prometheus/procfs cb4147076ac75738c9a7d279075a253c0cc5acbd
+github.com/spf13/cobra 312092086bed4968099259622145a0c9ae280064
+github.com/spf13/pflag 5644820622454e71517561946e3d94b9f9db6842
+github.com/stevvooe/resumable 2aaf90b2ceea5072cb503ef2a620b08ff3119870
+github.com/xenolf/lego a9d8cec0e6563575e5868a005359ac97911b5985
+github.com/yvasiyarov/go-metrics 57bccd1ccd43f94bb17fdd8bf3007059b802f85e
+github.com/yvasiyarov/gorelic a9bba5b9ab508a086f9a12b8c51fab68478e2128
+github.com/yvasiyarov/newrelic_platform_go b21fdbd4370f3717f3bbd2bf41c223bc273068e6
+golang.org/x/crypto c10c31b5e94b6f7a0283272dc2bb27163dcea24b
+golang.org/x/net 4876518f9e71663000c348837735820161a42df7
+golang.org/x/oauth2 045497edb6234273d67dbc25da3f2ddbc4c4cacf
+golang.org/x/time a4bde12657593d5e90d0533a3e4fd95e635124cb
+google.golang.org/api 9bf6e6e569ff057f75d9604a46c52928f17d2b54
+google.golang.org/appengine 12d5545dc1cfa6047a286d5e853841b6471f4c19
+google.golang.org/cloud 975617b05ea8a58727e6c1a06b6161ff4185a9f2
+google.golang.org/grpc d3ddb4469d5a1b949fc7a7da7c1d6a0d1b6de994
+gopkg.in/check.v1 64131543e7896d5bcc6bd5a76287eb75ea96c673
+gopkg.in/square/go-jose.v1 40d457b439244b546f023d056628e5184136899b
+gopkg.in/yaml.v2 bef53efd0c76e49e6de55ead051f886bea7e9420
+rsc.io/letsencrypt e770c10b0f1a64775ae91d240407ce00d1a5bdeb https://github.com/dmcgowan/letsencrypt.git
+github.com/opencontainers/go-digest a6d0ee40d4207ea02364bd3b9e8e77b9159ba1eb
+github.com/opencontainers/image-spec ab7389ef9f50030c9b245bc16b981c7ddf192882
diff --git a/vendor/github.com/docker/docker/api/README.md b/vendor/github.com/docker/docker/api/README.md
new file mode 100644
index 0000000000..f136c3433a
--- /dev/null
+++ b/vendor/github.com/docker/docker/api/README.md
@@ -0,0 +1,42 @@
+# Working on the Engine API
+
+The Engine API is an HTTP API used by the command-line client to communicate with the daemon. It can also be used by third-party software to control the daemon.
+
+It consists of various components in this repository:
+
+- `api/swagger.yaml` A Swagger definition of the API.
+- `api/types/` Types shared by both the client and server, representing various objects, options, responses, etc. Most are written manually, but some are automatically generated from the Swagger definition. See [#27919](https://github.com/docker/docker/issues/27919) for progress on this.
+- `cli/` The command-line client.
+- `client/` The Go client used by the command-line client. It can also be used by third-party Go programs.
+- `daemon/` The daemon, which serves the API.
+
+## Swagger definition
+
+The API is defined by the [Swagger](http://swagger.io/specification/) definition in `api/swagger.yaml`. This definition can be used to:
+
+1. Automatically generate documentation.
+2. Automatically generate the Go server and client. (A work-in-progress.)
+3. Provide a machine readable version of the API for introspecting what it can do, automatically generating clients for other languages, etc.
+
+## Updating the API documentation
+
+The API documentation is generated entirely from `api/swagger.yaml`. If you make updates to the API, edit this file to represent the change in the documentation.
+
+The file is split into two main sections:
+
+- `definitions`, which defines re-usable objects used in requests and responses
+- `paths`, which defines the API endpoints (and some inline objects which don't need to be reusable)
+
+To make an edit, first look for the endpoint you want to edit under `paths`, then make the required edits. Endpoints may reference reusable objects with `$ref`, which can be found in the `definitions` section.
+
+There is hopefully enough example material in the file for you to copy a similar pattern from elsewhere in the file (e.g. adding new fields or endpoints), but for the full reference, see the [Swagger specification](https://github.com/docker/docker/issues/27919).
+
+`swagger.yaml` is validated by `hack/validate/swagger` to ensure it is a valid Swagger definition. This is useful when making edits to ensure you are doing the right thing.
+
+## Viewing the API documentation
+
+When you make edits to `swagger.yaml`, you may want to check the generated API documentation to ensure it renders correctly.
+
+Run `make swagger-docs` and a preview will be running at `http://localhost`. Some of the styling may be incorrect, but you'll be able to ensure that it is generating the correct documentation.
+
+The production documentation is generated by vendoring `swagger.yaml` into [docker/docker.github.io](https://github.com/docker/docker.github.io).
diff --git a/vendor/github.com/docker/docker/api/swagger-gen.yaml b/vendor/github.com/docker/docker/api/swagger-gen.yaml
new file mode 100644
index 0000000000..f07a02737f
--- /dev/null
+++ b/vendor/github.com/docker/docker/api/swagger-gen.yaml
@@ -0,0 +1,12 @@
+
+layout:
+ models:
+ - name: definition
+ source: asset:model
+ target: "{{ joinFilePath .Target .ModelPackage }}"
+ file_name: "{{ (snakize (pascalize .Name)) }}.go"
+ operations:
+ - name: handler
+ source: asset:serverOperation
+ target: "{{ joinFilePath .Target .APIPackage .Package }}"
+ file_name: "{{ (snakize (pascalize .Name)) }}.go"
diff --git a/vendor/github.com/docker/docker/api/swagger.yaml b/vendor/github.com/docker/docker/api/swagger.yaml
new file mode 100644
index 0000000000..af3bd6d484
--- /dev/null
+++ b/vendor/github.com/docker/docker/api/swagger.yaml
@@ -0,0 +1,10122 @@
+# A Swagger 2.0 (a.k.a. OpenAPI) definition of the Engine API.
+#
+# This is used for generating API documentation and the types used by the
+# client/server. See api/README.md for more information.
+#
+# Some style notes:
+# - This file is used by ReDoc, which allows GitHub Flavored Markdown in
+# descriptions.
+# - There is no maximum line length, for ease of editing and pretty diffs.
+# - operationIds are in the format "NounVerb", with a singular noun.
+
+swagger: "2.0"
+schemes:
+ - "http"
+ - "https"
+produces:
+ - "application/json"
+ - "text/plain"
+consumes:
+ - "application/json"
+ - "text/plain"
+basePath: "/v1.38"
+info:
+ title: "Docker Engine API"
+ version: "1.38"
+ x-logo:
+ url: "https://docs.docker.com/images/logo-docker-main.png"
+ description: |
+ The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.
+
+ Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.
+
+ # Errors
+
+ The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:
+
+ ```
+ {
+ "message": "page not found"
+ }
+ ```
+
+ # Versioning
+
+ The API is usually changed in each release, so API calls are versioned to
+ ensure that clients don't break. To lock to a specific version of the API,
+ you prefix the URL with its version, for example, call `/v1.30/info` to use
+ the v1.30 version of the `/info` endpoint. If the API version specified in
+ the URL is not supported by the daemon, a HTTP `400 Bad Request` error message
+ is returned.
+
+ If you omit the version-prefix, the current version of the API (v1.38) is used.
+ For example, calling `/info` is the same as calling `/v1.38/info`. Using the
+ API without a version-prefix is deprecated and will be removed in a future release.
+
+ Engine releases in the near future should support this version of the API,
+ so your client will continue to work even if it is talking to a newer Engine.
+
+ The API uses an open schema model, which means server may add extra properties
+ to responses. Likewise, the server will ignore any extra query parameters and
+ request body properties. When you write clients, you need to ignore additional
+ properties in responses to ensure they do not break when talking to newer
+ daemons.
+
+
+ # Authentication
+
+ Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a Base64 encoded (JSON) string with the following structure:
+
+ ```
+ {
+ "username": "string",
+ "password": "string",
+ "email": "string",
+ "serveraddress": "string"
+ }
+ ```
+
+ The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.
+
+ If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:
+
+ ```
+ {
+ "identitytoken": "9cbaf023786cd7..."
+ }
+ ```
+
+# The tags on paths define the menu sections in the ReDoc documentation, so
+# the usage of tags must make sense for that:
+# - They should be singular, not plural.
+# - There should not be too many tags, or the menu becomes unwieldy. For
+# example, it is preferable to add a path to the "System" tag instead of
+# creating a tag with a single path in it.
+# - The order of tags in this list defines the order in the menu.
+tags:
+ # Primary objects
+ - name: "Container"
+ x-displayName: "Containers"
+ description: |
+ Create and manage containers.
+ - name: "Image"
+ x-displayName: "Images"
+ - name: "Network"
+ x-displayName: "Networks"
+ description: |
+ Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
+ - name: "Volume"
+ x-displayName: "Volumes"
+ description: |
+ Create and manage persistent storage that can be attached to containers.
+ - name: "Exec"
+ x-displayName: "Exec"
+ description: |
+ Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.
+
+ To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.
+ # Swarm things
+ - name: "Swarm"
+ x-displayName: "Swarm"
+ description: |
+ Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
+ - name: "Node"
+ x-displayName: "Nodes"
+ description: |
+ Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
+ - name: "Service"
+ x-displayName: "Services"
+ description: |
+ Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
+ - name: "Task"
+ x-displayName: "Tasks"
+ description: |
+ A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.
+ - name: "Secret"
+ x-displayName: "Secrets"
+ description: |
+ Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
+ - name: "Config"
+ x-displayName: "Configs"
+ description: |
+ Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
+ # System things
+ - name: "Plugin"
+ x-displayName: "Plugins"
+ - name: "System"
+ x-displayName: "System"
+
+definitions:
+ Port:
+ type: "object"
+ description: "An open port on a container"
+ required: [PrivatePort, Type]
+ properties:
+ IP:
+ type: "string"
+ format: "ip-address"
+ description: "Host IP address that the container's port is mapped to"
+ PrivatePort:
+ type: "integer"
+ format: "uint16"
+ x-nullable: false
+ description: "Port on the container"
+ PublicPort:
+ type: "integer"
+ format: "uint16"
+ description: "Port exposed on the host"
+ Type:
+ type: "string"
+ x-nullable: false
+ enum: ["tcp", "udp", "sctp"]
+ example:
+ PrivatePort: 8080
+ PublicPort: 80
+ Type: "tcp"
+
+ MountPoint:
+ type: "object"
+ description: "A mount point inside a container"
+ properties:
+ Type:
+ type: "string"
+ Name:
+ type: "string"
+ Source:
+ type: "string"
+ Destination:
+ type: "string"
+ Driver:
+ type: "string"
+ Mode:
+ type: "string"
+ RW:
+ type: "boolean"
+ Propagation:
+ type: "string"
+
+ DeviceMapping:
+ type: "object"
+ description: "A device mapping between the host and container"
+ properties:
+ PathOnHost:
+ type: "string"
+ PathInContainer:
+ type: "string"
+ CgroupPermissions:
+ type: "string"
+ example:
+ PathOnHost: "/dev/deviceName"
+ PathInContainer: "/dev/deviceName"
+ CgroupPermissions: "mrw"
+
+ ThrottleDevice:
+ type: "object"
+ properties:
+ Path:
+ description: "Device path"
+ type: "string"
+ Rate:
+ description: "Rate"
+ type: "integer"
+ format: "int64"
+ minimum: 0
+
+ Mount:
+ type: "object"
+ properties:
+ Target:
+ description: "Container path."
+ type: "string"
+ Source:
+ description: "Mount source (e.g. a volume name, a host path)."
+ type: "string"
+ Type:
+ description: |
+ The mount type. Available types:
+
+ - `bind` Mounts a file or directory from the host into the container. Must exist prior to creating the container.
+ - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed.
+ - `tmpfs` Create a tmpfs with the given options. The mount source cannot be specified for tmpfs.
+ type: "string"
+ enum:
+ - "bind"
+ - "volume"
+ - "tmpfs"
+ ReadOnly:
+ description: "Whether the mount should be read-only."
+ type: "boolean"
+ Consistency:
+ description: "The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`."
+ type: "string"
+ BindOptions:
+ description: "Optional configuration for the `bind` type."
+ type: "object"
+ properties:
+ Propagation:
+ description: "A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`."
+ type: "string"
+ enum:
+ - "private"
+ - "rprivate"
+ - "shared"
+ - "rshared"
+ - "slave"
+ - "rslave"
+ VolumeOptions:
+ description: "Optional configuration for the `volume` type."
+ type: "object"
+ properties:
+ NoCopy:
+ description: "Populate volume with data from the target."
+ type: "boolean"
+ default: false
+ Labels:
+ description: "User-defined key/value metadata."
+ type: "object"
+ additionalProperties:
+ type: "string"
+ DriverConfig:
+ description: "Map of driver specific options"
+ type: "object"
+ properties:
+ Name:
+ description: "Name of the driver to use to create the volume."
+ type: "string"
+ Options:
+ description: "key/value map of driver specific options."
+ type: "object"
+ additionalProperties:
+ type: "string"
+ TmpfsOptions:
+ description: "Optional configuration for the `tmpfs` type."
+ type: "object"
+ properties:
+ SizeBytes:
+ description: "The size for the tmpfs mount in bytes."
+ type: "integer"
+ format: "int64"
+ Mode:
+ description: "The permission mode for the tmpfs mount in an integer."
+ type: "integer"
+
+ RestartPolicy:
+ description: |
+ The behavior to apply when the container exits. The default is not to restart.
+
+ An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.
+ type: "object"
+ properties:
+ Name:
+ type: "string"
+ description: |
+ - Empty string means not to restart
+ - `always` Always restart
+ - `unless-stopped` Restart always except when the user has manually stopped the container
+ - `on-failure` Restart only when the container exit code is non-zero
+ enum:
+ - ""
+ - "always"
+ - "unless-stopped"
+ - "on-failure"
+ MaximumRetryCount:
+ type: "integer"
+ description: "If `on-failure` is used, the number of times to retry before giving up"
+
+ Resources:
+ description: "A container's resources (cgroups config, ulimits, etc)"
+ type: "object"
+ properties:
+ # Applicable to all platforms
+ CpuShares:
+ description: "An integer value representing this container's relative CPU weight versus other containers."
+ type: "integer"
+ Memory:
+ description: "Memory limit in bytes."
+ type: "integer"
+ format: "int64"
+ default: 0
+ # Applicable to UNIX platforms
+ CgroupParent:
+ description: "Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist."
+ type: "string"
+ BlkioWeight:
+ description: "Block IO weight (relative weight)."
+ type: "integer"
+ minimum: 0
+ maximum: 1000
+ BlkioWeightDevice:
+ description: |
+ Block IO weight (relative device weight) in the form `[{"Path": "device_path", "Weight": weight}]`.
+ type: "array"
+ items:
+ type: "object"
+ properties:
+ Path:
+ type: "string"
+ Weight:
+ type: "integer"
+ minimum: 0
+ BlkioDeviceReadBps:
+ description: |
+ Limit read rate (bytes per second) from a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
+ type: "array"
+ items:
+ $ref: "#/definitions/ThrottleDevice"
+ BlkioDeviceWriteBps:
+ description: |
+ Limit write rate (bytes per second) to a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
+ type: "array"
+ items:
+ $ref: "#/definitions/ThrottleDevice"
+ BlkioDeviceReadIOps:
+ description: |
+ Limit read rate (IO per second) from a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
+ type: "array"
+ items:
+ $ref: "#/definitions/ThrottleDevice"
+ BlkioDeviceWriteIOps:
+ description: |
+ Limit write rate (IO per second) to a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
+ type: "array"
+ items:
+ $ref: "#/definitions/ThrottleDevice"
+ CpuPeriod:
+ description: "The length of a CPU period in microseconds."
+ type: "integer"
+ format: "int64"
+ CpuQuota:
+ description: "Microseconds of CPU time that the container can get in a CPU period."
+ type: "integer"
+ format: "int64"
+ CpuRealtimePeriod:
+ description: "The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks."
+ type: "integer"
+ format: "int64"
+ CpuRealtimeRuntime:
+ description: "The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks."
+ type: "integer"
+ format: "int64"
+ CpusetCpus:
+ description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)"
+ type: "string"
+ example: "0-3"
+ CpusetMems:
+ description: "Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems."
+ type: "string"
+ Devices:
+ description: "A list of devices to add to the container."
+ type: "array"
+ items:
+ $ref: "#/definitions/DeviceMapping"
+ DeviceCgroupRules:
+ description: "a list of cgroup rules to apply to the container"
+ type: "array"
+ items:
+ type: "string"
+ example: "c 13:* rwm"
+ DiskQuota:
+ description: "Disk limit (in bytes)."
+ type: "integer"
+ format: "int64"
+ KernelMemory:
+ description: "Kernel memory limit in bytes."
+ type: "integer"
+ format: "int64"
+ MemoryReservation:
+ description: "Memory soft limit in bytes."
+ type: "integer"
+ format: "int64"
+ MemorySwap:
+ description: "Total memory limit (memory + swap). Set as `-1` to enable unlimited swap."
+ type: "integer"
+ format: "int64"
+ MemorySwappiness:
+ description: "Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100."
+ type: "integer"
+ format: "int64"
+ minimum: 0
+ maximum: 100
+ NanoCPUs:
+ description: "CPU quota in units of 10