From b911020c1f93704e5a7ff0d25258b1c3d8e2f547 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 12 Oct 2023 09:32:37 +0200 Subject: [PATCH] docs: fix markup and broken links Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/content/_index.md | 30 +- docs/content/about/_index.md | 6 +- docs/content/about/architecture.md | 2 +- docs/content/about/compatibility.md | 6 +- docs/content/about/configuration.md | 87 +- docs/content/about/deploying.md | 315 ++--- docs/content/about/garbage-collection.md | 6 +- docs/content/about/glossary.md | 2 +- docs/content/about/help.md | 2 - docs/content/about/insecure.md | 110 +- docs/content/about/notifications.md | 6 +- docs/content/recipes/_index.md | 12 +- docs/content/recipes/apache.md | 28 +- docs/content/recipes/mirror.md | 9 +- docs/content/recipes/nginx.md | 200 +-- docs/content/recipes/osx-setup-guide.md | 54 +- docs/content/recipes/systemd.md | 15 +- docs/content/spec/_index.md | 8 +- docs/content/spec/api.md | 1088 ++++------------- docs/content/spec/api.md.tmpl | 2 +- docs/content/spec/auth/_index.md | 8 +- docs/content/spec/auth/oauth.md | 6 +- docs/content/spec/auth/scope.md | 23 +- docs/content/spec/auth/token.md | 4 +- docs/content/spec/deprecated-schema-v1.md | 10 +- docs/content/spec/implementations.md | 2 +- docs/content/spec/json.md | 2 +- docs/content/spec/manifest-v2-2.md | 16 +- docs/content/spec/menu.md | 7 - docs/content/storage-drivers/_index.md | 25 +- docs/content/storage-drivers/gcs.md | 5 +- docs/content/storage-drivers/inmemory.md | 6 +- docs/content/storage-drivers/s3.md | 16 +- docs/hugo.yaml | 2 +- .../images/notifications.gliffy | 0 .../images/notifications.png | Bin .../images/notifications.svg | 0 .../images/v2-registry-auth.png | Bin 38 files changed, 783 insertions(+), 1337 deletions(-) delete mode 100644 docs/content/spec/menu.md rename docs/{content => static}/images/notifications.gliffy (100%) rename docs/{content => static}/images/notifications.png (100%) rename docs/{content => static}/images/notifications.svg (100%) rename docs/{content => static}/images/v2-registry-auth.png (100%) diff --git a/docs/content/_index.md b/docs/content/_index.md index 1162f2d3..367ac6ad 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -1,8 +1,6 @@ --- description: High-level overview of the Registry keywords: registry, on-prem, images, tags, repository, distribution -redirect_from: -- /registry/overview/ title: Docker Registry --- @@ -35,29 +33,41 @@ The Registry is compatible with Docker engine **version 1.6.0 or higher**. Start your registry - docker run -d -p 5000:5000 --name registry registry:2 +```sh +docker run -d -p 5000:5000 --name registry registry:2 +``` Pull (or build) some image from the hub - docker pull ubuntu +```sh +docker pull ubuntu +``` Tag the image so that it points to your registry - docker image tag ubuntu localhost:5000/myfirstimage +```sh +docker image tag ubuntu localhost:5000/myfirstimage +``` Push it - docker push localhost:5000/myfirstimage +```sh +docker push localhost:5000/myfirstimage +``` Pull it back - docker pull localhost:5000/myfirstimage +```sh +docker pull localhost:5000/myfirstimage +``` Now stop your registry and remove all data - docker container stop registry && docker container rm -v registry +```sh +docker container stop registry && docker container rm -v registry +``` ## Next -You should now read the [detailed introduction about the registry](./about/_index.md), -or jump directly to [deployment instructions](./about/deploying.md). +You should now read the [detailed introduction about the registry](about), +or jump directly to [deployment instructions](about/deploying). diff --git a/docs/content/about/_index.md b/docs/content/about/_index.md index 6fd5aa15..80bc4d4f 100644 --- a/docs/content/about/_index.md +++ b/docs/content/about/_index.md @@ -27,7 +27,7 @@ The Registry GitHub repository includes additional information about advanced authentication and authorization methods. Only very large or public deployments are expected to extend the Registry in this way. -Finally, the Registry ships with a robust [notification system](notifications.md), +Finally, the Registry ships with a robust [notification system](notifications), calling webhooks in response to activity, and both extensive logging and reporting, mostly useful for large installations that want to collect metrics. @@ -39,7 +39,7 @@ Image names as used in typical docker commands reflect their origin: * `docker pull myregistrydomain:port/foo/bar` instructs docker to contact the registry located at `myregistrydomain:port` to find the image `foo/bar` You can find out more about the various Docker commands dealing with images in -the [official Docker engine documentation](../engine/reference/commandline/cli.md). +the [official Docker engine documentation](https://docs.docker.com/engine/reference/commandline/cli/). ## Use cases @@ -70,4 +70,4 @@ golang are certainly useful as well for advanced operations or hacking. ## Next -Dive into [deploying your registry](deploying.md) +Dive into [deploying your registry](deploying) diff --git a/docs/content/about/architecture.md b/docs/content/about/architecture.md index c2aaa9f2..91b704f8 100644 --- a/docs/content/about/architecture.md +++ b/docs/content/about/architecture.md @@ -1,5 +1,5 @@ --- -published: false +draft: true --- # Architecture diff --git a/docs/content/about/compatibility.md b/docs/content/about/compatibility.md index 6462b557..d12845b8 100644 --- a/docs/content/about/compatibility.md +++ b/docs/content/about/compatibility.md @@ -5,13 +5,14 @@ title: Registry compatibility --- ## Synopsis + If a manifest is pulled by _digest_ from a registry 2.3 with Docker Engine 1.9 and older, and the manifest was pushed with Docker Engine 1.10, a security check causes the Engine to receive a manifest it cannot use and the pull fails. ## Registry manifest support -Historically, the registry has supported a [single manifest type](./spec/manifest-v2-1.md) +Historically, the registry has supported a single manifest type known as _Schema 1_. With the move toward multiple architecture images, the distribution project @@ -23,7 +24,6 @@ preserve compatibility with older versions of Docker Engine. This conversion has some implications for pulling manifests by digest and this document enumerates these implications. - ## Content Addressable Storage (CAS) Manifests are stored and retrieved in the registry by keying off a digest @@ -42,7 +42,6 @@ attempts to send a _Schema 2_ manifest, falling back to sending a Schema 1 type manifest when it detects that the registry does not support the new version. - ## Registry v2.3 ### Manifest push with Docker 1.10 @@ -75,4 +74,3 @@ registry persists to disk. When the manifest is pulled by digest or tag with any Docker version, a _Schema 1_ manifest is returned. - diff --git a/docs/content/about/configuration.md b/docs/content/about/configuration.md index 52edfa4a..6c759e13 100644 --- a/docs/content/about/configuration.md +++ b/docs/content/about/configuration.md @@ -20,7 +20,7 @@ To override a configuration option, create an environment variable named and the `_` (underscore) represents indention levels. For example, you can configure the `rootdirectory` of the `filesystem` storage backend: -```none +```yaml storage: filesystem: rootdirectory: /var/lib/registry @@ -28,7 +28,7 @@ storage: To override this value, set an environment variable like this: -```none +```sh REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere ``` @@ -64,7 +64,7 @@ These are all configuration options for the registry. Some options in the list are mutually exclusive. Read the detailed reference information about each option before finalizing your configuration. -```none +```yaml version: 0.1 log: accesslog: @@ -293,7 +293,7 @@ the children marked **required**. ## `version` -```none +```yaml version: 0.1 ``` @@ -307,7 +307,7 @@ The `log` subsection configures the behavior of the logging system. The logging system outputs everything to stderr. You can adjust the granularity and format with this configuration section. -```none +```yaml log: accesslog: disabled: true @@ -326,7 +326,7 @@ log: ### `accesslog` -```none +```yaml accesslog: disabled: true ``` @@ -338,7 +338,7 @@ Access logging can be disabled by setting the boolean flag `disabled` to `true`. ## `hooks` -```none +```yaml hooks: - type: mail levels: @@ -362,7 +362,7 @@ Refer to `loglevel` to configure the level of messages printed. > **DEPRECATED:** Please use [log](#log) instead. -```none +```yaml loglevel: debug ``` @@ -371,7 +371,7 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is ## `storage` -```none +```yaml storage: filesystem: rootdirectory: /var/lib/registry @@ -436,15 +436,15 @@ returns an error. You can choose any of these backend storage drivers: | Storage driver | Description | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md). | -| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). | -| `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/gcs.md). | -| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/s3.md). | +| `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](/storage-drivers/filesystem). | +| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](/storage-drivers/azure). | +| `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](/storage-drivers/gcs). | +| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](/storage-drivers/s3). | For testing only, you can use the [`inmemory` storage -driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/inmemory.md). +driver](/storage-drivers/inmemory). If you would like to run a registry from volatile memory, use the -[`filesystem` driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md) +[`filesystem` driver](/storage-drivers/filesystem) on a ramdisk. If you are deploying a registry on Windows, a Windows volume mounted from the @@ -453,7 +453,7 @@ data-store. If you do use a Windows volume, the length of the `PATH` to the mount point must be within the `MAX_PATH` limits (typically 255 characters), or this error will occur: -```none +```text mkdir /XXX protocol error and your registry will not function properly. ``` @@ -496,7 +496,7 @@ Use the `delete` structure to enable the deletion of image blobs and manifests by digest. It defaults to false, but it can be enabled by writing the following on the configuration file: -```none +```yaml delete: enabled: true ``` @@ -531,14 +531,14 @@ instance is aggressively caching. To disable redirects, add a single flag `disable`, set to `true` under the `redirect` section: -```none +```yaml redirect: disable: true ``` ## `auth` -```none +```yaml auth: silly: realm: silly-realm @@ -593,7 +593,7 @@ security. For more information about Token based authentication configuration, see the -[specification](spec/auth/token.md). +[specification](/spec/auth/token). ### `htpasswd` @@ -601,7 +601,7 @@ The _htpasswd_ authentication backed allows you to configure basic authentication using an [Apache htpasswd file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html). The only supported password format is -[`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt). Entries with other hash types +[`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt). Entries with other hash types are ignored. The `htpasswd` file is loaded once, at startup. If the file is invalid, the registry will display an error and will not start. @@ -629,7 +629,7 @@ object it is wrapping. For instance, a registry middleware must implement the This is an example configuration of the `cloudfront` middleware, a storage middleware: -```none +```yaml middleware: registry: - name: ARegistryMiddleware @@ -694,7 +694,7 @@ location of a proxy for the layer stored by the S3 storage driver. ## `http` -```none +```yaml http: addr: localhost:5000 net: tcp @@ -834,7 +834,7 @@ to access proxy statistics. These statistics are exposed at `/debug/vars` in JSO #### `prometheus` -```none +```yaml prometheus: enabled: true path: /metrics @@ -879,7 +879,7 @@ settings for the registry. ## `notifications` -```none +```yaml notifications: events: includereferences: true @@ -937,7 +937,7 @@ The `events` structure configures the information provided in event notification ## `redis` -```none +```yaml redis: addr: localhost:6379 password: asecret @@ -974,7 +974,7 @@ registry does not set an expiration value on keys. ### `pool` -```none +```yaml pool: maxidle: 16 maxactive: 64 @@ -991,7 +991,7 @@ Use these settings to configure the behavior of the Redis connection pool. ### `tls` -```none +```yaml tls: enabled: false ``` @@ -1005,7 +1005,7 @@ Use these settings to configure Redis TLS. ## `health` -```none +```yaml health: storagedriver: enabled: true @@ -1090,7 +1090,7 @@ attempt fails, the health check will fail. ## `proxy` -``` +```yaml proxy: remoteurl: https://registry-1.docker.io username: [username] @@ -1099,8 +1099,8 @@ proxy: ``` The `proxy` structure allows a registry to be configured as a pull-through cache -to Docker Hub. See -[mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) +to Docker Hub. See +[mirror](/recipes/mirror) for more information. Pushing to a registry configured as a pull-through cache is unsupported. @@ -1120,7 +1120,7 @@ username (such as `batman`) and the password for that username. ## `validation` -```none +```yaml validation: manifests: urls: @@ -1151,15 +1151,15 @@ If `allow` is unset, pushing a manifest containing URLs fails. If `allow` is set, pushing a manifest succeeds only if all URLs match one of the `allow` regular expressions **and** one of the following holds: -1. `deny` is unset. -2. `deny` is set but no URLs within the manifest match any of the `deny` regular - expressions. +1. `deny` is unset. +2. `deny` is set but no URLs within the manifest match any of the `deny` regular + expressions. ## Example: Development configuration You can use this simple example for local development: -```none +```yaml version: 0.1 log: level: debug @@ -1183,10 +1183,9 @@ See for another simple configuration. Both examples are generally useful for local development. - ## Example: Middleware configuration -This example configures [Amazon Cloudfront](http://aws.amazon.com/cloudfront/) +This example configures [Amazon Cloudfront](https://aws.amazon.com/cloudfront/) as the storage middleware in a registry. Middleware allows the registry to serve layers via a content delivery network (CDN). This reduces requests to the storage layer. @@ -1195,7 +1194,7 @@ Cloudfront requires the S3 storage driver. This is the configuration expressed in YAML: -```none +```yaml middleware: storage: - name: cloudfront @@ -1210,6 +1209,8 @@ middleware: See the configuration reference for [Cloudfront](#cloudfront) for more information about configuration options. -> **Note**: Cloudfront keys exist separately from other AWS keys. See -> [the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) -> for more information. +{{< hint type=note >}} +Cloudfront keys exist separately from other AWS keys. See +[the documentation on AWS credentials](https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) +for more information. +{{< /hint >}} diff --git a/docs/content/about/deploying.md b/docs/content/about/deploying.md index 17ec308d..c94ae691 100644 --- a/docs/content/about/deploying.md +++ b/docs/content/about/deploying.md @@ -9,7 +9,7 @@ A registry is an instance of the `registry` image, and runs within Docker. This topic provides basic information about deploying and configuring a registry. For an exhaustive list of configuration options, see the -[configuration reference](configuration.md). +[configuration reference](../configuration). If you have an air-gapped datacenter, see [Considerations for air-gapped registries](#considerations-for-air-gapped-registries). @@ -27,7 +27,7 @@ The registry is now ready to use. > **Warning**: These first few examples show registry configurations that are > only appropriate for testing. A production-ready registry must be protected by > TLS and should ideally use an access-control mechanism. Keep reading and then -> continue to the [configuration guide](configuration.md) to deploy a +> continue to the [configuration guide](../configuration) to deploy a > production-ready registry. ## Copy an image from Docker Hub to your registry @@ -38,40 +38,40 @@ as `my-ubuntu`, then pushes it to the local registry. Finally, the `ubuntu:16.04` and `my-ubuntu` images are deleted locally and the `my-ubuntu` image is pulled from the local registry. -1. Pull the `ubuntu:16.04` image from Docker Hub. +1. Pull the `ubuntu:16.04` image from Docker Hub. - ```console - $ docker pull ubuntu:16.04 - ``` + ```console + $ docker pull ubuntu:16.04 + ``` -2. Tag the image as `localhost:5000/my-ubuntu`. This creates an additional tag - for the existing image. When the first part of the tag is a hostname and - port, Docker interprets this as the location of a registry, when pushing. +2. Tag the image as `localhost:5000/my-ubuntu`. This creates an additional tag + for the existing image. When the first part of the tag is a hostname and + port, Docker interprets this as the location of a registry, when pushing. - ```console - $ docker tag ubuntu:16.04 localhost:5000/my-ubuntu - ``` + ```console + $ docker tag ubuntu:16.04 localhost:5000/my-ubuntu + ``` -3. Push the image to the local registry running at `localhost:5000`: +3. Push the image to the local registry running at `localhost:5000`: - ```console - $ docker push localhost:5000/my-ubuntu - ``` + ```console + $ docker push localhost:5000/my-ubuntu + ``` -4. Remove the locally-cached `ubuntu:16.04` and `localhost:5000/my-ubuntu` - images, so that you can test pulling the image from your registry. This - does not remove the `localhost:5000/my-ubuntu` image from your registry. +4. Remove the locally-cached `ubuntu:16.04` and `localhost:5000/my-ubuntu` + images, so that you can test pulling the image from your registry. This + does not remove the `localhost:5000/my-ubuntu` image from your registry. - ```console - $ docker image remove ubuntu:16.04 - $ docker image remove localhost:5000/my-ubuntu - ``` + ```console + $ docker image remove ubuntu:16.04 + $ docker image remove localhost:5000/my-ubuntu + ``` -5. Pull the `localhost:5000/my-ubuntu` image from your local registry. +5. Pull the `localhost:5000/my-ubuntu` image from your local registry. - ```console - $ docker pull localhost:5000/my-ubuntu - ``` + ```console + $ docker pull localhost:5000/my-ubuntu + ``` ## Stop a local registry @@ -94,7 +94,7 @@ To configure the container, you can pass additional or modified options to the `docker run` command. The following sections provide basic guidelines for configuring your registry. -For more details, see the [registry configuration reference](configuration.md). +For more details, see the [registry configuration reference](../configuration). ### Start the registry automatically @@ -144,7 +144,7 @@ $ docker run -d \ ### Customize the storage location -By default, your registry data is persisted as a [docker volume](../storage/volumes.md) +By default, your registry data is persisted as a [docker volume](https://docs.docker.com/storage/volumes) on the host filesystem. If you want to store your registry contents at a specific location on your host filesystem, such as if you have an SSD or SAN mounted into a particular directory, you might decide to use a bind mount instead. A bind mount @@ -166,8 +166,8 @@ $ docker run -d \ By default, the registry stores its data on the local filesystem, whether you use a bind mount or a volume. You can store the registry data in an Amazon S3 bucket, Google Cloud Platform, or on another storage back-end by using -[storage drivers](./storage-drivers/index.md). For more information, see -[storage configuration options](./configuration.md#storage). +[storage drivers](/storage-drivers). For more information, see +[storage configuration options](../configuration#storage). ## Run an externally-accessible registry @@ -190,48 +190,48 @@ These examples assume the following: If you have been issued an _intermediate_ certificate instead, see [use an intermediate certificate](#use-an-intermediate-certificate). -1. Create a `certs` directory. +1. Create a `certs` directory. - ```console - $ mkdir -p certs - ``` + ```console + $ mkdir -p certs + ``` - Copy the `.crt` and `.key` files from the CA into the `certs` directory. - The following steps assume that the files are named `domain.crt` and - `domain.key`. + Copy the `.crt` and `.key` files from the CA into the `certs` directory. + The following steps assume that the files are named `domain.crt` and + `domain.key`. -2. Stop the registry if it is currently running. +2. Stop the registry if it is currently running. - ```console - $ docker container stop registry - ``` + ```console + $ docker container stop registry + ``` -3. Restart the registry, directing it to use the TLS certificate. This command - bind-mounts the `certs/` directory into the container at `/certs/`, and sets - environment variables that tell the container where to find the `domain.crt` - and `domain.key` file. The registry runs on port 443, the default HTTPS port. +3. Restart the registry, directing it to use the TLS certificate. This command + bind-mounts the `certs/` directory into the container at `/certs/`, and sets + environment variables that tell the container where to find the `domain.crt` + and `domain.key` file. The registry runs on port 443, the default HTTPS port. - ```console - $ docker run -d \ - --restart=always \ - --name registry \ - -v "$(pwd)"/certs:/certs \ - -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \ - -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ - -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ - -p 443:443 \ - registry:2 - ``` + ```console + $ docker run -d \ + --restart=always \ + --name registry \ + -v "$(pwd)"/certs:/certs \ + -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \ + -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ + -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ + -p 443:443 \ + registry:2 + ``` -4. Docker clients can now pull from and push to your registry using its - external address. The following commands demonstrate this: +4. Docker clients can now pull from and push to your registry using its + external address. The following commands demonstrate this: - ```console - $ docker pull ubuntu:16.04 - $ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu - $ docker push myregistry.domain.com/my-ubuntu - $ docker pull myregistry.domain.com/my-ubuntu - ``` + ```console + $ docker pull ubuntu:16.04 + $ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu + $ docker push myregistry.domain.com/my-ubuntu + $ docker pull myregistry.domain.com/my-ubuntu + ``` #### Use an intermediate certificate @@ -252,23 +252,23 @@ The registry supports using Let's Encrypt to automatically obtain a browser-trusted certificate. For more information on Let's Encrypt, see [https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/) and the relevant section of the -[registry configuration](configuration.md#letsencrypt). +[registry configuration](../configuration#letsencrypt). ### Use an insecure registry (testing only) It is possible to use a self-signed certificate, or to use our registry insecurely. Unless you have set up verification for your self-signed -certificate, this is for testing only. See [run an insecure registry](insecure.md). +certificate, this is for testing only. See [run an insecure registry](../insecure). ## Run the registry as a service -[Swarm services](../engine/swarm/services.md) provide several advantages over +[Swarm services](https://docs.docker.com/engine/swarm/services) provide several advantages over standalone containers. They use a declarative model, which means that you define the desired state and Docker works to keep your service in that state. Services provide automatic load balancing scaling, and the ability to control the distribution of your service, among other advantages. Services also allow you to store sensitive data such as TLS certificates in -[secrets](../engine/swarm/secrets.md). +[secrets](https://docs.docker.com/engine/swarm/secrets). The storage back-end you use determines whether you use a fully scaled service or a service with either only a single node or a node constraint. @@ -342,9 +342,9 @@ The most important aspect is that a load balanced cluster of registries must share the same resources. For the current version of the registry, this means the following must be the same: - - Storage Driver - - HTTP Secret - - Redis Cache (if configured) +- Storage Driver +- HTTP Secret +- Redis Cache (if configured) Differences in any of the above cause problems serving requests. As an example, if you're using the filesystem driver, all registry instances @@ -393,87 +393,89 @@ The simplest way to achieve access restriction is through basic authentication This example uses native basic authentication using `htpasswd` to store the secrets. -> **Warning**: -> You **cannot** use authentication with authentication schemes that send -> credentials as clear text. You must -> [configure TLS first](deploying.md#run-an-externally-accessible-registry) for -> authentication to work. -{:.warning} +{{< hint type=warning >}} +You **cannot** use authentication with authentication schemes that send +credentials as clear text. You must +[configure TLS first](#run-an-externally-accessible-registry) for +authentication to work. +{{< /hint >}} -> **Warning** -> The official registry image **only** supports htpasswd credentials in -> bcrypt format, so if you omit the `-B` option when generating the credential -> using htpasswd, all authentication attempts will fail. -{:.warning} +{{< hint type=warning >}} +The official registry image **only** supports htpasswd credentials in +bcrypt format, so if you omit the `-B` option when generating the credential +using htpasswd, all authentication attempts will fail. +{{< /hint >}} -1. Create a password file with one entry for the user `testuser`, with password - `testpassword`: +1. Create a password file with one entry for the user `testuser`, with password + `testpassword`: - ```console - $ mkdir auth - $ docker run \ - --entrypoint htpasswd \ - httpd:2 -Bbn testuser testpassword > auth/htpasswd - ``` - - On Windows, make sure the output file is correctly encoded: + ```console + $ mkdir auth + $ docker run \ + --entrypoint htpasswd \ + httpd:2 -Bbn testuser testpassword > auth/htpasswd + ``` - ```powershell - docker run --rm --entrypoint htpasswd httpd:2 -Bbn testuser testpassword | Set-Content -Encoding ASCII auth/htpasswd - ``` + On Windows, make sure the output file is correctly encoded: -2. Stop the registry. + ```powershell + docker run --rm --entrypoint htpasswd httpd:2 -Bbn testuser testpassword | Set-Content -Encoding ASCII auth/htpasswd + ``` - ```console - $ docker container stop registry - ``` +2. Stop the registry. -3. Start the registry with basic authentication. + ```console + $ docker container stop registry + ``` - ```console - $ docker run -d \ - -p 5000:5000 \ - --restart=always \ - --name registry \ - -v "$(pwd)"/auth:/auth \ - -e "REGISTRY_AUTH=htpasswd" \ - -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \ - -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ - -v "$(pwd)"/certs:/certs \ - -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ - -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ - registry:2 - ``` +3. Start the registry with basic authentication. -4. Try to pull an image from the registry, or push an image to the registry. - These commands fail. + ```console + $ docker run -d \ + -p 5000:5000 \ + --restart=always \ + --name registry \ + -v "$(pwd)"/auth:/auth \ + -e "REGISTRY_AUTH=htpasswd" \ + -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \ + -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ + -v "$(pwd)"/certs:/certs \ + -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ + -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ + registry:2 + ``` -5. Log in to the registry. +4. Try to pull an image from the registry, or push an image to the registry. + These commands fail. - ```console - $ docker login myregistrydomain.com:5000 - ``` +5. Log in to the registry. - Provide the username and password from the first step. + ```console + $ docker login myregistrydomain.com:5000 + ``` - Test that you can now pull an image from the registry or push an image to - the registry. + Provide the username and password from the first step. -> **X509 errors**: X509 errors usually indicate that you are attempting to use -> a self-signed certificate without configuring the Docker daemon correctly. -> See [run an insecure registry](insecure.md). + Test that you can now pull an image from the registry or push an image to + the registry. + +{{< hint type=note title="X509 errors" >}} +X509 errors usually indicate that you are attempting to use +a self-signed certificate without configuring the Docker daemon correctly. +See [run an insecure registry](../insecure). +{{< /hint >}} ### More advanced authentication You may want to leverage more advanced basic auth implementations by using a -proxy in front of the registry. See the [recipes list](recipes/index.md). +proxy in front of the registry. See the [recipes list](/recipes/). The registry also supports delegated authentication which redirects users to a specific trusted token server. This approach is more complicated to set up, and only makes sense if you need to fully configure ACLs and need more control over the registry's integration into your global authorization and authentication -systems. Refer to the following [background information](spec/auth/token.md) and -[configuration information here](configuration.md#auth). +systems. Refer to the following [background information](/spec/auth/token) and +[configuration information here](../configuration#auth). This approach requires you to implement your own authentication system or leverage a third-party implementation. @@ -537,41 +539,42 @@ following: You are responsible for ensuring that you are in compliance with the terms of use for non-distributable layers. - 1. Edit the `daemon.json` file, which is located in `/etc/docker/` on Linux - hosts and `C:\ProgramData\docker\config\daemon.json` on Windows Server. - Assuming the file was previously empty, add the following contents: + 1. Edit the `daemon.json` file, which is located in `/etc/docker/` on Linux + hosts and `C:\ProgramData\docker\config\daemon.json` on Windows Server. + Assuming the file was previously empty, add the following contents: - ```json - { - "allow-nondistributable-artifacts": ["myregistrydomain.com:5000"] - } - ``` + ```json + { + "allow-nondistributable-artifacts": ["myregistrydomain.com:5000"] + } + ``` - The value is an array of registry addresses, separated by commas. + The value is an array of registry addresses, separated by commas. - Save and exit the file. + Save and exit the file. - 2. Restart Docker. + 2. Restart Docker. - 3. Restart the registry if it does not start automatically. + 3. Restart the registry if it does not start automatically. - 4. When you push images to the registries in the list, their - non-distributable layers are pushed to the registry. - - > **Warning**: Non-distributable artifacts typically have restrictions on - > how and where they can be distributed and shared. Only use this feature - > to push artifacts to private registries and ensure that you are in - > compliance with any terms that cover redistributing non-distributable - > artifacts. + 4. When you push images to the registries in the list, their + non-distributable layers are pushed to the registry. +{{< hint type=warning >}} +Non-distributable artifacts typically have restrictions on +how and where they can be distributed and shared. Only use this feature +to push artifacts to private registries and ensure that you are in +compliance with any terms that cover redistributing non-distributable +artifacts. +{{< /hint >}} ## Next steps More specific and advanced information is available in the following sections: - - [Configuration reference](configuration.md) - - [Working with notifications](notifications.md) - - [Advanced "recipes"](recipes/index.md) - - [Registry API](spec/api.md) - - [Storage driver model](storage-drivers/index.md) - - [Token authentication](spec/auth/token.md) +- [Configuration reference](../configuration) +- [Working with notifications](../notifications) +- [Advanced "recipes"](/recipes) +- [Registry API](/spec/api) +- [Storage driver model](/storage-drivers) +- [Token authentication](/spec/auth/token) diff --git a/docs/content/about/garbage-collection.md b/docs/content/about/garbage-collection.md index 928fab9a..f52d7794 100644 --- a/docs/content/about/garbage-collection.md +++ b/docs/content/about/garbage-collection.md @@ -21,15 +21,15 @@ that certain layers no longer exist on the filesystem. Filesystem layers are stored by their content address in the Registry. This has many advantages, one of which is that data is stored once and referred to by manifests. -See [here](compatibility.md#content-addressable-storage-cas) for more details. +See [here](../compatibility#content-addressable-storage-cas) for more details. Layers are therefore shared amongst manifests; each manifest maintains a reference to the layer. As long as a layer is referenced by one manifest, it cannot be garbage collected. Manifests and layers can be `deleted` with the registry API (refer to the API -documentation [here](spec/api.md#deleting-a-layer) and -[here](spec/api.md#deleting-an-image) for details). This API removes references +documentation [here](/spec/api#deleting-a-layer) and +[here](/spec/api#deleting-an-image) for details). This API removes references to the target and makes them eligible for garbage collection. It also makes them unable to be read via the API. diff --git a/docs/content/about/glossary.md b/docs/content/about/glossary.md index b07cfc0c..e31c4f44 100644 --- a/docs/content/about/glossary.md +++ b/docs/content/about/glossary.md @@ -1,5 +1,5 @@ --- -published: false +draft: true --- # Glossary diff --git a/docs/content/about/help.md b/docs/content/about/help.md index 8c5f7e6d..6e74aed1 100644 --- a/docs/content/about/help.md +++ b/docs/content/about/help.md @@ -10,5 +10,3 @@ If you want to report a bug: - be sure to first read about [how to contribute](https://github.com/distribution/distribution/blob/master/CONTRIBUTING.md). - you can then do so on the [GitHub project bugtracker](https://github.com/distribution/distribution/issues). - -You can also find out more about the Docker's project [Getting Help resources](../opensource/ways.md). diff --git a/docs/content/about/insecure.md b/docs/content/about/insecure.md index a012e8ab..e9f55f15 100644 --- a/docs/content/about/insecure.md +++ b/docs/content/about/insecure.md @@ -11,96 +11,96 @@ involves security trade-offs and additional configuration steps. ## Deploy a plain HTTP registry -> **Warning**: -> It's not possible to use an insecure registry with basic authentication. -{:.warning} +{{< hint type=warning >}} +It's not possible to use an insecure registry with basic authentication. +{{< /hint >}} This procedure configures Docker to entirely disregard security for your registry. This is **very** insecure and is not recommended. It exposes your registry to trivial man-in-the-middle (MITM) attacks. Only use this solution for isolated testing or in a tightly controlled, air-gapped environment. -1. Edit the `daemon.json` file, whose default location is - `/etc/docker/daemon.json` on Linux or - `C:\ProgramData\docker\config\daemon.json` on Windows Server. If you use - Docker Desktop for Mac or Docker Desktop for Windows, click the Docker icon, choose - **Preferences** (Mac) or **Settings** (Windows), and choose **Docker Engine**. +1. Edit the `daemon.json` file, whose default location is + `/etc/docker/daemon.json` on Linux or + `C:\ProgramData\docker\config\daemon.json` on Windows Server. If you use + Docker Desktop for Mac or Docker Desktop for Windows, click the Docker icon, choose + **Preferences** (Mac) or **Settings** (Windows), and choose **Docker Engine**. - If the `daemon.json` file does not exist, create it. Assuming there are no - other settings in the file, it should have the following contents: + If the `daemon.json` file does not exist, create it. Assuming there are no + other settings in the file, it should have the following contents: - ```json - { - "insecure-registries" : ["myregistrydomain.com:5000"] - } - ``` + ```json + { + "insecure-registries" : ["myregistrydomain.com:5000"] + } + ``` - Substitute the address of your insecure registry for the one in the example. + Substitute the address of your insecure registry for the one in the example. - With insecure registries enabled, Docker goes through the following steps: + With insecure registries enabled, Docker goes through the following steps: - - First, try using HTTPS. - - If HTTPS is available but the certificate is invalid, ignore the error - about the certificate. - - If HTTPS is not available, fall back to HTTP. + - First, try using HTTPS. + + - If HTTPS is available but the certificate is invalid, ignore the error + about the certificate. + + - If HTTPS is not available, fall back to HTTP. 2. Restart Docker for the changes to take effect. - Repeat these steps on every Engine host that wants to access your registry. - ## Use self-signed certificates -> **Warning**: -> Using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below) -{:.warning} +{{< hint type=warning >}} +Using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below) +{{< /hint >}} This is more secure than the insecure registry solution. -1. Generate your own certificate: +1. Generate your own certificate: - ```console - $ mkdir -p certs + ```console + $ mkdir -p certs - $ openssl req \ - -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \ - -addext "subjectAltName = DNS:myregistry.domain.com" \ - -x509 -days 365 -out certs/domain.crt - ``` + $ openssl req \ + -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \ + -addext "subjectAltName = DNS:myregistry.domain.com" \ + -x509 -days 365 -out certs/domain.crt + ``` - Be sure to use the name `myregistry.domain.com` as a CN. + Be sure to use the name `myregistry.domain.com` as a CN. -2. Use the result to [start your registry with TLS enabled](./deploying.md#get-a-certificate). +2. Use the result to [start your registry with TLS enabled](../deploying#get-a-certificate). -3. Instruct every Docker daemon to trust that certificate. The way to do this - depends on your OS. +3. Instruct every Docker daemon to trust that certificate. The way to do this + depends on your OS. - - **Linux**: Copy the `domain.crt` file to - `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker - host. You do not need to restart Docker. + - **Linux**: Copy the `domain.crt` file to + `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker + host. You do not need to restart Docker. - - **Windows Server**: + - **Windows Server**: - 1. Open Windows Explorer, right-click the `domain.crt` - file, and choose Install certificate. When prompted, select the following - options: + 1. Open Windows Explorer, right-click the `domain.crt` + file, and choose Install certificate. When prompted, select the following + options: - | Store location | local machine | - | Place all certificates in the following store | selected | + | Store location | local machine | + | Place all certificates in the following store | selected | - 2. Click **Browser** and select **Trusted Root Certificate Authorities**. + 2. Click **Browser** and select **Trusted Root Certificate Authorities**. - 3. Click **Finish**. Restart Docker. + 3. Click **Finish**. Restart Docker. - - **Docker Desktop for Mac**: Follow the instructions in - [Adding custom CA certificates](../desktop/mac/index.md#add-tls-certificates){: target="_blank" rel="noopener" class="_"}. - Restart Docker. + - **Docker Desktop for Mac**: Follow the instructions in + [Adding custom CA certificates](https://docs.docker.com/desktop/mac/#add-tls-certificates). + Restart Docker. - - **Docker Desktop for Windows**: Follow the instructions in - [Adding custom CA certificates](../desktop/windows/index.md#adding-tls-certificates){: target="_blank" rel="noopener" class="_"}. - Restart Docker. + - **Docker Desktop for Windows**: Follow the instructions in + [Adding custom CA certificates](https://docs.docker.com/desktop/windows/#adding-tls-certificates). + Restart Docker. ## Troubleshoot insecure registry diff --git a/docs/content/about/notifications.md b/docs/content/about/notifications.md index 245d2faa..81292bd9 100644 --- a/docs/content/about/notifications.md +++ b/docs/content/about/notifications.md @@ -8,9 +8,9 @@ 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_](notifications.md#endpoints). +queues and dispatches events to [_Endpoints_](#endpoints). -![Workflow of registry notifications](images/notifications.png) +![Workflow of registry notifications](/images/notifications.png) ## Endpoints @@ -45,7 +45,7 @@ The above would configure the registry with an endpoint to send events to 5 failures happen consecutively, the registry backs off for 1 second before trying again. -For details on the fields, see the [configuration documentation](configuration.md#notifications). +For details on the fields, see the [configuration documentation](../configuration/#notifications). A properly configured endpoint should lead to a log message from the registry upon startup: diff --git a/docs/content/recipes/_index.md b/docs/content/recipes/_index.md index 3ffdba3b..d6332b59 100644 --- a/docs/content/recipes/_index.md +++ b/docs/content/recipes/_index.md @@ -9,7 +9,7 @@ These recipes are not useful for most standard set-ups. ## Requirements -Before following these steps, work through the [deployment guide](../deploying.md). +Before following these steps, work through the [deployment guide](../about/deploying). At this point, it's assumed that: @@ -21,8 +21,8 @@ At this point, it's assumed that: ## The List - * [using Apache as an authenticating proxy](apache.md) - * [using Nginx as an authenticating proxy](nginx.md) - * [running a Registry on macOS](osx-setup-guide.md) - * [mirror the Docker Hub](mirror.md) - * [start registry via systemd](systemd.md) + * [using Apache as an authenticating proxy](apache) + * [using Nginx as an authenticating proxy](nginx) + * [running a Registry on macOS](osx-setup-guide) + * [mirror the Docker Hub](mirror) + * [start registry via systemd](systemd) diff --git a/docs/content/recipes/apache.md b/docs/content/recipes/apache.md index b559d264..84639275 100644 --- a/docs/content/recipes/apache.md +++ b/docs/content/recipes/apache.md @@ -12,7 +12,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO ### Alternatives -If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth). +If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](/about/deploying#native-basic-auth). ### Solution @@ -30,13 +30,13 @@ Furthermore, introducing an extra http layer in your communication pipeline adds ## Setting things up -Read again [the requirements](index.md#requirements). +Read again [the requirements](../#requirements). Ready? Run the following script: -``` +```sh mkdir -p auth mkdir -p data @@ -191,19 +191,27 @@ EOF Now, start your stack: - docker-compose up -d +```console +$ docker-compose up -d +``` Log in with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: - docker login myregistrydomain.com:5043 - docker tag ubuntu myregistrydomain.com:5043/test - docker push myregistrydomain.com:5043/test +```console +$ docker login myregistrydomain.com:5043 +$ docker tag ubuntu myregistrydomain.com:5043/test +$ docker push myregistrydomain.com:5043/test +``` Now, log in with a "pull-only" user (using `testuser` and `testpassword`), then pull back the image: - docker login myregistrydomain.com:5043 - docker pull myregistrydomain.com:5043/test +```console +$ docker login myregistrydomain.com:5043 +$ docker pull myregistrydomain.com:5043/test +``` Verify that the "pull-only" can NOT push: - docker push myregistrydomain.com:5043/test +```console +$ docker push myregistrydomain.com:5043/test +``` diff --git a/docs/content/recipes/mirror.md b/docs/content/recipes/mirror.md index fe00b8b4..bd17a96b 100644 --- a/docs/content/recipes/mirror.md +++ b/docs/content/recipes/mirror.md @@ -2,8 +2,6 @@ description: Setting-up a local mirror for Docker Hub images keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced title: Registry as a pull through cache -redirect_from: -- /engine/admin/registry_mirror/ --- ## Use-case @@ -88,7 +86,8 @@ but this property does not hold true for a registry cache cluster. > **Note** > -> Service accounts included in the Team plan are limited to 5,000 pulls per day. See [Service Accounts](/docker-hub/service-accounts/) for more details. +> Service accounts included in the Team plan are limited to 5,000 pulls per day. +> See [Service Accounts](https://docs.docker.com/docker-hub/service-accounts/) for more details. ### Configure the cache @@ -113,12 +112,12 @@ proxy: > **Warning**: For the scheduler to clean up old entries, `delete` must > be enabled in the registry configuration. See -> [Registry Configuration](../configuration.md) for more details. +> [Registry Configuration](/about/configuration) for more details. ### Configure the Docker daemon Either pass the `--registry-mirror` option when starting `dockerd` manually, -or edit [`/etc/docker/daemon.json`](../../engine/reference/commandline/dockerd.md#daemon-configuration-file) +or edit [`/etc/docker/daemon.json`](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file) and add the `registry-mirrors` key and value, to make the change persistent. ```json diff --git a/docs/content/recipes/nginx.md b/docs/content/recipes/nginx.md index 8efaeb5c..127d900f 100644 --- a/docs/content/recipes/nginx.md +++ b/docs/content/recipes/nginx.md @@ -2,8 +2,6 @@ description: Restricting access to your registry using a nginx proxy keywords: registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced title: Authenticate proxy with nginx -redirect_from: -- /registry/nginx/ --- ## Use-case @@ -19,7 +17,7 @@ mechanism fronting their internal http portal. If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native -[basic auth registry feature](../deploying.md#native-basic-auth). +[basic auth registry feature](/about/deploying#native-basic-auth). ### Solution @@ -52,7 +50,7 @@ complexity is required. For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets the following client header: -``` +```none X-Real-IP X-Forwarded-For X-Forwarded-Proto @@ -74,132 +72,136 @@ properly. For more information, see ## Setting things up -Review the [requirements](index.md#requirements), then follow these steps. +Review the [requirements](../#requirements), then follow these steps. -1. Create the required directories +1. Create the required directories - ```console - $ mkdir -p auth data - ``` + ```console + $ mkdir -p auth data + ``` -2. Create the main nginx configuration. Paste this code block into a new file called `auth/nginx.conf`: +2. Create the main nginx configuration. Paste this code block into a new file called `auth/nginx.conf`: - ```conf - events { - worker_connections 1024; - } + ```conf + events { + worker_connections 1024; + } - http { + http { - upstream docker-registry { - server registry:5000; - } + upstream docker-registry { + server registry:5000; + } - ## Set a variable to help us decide if we need to add the - ## 'Docker-Distribution-Api-Version' header. - ## The registry always sets this header. - ## In the case of nginx performing auth, the header is unset - ## since nginx is auth-ing before proxying. - map $upstream_http_docker_distribution_api_version $docker_distribution_api_version { - '' 'registry/2.0'; - } + ## Set a variable to help us decide if we need to add the + ## 'Docker-Distribution-Api-Version' header. + ## The registry always sets this header. + ## In the case of nginx performing auth, the header is unset + ## since nginx is auth-ing before proxying. + map $upstream_http_docker_distribution_api_version $docker_distribution_api_version { + '' 'registry/2.0'; + } - server { - listen 443 ssl; - server_name myregistrydomain.com; + server { + listen 443 ssl; + server_name myregistrydomain.com; - # SSL - ssl_certificate /etc/nginx/conf.d/domain.crt; - ssl_certificate_key /etc/nginx/conf.d/domain.key; + # SSL + ssl_certificate /etc/nginx/conf.d/domain.crt; + ssl_certificate_key /etc/nginx/conf.d/domain.key; - # Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html - ssl_protocols TLSv1.1 TLSv1.2; - ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:10m; + # Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html + ssl_protocols TLSv1.1 TLSv1.2; + ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; + ssl_prefer_server_ciphers on; + ssl_session_cache shared:SSL:10m; - # disable any limits to avoid HTTP 413 for large image uploads - client_max_body_size 0; + # disable any limits to avoid HTTP 413 for large image uploads + client_max_body_size 0; - # required to avoid HTTP 411: see Issue #1486 (https://github.com/moby/moby/issues/1486) - chunked_transfer_encoding on; + # required to avoid HTTP 411: see Issue #1486 (https://github.com/moby/moby/issues/1486) + chunked_transfer_encoding on; - location /v2/ { - # Do not allow connections from docker 1.5 and earlier - # docker pre-1.6.0 did not properly set the user agent on ping, catch "Go *" user agents - if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) { - return 404; - } + location /v2/ { + # Do not allow connections from docker 1.5 and earlier + # docker pre-1.6.0 did not properly set the user agent on ping, catch "Go *" user agents + if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) { + return 404; + } - # To add basic authentication to v2 use auth_basic setting. - auth_basic "Registry realm"; - auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd; + # To add basic authentication to v2 use auth_basic setting. + auth_basic "Registry realm"; + auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd; - ## If $docker_distribution_api_version is empty, the header is not added. - ## See the map directive above where this variable is defined. - add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always; + ## If $docker_distribution_api_version is empty, the header is not added. + ## See the map directive above where this variable is defined. + add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always; - proxy_pass http://docker-registry; - proxy_set_header Host $http_host; # required for docker client's sake - proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_read_timeout 900; - } - } - } - ``` + proxy_pass http://docker-registry; + proxy_set_header Host $http_host; # required for docker client's sake + proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_read_timeout 900; + } + } + } + ``` -3. Create a password file `auth/nginx.htpasswd` for "testuser" and "testpassword". +3. Create a password file `auth/nginx.htpasswd` for "testuser" and "testpassword". - ```console - $ docker run --rm --entrypoint htpasswd registry:2 -Bbn testuser testpassword > auth/nginx.htpasswd - ``` + ```console + $ docker run --rm --entrypoint htpasswd registry:2 -Bbn testuser testpassword > auth/nginx.htpasswd + ``` - > **Note**: If you do not want to use `bcrypt`, you can omit the `-B` parameter. + > **Note**: If you do not want to use `bcrypt`, you can omit the `-B` parameter. -4. Copy your certificate files to the `auth/` directory. +4. Copy your certificate files to the `auth/` directory. - ```console - $ cp domain.crt auth - $ cp domain.key auth - ``` + ```console + $ cp domain.crt auth + $ cp domain.key auth + ``` -5. Create the compose file. Paste the following YAML into a new file called `docker-compose.yml`. +5. Create the compose file. Paste the following YAML into a new file called `docker-compose.yml`. - ```yaml - version: "3" + ```yaml + version: "3" - services: - nginx: - # Note : Only nginx:alpine supports bcrypt. - # If you don't need to use bcrypt, you can use a different tag. - # Ref. https://github.com/nginxinc/docker-nginx/issues/29 - image: "nginx:alpine" - ports: - - 5043:443 - depends_on: - - registry - volumes: - - ./auth:/etc/nginx/conf.d - - ./auth/nginx.conf:/etc/nginx/nginx.conf:ro + services: + nginx: + # Note : Only nginx:alpine supports bcrypt. + # If you don't need to use bcrypt, you can use a different tag. + # Ref. https://github.com/nginxinc/docker-nginx/issues/29 + image: "nginx:alpine" + ports: + - 5043:443 + depends_on: + - registry + volumes: + - ./auth:/etc/nginx/conf.d + - ./auth/nginx.conf:/etc/nginx/nginx.conf:ro - registry: - image: registry:2 - volumes: - - ./data:/var/lib/registry - ``` + registry: + image: registry:2 + volumes: + - ./data:/var/lib/registry + ``` ## Starting and stopping Now, start your stack: - docker-compose up -d +```consonle +$ docker-compose up -d +``` Login with a "push" authorized user (using `testuser` and `testpassword`), then tag and push your first image: - docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043 - docker tag ubuntu myregistrydomain.com:5043/test - docker push myregistrydomain.com:5043/test - docker pull myregistrydomain.com:5043/test +```console +$ docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043 +$ docker tag ubuntu myregistrydomain.com:5043/test +$ docker push myregistrydomain.com:5043/test +$ docker pull myregistrydomain.com:5043/test +``` diff --git a/docs/content/recipes/osx-setup-guide.md b/docs/content/recipes/osx-setup-guide.md index 40bc1a29..e33782a6 100644 --- a/docs/content/recipes/osx-setup-guide.md +++ b/docs/content/recipes/osx-setup-guide.md @@ -26,49 +26,65 @@ If you know, safely skip to the next section. If you don't, the TLDR is: - bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer) - source ~/.gvm/scripts/gvm - gvm install go1.4.2 - gvm use go1.4.2 +```console +$ bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer) +$ source ~/.gvm/scripts/gvm +$ gvm install go1.4.2 +$ gvm use go1.4.2 +``` If you want to understand, you should read [How to Write Go Code](https://golang.org/doc/code.html). ## Checkout the source tree - mkdir -p $GOPATH/src/github.com/distribution - git clone https://github.com/distribution/distribution.git $GOPATH/src/github.com/distribution/distribution - cd $GOPATH/src/github.com/distribution/distribution +```console +$ mkdir -p $GOPATH/src/github.com/distribution +$ git clone https://github.com/distribution/distribution.git $GOPATH/src/github.com/distribution/distribution +$ cd $GOPATH/src/github.com/distribution/distribution +``` ## Build the binary - GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries - sudo mkdir -p /usr/local/libexec - sudo cp bin/registry /usr/local/libexec/registry +```console +$ GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries +$ sudo mkdir -p /usr/local/libexec +$ sudo cp bin/registry /usr/local/libexec/registry +``` ## Setup Copy the registry configuration file in place: - mkdir /Users/Shared/Registry - cp docs/osx/config.yml /Users/Shared/Registry/config.yml +```console +$ mkdir /Users/Shared/Registry +$ cp docs/osx/config.yml /Users/Shared/Registry/config.yml +``` ## Run the registry under launchd Copy the registry plist into place: - plutil -lint docs/recipes/osx/com.docker.registry.plist - cp docs/recipes/osx/com.docker.registry.plist ~/Library/LaunchAgents/ - chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist +```console +$ plutil -lint docs/recipes/osx/com.docker.registry.plist +$ cp docs/recipes/osx/com.docker.registry.plist ~/Library/LaunchAgents/ +$ chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist +``` Start the registry: - launchctl load ~/Library/LaunchAgents/com.docker.registry.plist +```console +$ launchctl load ~/Library/LaunchAgents/com.docker.registry.plist +``` ### Restart the registry service - launchctl stop com.docker.registry - launchctl start com.docker.registry +```console +$ launchctl stop com.docker.registry +$ launchctl start com.docker.registry +``` ### Unload the registry service - launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist +```console +$ launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist +``` diff --git a/docs/content/recipes/systemd.md b/docs/content/recipes/systemd.md index 99a0823d..f3d84ab2 100644 --- a/docs/content/recipes/systemd.md +++ b/docs/content/recipes/systemd.md @@ -7,8 +7,9 @@ title: Start registry via systemd ## Use-case Using systemd to manage containers can make service discovery and maintenance easier -by managining all services in the same way. Additionally, when using Podman, systemd +by managing all services in the same way. Additionally, when using Podman, systemd can start the registry with socket-activation, providing additional security options: + * Run as non-root and expose on a low-numbered socket (< 1024) * Run with `--network=none` @@ -18,7 +19,8 @@ When deploying the registry via Docker, a simple service file can be used to man the registry: registry.service -``` + +```ini [Unit] Description=Docker registry After=docker.service @@ -40,7 +42,7 @@ WantedBy=multi-user.target In this case, the registry will store images in the named-volume `registry`. Note that the container is destroyed on restart instead of using `--rm` or -destroy on stop. This is done to make accessing `docker logs ...` easier in +destroy on stop. This is done to make accessing `docker logs ...` easier in the case of issues. ### Podman @@ -50,7 +52,7 @@ socket-activation of containers. #### Create service file -``` +```sh podman create --name registry --network=none -v registry:/var/lib/registry registry:2 podman generate systemd --name --new registry > registry.service ``` @@ -58,7 +60,8 @@ podman generate systemd --name --new registry > registry.service #### Create socket file registry.socket -``` + +```ini [Unit] Description=container registry @@ -71,7 +74,7 @@ WantedBy=sockets.target ### Installation -Installation can be either rootful or rootless. For Docker, rootless configurations +Installation can be either rootful or rootless. For Docker, rootless configurations often include additional setup steps that are beyond the scope of this recipe, whereas for Podman, rootless containers generally work out of the box. diff --git a/docs/content/spec/_index.md b/docs/content/spec/_index.md index 46fddb12..5e9729b8 100644 --- a/docs/content/spec/_index.md +++ b/docs/content/spec/_index.md @@ -6,7 +6,7 @@ keywords: registry, service, images, repository, json # Docker Registry Reference -* [HTTP API V2](api.md) -* [Storage Driver](https://docs.docker.com/registry/storage-drivers/) -* [Token Authentication Specification](auth/token.md) -* [Token Authentication Implementation](auth/jwt.md) +* [HTTP API V2](api) +* [Storage Driver](/storage-drivers/) +* [Token Authentication Specification](auth/token) +* [Token Authentication Implementation](auth/jwt) diff --git a/docs/content/spec/api.md b/docs/content/spec/api.md index 9b34163c..45d6c0d0 100644 --- a/docs/content/spec/api.md +++ b/docs/content/spec/api.md @@ -2,12 +2,10 @@ title: "HTTP API V2" description: "Specification for the Registry API." keywords: registry, on-prem, images, tags, repository, distribution, api, advanced -redirect_from: +aliases: - /reference/api/registry_api/ --- -# Docker Registry HTTP API V2 - ## Introduction The _Docker Registry HTTP API_ is the protocol to facilitate distribution of @@ -212,7 +210,9 @@ 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// +```none +/v2// +``` For example, an API endpoint that will work with the `library/ubuntu` repository, the URI prefix will be: @@ -252,6 +252,7 @@ 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: +```none { "errors": [ { @@ -262,6 +263,7 @@ errors will be returned in the following format: ... ] } +``` 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 @@ -282,7 +284,9 @@ section. A minimal endpoint, mounted at `/v2/` will provide version support information based on its response statuses. The request format is as follows: - GET /v2/ +```none +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. @@ -305,7 +309,7 @@ API. When this header is omitted, clients may fallback to an older API version. ### Content Digests -This API design is driven heavily by [content addressability](http://en.wikipedia.org/wiki/Content-addressable_storage). +This API design is driven heavily by [content addressability](https://en.wikipedia.org/wiki/Content-addressable_storage). The core of this design is the concept of a content addressable identifier. It uniquely identifies content by taking a collision-resistant hash of the bytes. Such an identifier can be independently calculated and verified by selection @@ -403,7 +407,7 @@ the V2 registry API, keyed by their digest. The image manifest can be fetched with the following url: -``` +```none GET /v2//manifests/ ``` @@ -411,28 +415,29 @@ The `name` and `reference` parameter identify the image and are required. The reference may include a tag or digest. The client should include an Accept header indicating which manifest content -types it supports. For more details on the manifest formats and their content -types, see [manifest-v2-1.md](manifest-v2-1.md) and -[manifest-v2-2.md](manifest-v2-2.md). In a successful response, the Content-Type -header will indicate which manifest type is being returned. +types it supports. For more details on the manifest format and content types, +see [Image Manifest Version 2, Schema 2](../manifest-v2-2). +In a successful response, the Content-Type header will indicate which manifest type is being returned. 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](https://github.com/docker/docker/issues/8093) for details): - { - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": - }, - ... - ], - "history": , - "signature": - } +```none +{ + "name": , + "tag": , + "fsLayers": [ + { + "blobSum": + }, + ... + ], + "history": , + "signature": +} +``` The client should verify the returned manifest signature for authenticity before fetching layers. @@ -441,7 +446,7 @@ before fetching layers. The image manifest can be checked for existence with the following url: -``` +```none HEAD /v2//manifests/ ``` @@ -452,13 +457,12 @@ 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 response will be as follows: -``` +```none 200 OK Content-Length: Docker-Content-Digest: ``` - #### Pulling a Layer Layers are stored in the blob portion of the registry, keyed by digest. @@ -503,7 +507,7 @@ use the most recent value returned by the API. To begin the process, a POST request should be issued in the following format: -``` +```none POST /v2//blobs/uploads/ ``` @@ -515,7 +519,7 @@ will be linked. Responses to this request are covered below. The existence of a layer can be checked via a `HEAD` request to the blob store API. The request should be formatted as follows: -``` +```none HEAD /v2//blobs/ ``` @@ -523,7 +527,7 @@ If the layer with the digest 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: -``` +```none 200 OK Content-Length: Docker-Content-Digest: @@ -539,7 +543,7 @@ for the existing registry layer, but the digests will be guaranteed to match. If the POST request is successful, a `202 Accepted` response will be returned with the upload URL in the `Location` header: -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- @@ -568,20 +572,20 @@ header, there are examples of [similar approaches](https://developers.google.com For an upload that just started, for an example with a 1000 byte layer file, the `Range` header would be as follows: -``` +```none Range: bytes=0-0 ``` To get the status of an upload, issue a GET request to the upload URL: -``` +```none GET /v2//blobs/uploads/ Host: ``` The response will be similar to the above, except will return 204 status: -``` +```none 204 No Content Location: /v2//blobs/uploads/ Range: bytes=0- @@ -598,7 +602,7 @@ 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: -``` +```none PUT /v2//blobs/uploads/?digest= Content-Length: Content-Type: application/octet-stream @@ -615,7 +619,7 @@ and expected responses. To carry out an upload of a chunk, the client can specify a range header and only include that part of the layer file: -``` +```none PATCH /v2//blobs/uploads/ Content-Length: Content-Range: - @@ -630,7 +634,7 @@ 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: -``` +```none 416 Requested Range Not Satisfiable Location: /v2//blobs/uploads/ Range: 0- @@ -649,7 +653,7 @@ following conditions: 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: -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- @@ -664,7 +668,7 @@ 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: -``` +```none PUT /v2//blobs/uploads/?digest= Content-Length: Content-Range: - @@ -682,7 +686,7 @@ 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: -``` +```none 201 Created Location: /v2//blobs/ Content-Length: 0 @@ -701,7 +705,7 @@ The "digest" parameter is designed as an opaque parameter to support verification of a successful transfer. For example, an HTTP URI parameter might be as follows: -``` +```none sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b ``` @@ -713,7 +717,7 @@ match this digest. An upload can be cancelled by issuing a DELETE request to the upload endpoint. The format will be as follows: -``` +```none DELETE /v2//blobs/uploads/ ``` @@ -729,7 +733,7 @@ to, removing the need to upload a blob already known to the registry. To issue a blob mount instead of an upload, a POST request should be issued in the following format: -``` +```none POST /v2//blobs/uploads/?mount=&from= Content-Length: 0 ``` @@ -737,7 +741,7 @@ Content-Length: 0 If the blob is successfully mounted, the client will receive a `201 Created` response: -``` +```none 201 Created Location: /v2//blobs/ Content-Length: 0 @@ -754,7 +758,7 @@ If a mount fails due to invalid repository or digest arguments, the registry will fall back to the standard upload behavior and return a `202 Accepted` with the upload URL in the `Location` header: -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: bytes=0- @@ -765,9 +769,11 @@ Docker-Upload-UUID: This behavior is consistent with older versions of the registry, which do not recognize the repository mount query parameters. -Note: a client may issue a HEAD request to check existence of a blob in a source +{{< hint type=note >}} +A client may issue a HEAD request to check existence of a blob in a source repository to distinguish between the registry not supporting blob mounts and the blob not existing in the expected repository. +{{< /hint >}} ##### Errors @@ -789,13 +795,17 @@ client must restart the upload process. A layer may be deleted from the registry via its `name` and `digest`. A delete may be issued with the following request format: - DELETE /v2//blobs/ +```none +DELETE /v2//blobs/ +``` If the blob exists and has been successfully deleted, the following response will be issued: - 202 Accepted - Content-Length: None +```none +202 Accepted +Content-Length: None +``` If the blob had already been deleted or did not exist, a `404 Not Found` response will be issued instead. @@ -808,27 +818,29 @@ then the complete images will not be resolvable. 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//manifests/ - Content-Type: +```none +PUT /v2//manifests/ +Content-Type: - { - "name": , - "tag": , - "fsLayers": [ - { - "blobSum": - }, - ... - ], - "history": , - "signature": , +{ + "name": , + "tag": , + "fsLayers": [ + { + "blobSum": + }, ... - } + ], + "history": , + "signature": , + ... +} +``` 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". The content type should match the type of the manifest being uploaded, as specified -in [manifest-v2-1.md](manifest-v2-1.md) and [manifest-v2-2.md](manifest-v2-2.md). +in [Image Manifest Version 2, Schema 2](../manifest-v2-2). If there is a problem with pushing the manifest, a relevant 4xx response will be returned with a JSON error message. Please see the @@ -840,18 +852,20 @@ returned. The `detail` field of the error response will have a `digest` field identifying the missing blob. 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": - } - }, - ... - ] - } +```none +{ + "errors": [ + { + "code": "BLOB_UNKNOWN", + "message": "blob unknown to registry", + "detail": { + "digest": + } + }, + ... + ] +} +``` ### Listing Repositories @@ -862,13 +876,13 @@ available through the _catalog_. The catalog for a given registry can be retrieved with the following request: -``` +```none GET /v2/_catalog ``` The response will be in the following format: -``` +```none 200 OK Content-Type: application/json @@ -906,7 +920,7 @@ Paginated catalog results can be retrieved by adding an `n` parameter to the request URL, declaring that the response should be limited to `n` results. Starting a paginated flow begins as follows: -``` +```none GET /v2/_catalog?n= ``` @@ -914,7 +928,7 @@ The above specifies that a catalog response should be returned, from the start o the result set, ordered lexically, limiting the number of results to `n`. The response to such a request would look as follows: -``` +```none 200 OK Content-Type: application/json Link: <?n=&last=>; rel="next" @@ -950,7 +964,7 @@ to skip forward in the catalog. To get the next result set, a client would issue the request as follows, using the URL encoded in the described `Link` header: -``` +```none GET /v2/_catalog?n=&last= ``` @@ -965,7 +979,7 @@ entries. The behavior of `last` is quite simple when demonstrated with an example. Let us say the registry has the following repositories: -``` +```none a b c @@ -976,7 +990,7 @@ If the value of `n` is 2, _a_ and _b_ will be returned on the first response. The `Link` header returned on the response will have `n` set to 2 and last set to _b_: -``` +```none Link: <?n=2&last=b>; rel="next" ``` @@ -1016,7 +1030,7 @@ any differences. Starting a paginated flow may begin as follows: -``` +```none GET /v2//tags/list?n= ``` @@ -1024,7 +1038,7 @@ The above specifies that a tags response should be returned, from the start of the result set, ordered lexically, limiting the number of results to `n`. The response to such a request would look as follows: -``` +```none 200 OK Content-Type: application/json Link: <?n=&last=>; rel="next" @@ -1042,7 +1056,7 @@ To get the next result set, a client would issue the request as follows, using the value encoded in the [RFC5988](https://tools.ietf.org/html/rfc5988) `Link` header: -``` +```none GET /v2//tags/list?n=&last= ``` @@ -1074,23 +1088,27 @@ response will be issued instead. Accept: application/vnd.docker.distribution.manifest.v2+json -> for more details, see: [compatibility.md](../compatibility.md#content-addressable-storage-cas) +> for more details, see: [compatibility](/about/compatibility#content-addressable-storage-cas) ## 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. +{{< hint type=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. +{{< /hint >}} 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. +{{< hint type=note >}} +The sections on endpoint detail are arranged with an example +request, a description of the request, followed by information about that +request. +{{< /hint >}} A list of methods and URIs are covered in the table below: @@ -1110,7 +1128,6 @@ A list of methods and URIs are covered in the table below: | DELETE | `/v2//blobs/uploads/` | Blob Upload | Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. | | GET | `/v2/_catalog` | Catalog | Retrieve a sorted, json list of repositories available in the registry. | - The detail for each endpoint is covered in the following sections. ### Errors @@ -1137,29 +1154,20 @@ The error codes encountered via the API are enumerated in the following table: `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. - - ### Base Base V2 API route. Typically, this can be used for lightweight version checks and to validate registry authentication. - - #### GET Base Check that the endpoint implements Docker Registry API V2. - - -``` +```none GET /v2/ Host: Authorization: ``` - - - The following parameters should be specified on the request: |Name|Kind|Description| @@ -1167,33 +1175,25 @@ The following parameters should be specified on the request: |`Host`|header|Standard HTTP Host Header. Should be set to the registry host.| |`Authorization`|header|An RFC7235 compliant authorization header.| - - - ###### On Success: OK -``` +```none 200 OK ``` The API implements V2 protocol and is accessible. - - - ###### On Failure: Not Found -``` +```none 404 Not Found ``` The registry does not implement the V2 API. - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -1220,19 +1220,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -1257,32 +1253,23 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - - ### Tags Retrieve information about tags. - - #### GET Tags Fetch the tags under the repository identified by `name`. - ##### Tags -``` +```none GET /v2//tags/list Host: Authorization: @@ -1290,7 +1277,6 @@ Authorization: Return all tags for the repository - The following parameters should be specified on the request: |Name|Kind|Description| @@ -1299,12 +1285,9 @@ The following parameters should be specified on the request: |`Authorization`|header|An RFC7235 compliant authorization header.| |`name`|path|Name of the target repository.| - - - ###### On Success: OK -``` +```none 200 OK Content-Length: Content-Type: application/json @@ -1326,12 +1309,9 @@ The following headers will be returned with the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -1358,19 +1338,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -1395,19 +1371,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -1432,19 +1404,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -1469,25 +1437,20 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ##### Tags Paginated -``` +```none GET /v2//tags/list?n=&last= ``` Return a portion of the tags for the specified repository. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -1496,12 +1459,9 @@ The following parameters should be specified on the request: |`n`|query|Limit the number of entries in each response. If not present, all entries will be returned.| |`last`|query|Result set will include values lexically after last.| - - - ###### On Success: OK -``` +```none 200 OK Content-Length: Link: <?n=&last=>; rel="next" @@ -1525,12 +1485,9 @@ The following headers will be returned with the response: |`Content-Length`|Length of the JSON response body.| |`Link`|RFC5988 compliant rel='next' with URL to next result set, if available| - - - ###### On Failure: Invalid pagination number -``` +```none 400 Bad Request Content-Type: application/json @@ -1548,19 +1505,15 @@ Content-Type: application/json The received parameter n was invalid in some way, as described by the error code. The client should resolve the issue and retry the request. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, or "n" is negative. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -1587,19 +1540,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -1624,19 +1573,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -1661,19 +1606,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -1698,39 +1639,26 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - - ### Manifest Create, update, delete and retrieve manifests. - - #### GET Manifest Fetch the manifest identified by `name` and `reference` where `reference` can be a tag or digest. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. - - -``` +```none GET /v2//manifests/ Host: Authorization: ``` - - - The following parameters should be specified on the request: |Name|Kind|Description| @@ -1740,12 +1668,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`reference`|path|Tag or digest of the target manifest.| - - - ###### On Success: OK -``` +```none 200 OK Docker-Content-Digest: Content-Type: @@ -1772,12 +1697,9 @@ The following headers will be returned with the response: |----|-----------| |`Docker-Content-Digest`|Digest of the targeted content for the request.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -1795,8 +1717,6 @@ Content-Type: application/json The name or reference was invalid. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -1804,11 +1724,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -1835,19 +1753,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -1872,19 +1786,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -1909,19 +1819,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -1946,24 +1852,17 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - #### PUT Manifest Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest. - - -``` +```none PUT /v2//manifests/ Host: Authorization: @@ -1983,9 +1882,6 @@ Content-Type: } ``` - - - The following parameters should be specified on the request: |Name|Kind|Description| @@ -1995,12 +1891,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`reference`|path|Tag or digest of the target manifest.| - - - ###### On Success: Created -``` +```none 201 Created Location: Content-Length: 0 @@ -2017,12 +1910,9 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Content-Digest`|Digest of the targeted content for the request.| - - - ###### On Failure: Invalid Manifest -``` +```none 400 Bad Request Content-Type: application/json @@ -2040,8 +1930,6 @@ Content-Type: application/json The received manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2052,11 +1940,9 @@ The error codes that may be included in the response body are enumerated below: | `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -2083,19 +1969,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -2120,19 +2002,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -2157,19 +2035,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -2194,19 +2068,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ###### On Failure: Missing Layer(s) -``` +```none 400 Bad Request Content-Type: application/json @@ -2226,50 +2096,36 @@ Content-Type: application/json One or more layers may be missing during a manifest upload. If so, the missing layers will be enumerated in the error response. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | - - ###### On Failure: Not allowed -``` +```none 405 Method Not Allowed ``` Manifest put is not allowed because the registry is configured as a pull-through cache or for some other reason - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | - - - #### DELETE Manifest Delete the manifest or tag identified by `name` and `reference` where `reference` can be a tag or digest. Note that a manifest can _only_ be deleted by digest. - - -``` +```none DELETE /v2//manifests/ Host: Authorization: ``` - - - The following parameters should be specified on the request: |Name|Kind|Description| @@ -2279,23 +2135,15 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`reference`|path|Tag or digest of the target manifest.| - - - ###### On Success: Accepted -``` +```none 202 Accepted ``` - - - - - ###### On Failure: Invalid Name or Reference -``` +```none 400 Bad Request Content-Type: application/json @@ -2313,8 +2161,6 @@ Content-Type: application/json The specified `name` or `reference` were invalid and the delete was unable to proceed. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2322,11 +2168,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -2353,19 +2197,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -2390,19 +2230,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -2427,19 +2263,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -2464,19 +2296,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ###### On Failure: Unknown Manifest -``` +```none 404 Not Found Content-Type: application/json @@ -2494,8 +2322,6 @@ Content-Type: application/json The specified `name` or `reference` are unknown to the registry and the delete was unable to proceed. Clients can assume the manifest or tag was already deleted if this response is returned. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2503,50 +2329,36 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository. | - - ###### On Failure: Not allowed -``` +```none 405 Method Not Allowed ``` Manifest or tag delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | - - - - ### Blob Operations on blobs identified by `name` and `digest`. Used to fetch or delete layers by digest. - - #### GET Blob Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. - ##### Fetch Blob -``` +```none GET /v2//blobs/ Host: Authorization: ``` - - - The following parameters should be specified on the request: |Name|Kind|Description| @@ -2556,12 +2368,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`digest`|path|Digest of desired blob.| - - - ###### On Success: OK -``` +```none 200 OK Content-Length: Docker-Content-Digest: @@ -2581,7 +2390,7 @@ The following headers will be returned with the response: ###### On Success: Temporary Redirect -``` +```none 307 Temporary Redirect Location: Docker-Content-Digest: @@ -2596,12 +2405,9 @@ The following headers will be returned with the response: |`Location`|The location where the layer should be accessible.| |`Docker-Content-Digest`|Digest of the targeted content for the request.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -2619,8 +2425,6 @@ Content-Type: application/json There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2628,11 +2432,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -2650,8 +2452,6 @@ Content-Type: application/json The blob, identified by `name` and `digest`, is unknown to the registry. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2659,11 +2459,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -2690,19 +2488,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -2727,19 +2521,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -2764,19 +2554,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -2801,19 +2587,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ##### Fetch Blob Part -``` +```none GET /v2//blobs/ Host: Authorization: @@ -2822,7 +2604,6 @@ Range: bytes=- This endpoint may also support RFC7233 compliant range requests. Support can be detected by issuing a HEAD request. If the header `Accept-Range: bytes` is returned, range requests can be used to fetch partial content. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -2833,12 +2614,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`digest`|path|Digest of desired blob.| - - - ###### On Success: Partial Content -``` +```none 206 Partial Content Content-Length: Content-Range: bytes -/ @@ -2856,12 +2634,9 @@ The following headers will be returned with the response: |`Content-Length`|The length of the requested blob chunk.| |`Content-Range`|Content range of blob chunk.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -2879,8 +2654,6 @@ Content-Type: application/json There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2888,11 +2661,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -2908,10 +2679,6 @@ Content-Type: application/json } ``` - - - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -2919,21 +2686,17 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | - - ###### On Failure: Requested Range Not Satisfiable -``` +```none 416 Requested Range Not Satisfiable ``` The range specification cannot be satisfied for the requested content. This can happen when the range is not formatted correctly or if the range is outside of the valid size of the content. - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -2960,19 +2723,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -2997,19 +2756,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -3034,19 +2789,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -3071,32 +2822,22 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - #### DELETE Blob Delete the blob identified by `name` and `digest` - - -``` +```none DELETE /v2//blobs/ Host: Authorization: ``` - - - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3106,19 +2847,14 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`digest`|path|Digest of desired blob.| - - - ###### On Success: Accepted -``` +```none 202 Accepted Content-Length: 0 Docker-Content-Digest: ``` - - The following headers will be returned with the response: |Name|Description| @@ -3126,19 +2862,12 @@ The following headers will be returned with the response: |`Content-Length`|0| |`Docker-Content-Digest`|Digest of the targeted content for the request.| - - - ###### On Failure: Invalid Name or Digest -``` +```none 400 Bad Request ``` - - - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3146,11 +2875,9 @@ The error codes that may be included in the response body are enumerated below: | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -3168,8 +2895,6 @@ Content-Type: application/json The blob, identified by `name` and `digest`, is unknown to the registry. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3177,11 +2902,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | | `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. | - - ###### On Failure: Method Not Allowed -``` +```none 405 Method Not Allowed Content-Type: application/json @@ -3199,19 +2922,15 @@ Content-Type: application/json Blob delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -3238,19 +2957,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -3275,19 +2990,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -3312,19 +3023,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -3349,32 +3056,23 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - - ### Initiate Blob Upload Initiate a blob upload. This endpoint can be used to create resumable uploads or monolithic uploads. - - #### POST Initiate Blob Upload Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request. - ##### Initiate Monolithic Blob Upload -``` +```none POST /v2//blobs/uploads/?digest= Host: Authorization: @@ -3386,7 +3084,6 @@ Content-Type: application/octet-stream Upload a blob identified by the `digest` parameter in single request. This upload will not be resumable unless a recoverable error is returned. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3397,12 +3094,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`digest`|query|Digest of uploaded blob. If present, the upload will be completed, in a single request, with contents of the request body as the resulting blob.| - - - ###### On Success: Created -``` +```none 201 Created Location: Content-Length: 0 @@ -3419,19 +3113,12 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| - - - ###### On Failure: Invalid Name or Digest -``` +```none 400 Bad Request ``` - - - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3439,29 +3126,23 @@ The error codes that may be included in the response body are enumerated below: | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | - - ###### On Failure: Not allowed -``` +```none 405 Method Not Allowed ``` Blob upload is not allowed because the registry is configured as a pull-through cache or for some other reason - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -3488,19 +3169,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -3525,19 +3202,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -3562,19 +3235,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -3599,19 +3268,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ##### Initiate Resumable Blob Upload -``` +```none POST /v2//blobs/uploads/ Host: Authorization: @@ -3620,7 +3285,6 @@ Content-Length: 0 Initiate a resumable blob upload with an empty request body. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3630,12 +3294,9 @@ The following parameters should be specified on the request: |`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.| |`name`|path|Name of the target repository.| - - - ###### On Success: Accepted -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: 0- @@ -3654,19 +3315,12 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| - - - ###### On Failure: Invalid Name or Digest -``` +```none 400 Bad Request ``` - - - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3674,11 +3328,9 @@ The error codes that may be included in the response body are enumerated below: | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -3705,19 +3357,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -3742,19 +3390,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -3779,19 +3423,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -3816,19 +3456,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ##### Mount Blob -``` +```none POST /v2//blobs/uploads/?mount=&from= Host: Authorization: @@ -3837,7 +3473,6 @@ Content-Length: 0 Mount a blob identified by the `mount` parameter from another repository. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -3849,12 +3484,9 @@ The following parameters should be specified on the request: |`mount`|query|Digest of blob to mount from the source repository.| |`from`|query|Name of the source repository.| - - - ###### On Success: Created -``` +```none 201 Created Location: Content-Length: 0 @@ -3871,19 +3503,12 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| - - - ###### On Failure: Invalid Name or Digest -``` +```none 400 Bad Request ``` - - - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -3891,29 +3516,23 @@ The error codes that may be included in the response body are enumerated below: | `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. | | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | - - ###### On Failure: Not allowed -``` +```none 405 Method Not Allowed ``` Blob mount is not allowed because the registry is configured as a pull-through cache or for some other reason - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -3940,19 +3559,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -3977,19 +3592,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -4014,19 +3625,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -4051,31 +3658,21 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - - ### Blob Upload Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests. The `Location` header and its parameters should be preserved by clients, using the latest value returned via upload related API calls. - - #### GET Blob Upload Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. - - -``` +```none GET /v2//blobs/uploads/ Host: Authorization: @@ -4083,7 +3680,6 @@ Authorization: Retrieve the progress of the current upload, as reported by the `Range` header. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4093,12 +3689,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.| - - - ###### On Success: Upload Progress -``` +```none 204 No Content Range: 0- Content-Length: 0 @@ -4115,12 +3708,9 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -4138,8 +3728,6 @@ Content-Type: application/json There was an error processing the upload and it must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -4148,11 +3736,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -4170,19 +3756,15 @@ Content-Type: application/json The upload is unknown to the registry. The upload must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -4209,19 +3791,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -4246,19 +3824,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -4283,19 +3857,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -4320,25 +3890,19 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - #### PATCH Blob Upload Upload a chunk of data for the specified upload. - ##### Stream upload -``` +```none PATCH /v2//blobs/uploads/ Host: Authorization: @@ -4349,7 +3913,6 @@ Content-Type: application/octet-stream Upload a stream of data to upload without completing the upload. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4359,12 +3922,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.| - - - ###### On Success: Data Accepted -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: 0- @@ -4383,12 +3943,9 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -4406,8 +3963,6 @@ Content-Type: application/json There was an error processing the upload and it must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -4416,11 +3971,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -4438,19 +3991,15 @@ Content-Type: application/json The upload is unknown to the registry. The upload must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -4477,19 +4026,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -4514,19 +4059,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -4551,19 +4092,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -4588,19 +4125,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - ##### Chunked upload -``` +```none PATCH /v2//blobs/uploads/ Host: Authorization: @@ -4613,7 +4146,6 @@ Content-Type: application/octet-stream Upload a chunk of data to specified upload without completing the upload. The data will be uploaded to the specified Content Range. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4625,12 +4157,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.| - - - ###### On Success: Chunk Accepted -``` +```none 202 Accepted Location: /v2//blobs/uploads/ Range: 0- @@ -4649,12 +4178,9 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -4672,8 +4198,6 @@ Content-Type: application/json There was an error processing the upload and it must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -4682,11 +4206,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -4704,29 +4226,23 @@ Content-Type: application/json The upload is unknown to the registry. The upload must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | - - ###### On Failure: Requested Range Not Satisfiable -``` +```none 416 Requested Range Not Satisfiable ``` The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid. - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -4753,19 +4269,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -4790,19 +4302,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -4827,19 +4335,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -4864,24 +4368,17 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - #### PUT Blob Upload Complete the upload specified by `uuid`, optionally appending the body as the final chunk. - - -``` +```none PUT /v2//blobs/uploads/?digest= Host: Authorization: @@ -4893,7 +4390,6 @@ Content-Type: application/octet-stream Complete the upload, providing all the data in the body, if necessary. A request without a body will just complete the upload with previously uploaded content. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -4905,12 +4401,9 @@ The following parameters should be specified on the request: |`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.| |`digest`|query|Digest of uploaded blob.| - - - ###### On Success: Upload Complete -``` +```none 201 Created Location: Content-Range: - @@ -4929,12 +4422,9 @@ The following headers will be returned with the response: |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| |`Docker-Content-Digest`|Digest of the targeted content for the request.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -4952,8 +4442,6 @@ Content-Type: application/json There was an error processing the upload and it must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -4963,11 +4451,9 @@ The error codes that may be included in the response body are enumerated below: | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | | `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -4985,19 +4471,15 @@ Content-Type: application/json The upload is unknown to the registry. The upload must be restarted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -5024,19 +4506,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -5061,19 +4539,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -5098,19 +4572,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -5135,24 +4605,17 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - #### DELETE Blob Upload Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. - - -``` +```none DELETE /v2//blobs/uploads/ Host: Authorization: @@ -5161,7 +4624,6 @@ Content-Length: 0 Cancel the upload specified by `uuid`. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -5172,12 +4634,9 @@ The following parameters should be specified on the request: |`name`|path|Name of the target repository.| |`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.| - - - ###### On Success: Upload Deleted -``` +```none 204 No Content Content-Length: 0 ``` @@ -5190,12 +4649,9 @@ The following headers will be returned with the response: |----|-----------| |`Content-Length`|The `Content-Length` header must be zero and the body must be empty.| - - - ###### On Failure: Bad Request -``` +```none 400 Bad Request Content-Type: application/json @@ -5213,8 +4669,6 @@ Content-Type: application/json An error was encountered processing the delete. The client may ignore this error. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| @@ -5222,11 +4676,9 @@ The error codes that may be included in the response body are enumerated below: | `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. | | `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. | - - ###### On Failure: Not Found -``` +```none 404 Not Found Content-Type: application/json @@ -5244,19 +4696,15 @@ Content-Type: application/json The upload is unknown to the registry. The client may ignore this error and assume the upload has been deleted. - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. | - - ###### On Failure: Authentication Required -``` +```none 401 Unauthorized WWW-Authenticate: realm="", ..." Content-Length: @@ -5283,19 +4731,15 @@ The following headers will be returned on the response: |`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. | - - ###### On Failure: No Such Repository Error -``` +```none 404 Not Found Content-Length: Content-Type: application/json @@ -5320,19 +4764,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. | - - ###### On Failure: Access Denied -``` +```none 403 Forbidden Content-Length: Content-Type: application/json @@ -5357,19 +4797,15 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. | - - ###### On Failure: Too Many Requests -``` +```none 429 Too Many Requests Content-Length: Content-Type: application/json @@ -5394,44 +4830,31 @@ The following headers will be returned on the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - The error codes that may be included in the response body are enumerated below: |Code|Message|Description| |----|-------|-----------| | `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times | - - - - ### Catalog List a set of available repositories in the local registry cluster. Does not provide any indication of what may be available upstream. Applications can only determine if a repository is available but not if it is not available. - - #### GET Catalog Retrieve a sorted, json list of repositories available in the registry. - ##### Catalog Fetch -``` +```none GET /v2/_catalog ``` Request an unabridged list of repositories available. The implementation may impose a maximum limit and return a partial set with pagination links. - - - - ###### On Success: OK -``` +```none 200 OK Content-Length: Content-Type: application/json @@ -5452,17 +4875,14 @@ The following headers will be returned with the response: |----|-----------| |`Content-Length`|Length of the JSON response body.| - - ##### Catalog Fetch Paginated -``` +```none GET /v2/_catalog?n=&last= ``` Return the specified portion of repositories. - The following parameters should be specified on the request: |Name|Kind|Description| @@ -5470,12 +4890,9 @@ The following parameters should be specified on the request: |`n`|query|Limit the number of entries in each response. It not present, 100 entries will be returned.| |`last`|query|Result set will include values lexically after last.| - - - ###### On Success: OK -``` +```none 200 OK Content-Length: Link: <?n=&last=>; rel="next" @@ -5490,16 +4907,9 @@ Content-Type: application/json } ``` - - The following headers will be returned with the response: |Name|Description| |----|-----------| |`Content-Length`|Length of the JSON response body.| |`Link`|RFC5988 compliant rel='next' with URL to next result set, if available| - - - - - diff --git a/docs/content/spec/api.md.tmpl b/docs/content/spec/api.md.tmpl index 7629d236..fc053212 100644 --- a/docs/content/spec/api.md.tmpl +++ b/docs/content/spec/api.md.tmpl @@ -2,7 +2,7 @@ title: "HTTP API V2" description: "Specification for the Registry API." keywords: registry, on-prem, images, tags, repository, distribution, api, advanced -redirect_from: +aliases: - /reference/api/registry_api/ --- diff --git a/docs/content/spec/auth/_index.md b/docs/content/spec/auth/_index.md index 8c4bf5e2..719c430c 100644 --- a/docs/content/spec/auth/_index.md +++ b/docs/content/spec/auth/_index.md @@ -6,7 +6,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, authenticat # Docker Registry v2 authentication -See the [Token Authentication Specification](token.md), -[Token Authentication Implementation](jwt.md), -[Token Scope Documentation](scope.md), -[OAuth2 Token Authentication](oauth.md) for more information. +See the [Token Authentication Specification](token), +[Token Authentication Implementation](jwt), +[Token Scope Documentation](scope), +[OAuth2 Token Authentication](oauth) for more information. diff --git a/docs/content/spec/auth/oauth.md b/docs/content/spec/auth/oauth.md index ee08b992..93c43e8a 100644 --- a/docs/content/spec/auth/oauth.md +++ b/docs/content/spec/auth/oauth.md @@ -12,7 +12,7 @@ reference for the protocol and HTTP endpoints described here. **Note**: Not all token servers implement oauth2. If the request to the endpoint returns `404` using the HTTP `POST` method, refer to -[Token Documentation](token.md) for using the HTTP `GET` method supported by all +[Token Documentation](../token) for using the HTTP `GET` method supported by all token servers. ## Refresh token format @@ -161,7 +161,7 @@ Content-Type: application/x-www-form-urlencoded #### Example getting refresh token -``` +```none POST /token HTTP/1.1 Host: auth.docker.io Content-Type: application/x-www-form-urlencoded @@ -176,7 +176,7 @@ Content-Type: application/json #### Example refreshing an Access Token -``` +```none POST /token HTTP/1.1 Host: auth.docker.io Content-Type: application/x-www-form-urlencoded diff --git a/docs/content/spec/auth/scope.md b/docs/content/spec/auth/scope.md index e162c3f2..19ba0b27 100644 --- a/docs/content/spec/auth/scope.md +++ b/docs/content/spec/auth/scope.md @@ -41,10 +41,11 @@ is authorized for a specific resource. #### Resource Class -> [!WARNING] -> Resource Class is deprecated and ignored. -> `repository` and `repository(plugin)` are considered equal when authorizing a token. -> Authorization services should no longer return scopes with a resource class. +{{< hint type=warning >}} +Resource Class is deprecated and ignored. +`repository` and `repository(plugin)` are considered equal when authorizing a token. +Authorization services should no longer return scopes with a resource class. +{{< /hint >}} The resource type might have a resource class which further classifies the the resource name within the resource type. A class is not required and @@ -108,11 +109,13 @@ Full reference grammar is defined [here](https://pkg.go.dev/github.com/distribution/distribution/reference). Currently the scope name grammar is a subset of the reference grammar. -> **NOTE:** that the `resourcename` may contain one `:` due to a possible port -> number in the hostname component of the `resourcename`, so a naive -> implementation that interprets the first three `:`-delimited tokens of a -> `scope` to be the `resourcetype`, `resourcename`, and a list of `action` -> would be insufficient. +{{< hint type=note >}} +Note that the `resourcename` may contain one `:` due to a possible port +number in the hostname component of the `resourcename`, so a naive +implementation that interprets the first three `:`-delimited tokens of a +`scope` to be the `resourcetype`, `resourcename`, and a list of `action` +would be insufficient. +{{< /hint >}} ## Resource Provider Use @@ -141,7 +144,7 @@ Each JWT access token may only have a single subject and audience but multiple resource scopes. The subject and audience are put into standard JWT fields `sub` and `aud`. The resource scope is put into the `access` field. The structure of the access field can be seen in the -[jwt documentation](jwt.md). +[jwt documentation](../jwt). ## Refresh Tokens diff --git a/docs/content/spec/auth/token.md b/docs/content/spec/auth/token.md index cdee7845..a3484107 100644 --- a/docs/content/spec/auth/token.md +++ b/docs/content/spec/auth/token.md @@ -8,7 +8,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, Bearer auth This document outlines the v2 Docker registry authentication scheme: -![v2 registry auth](../images/v2-registry-auth.png) +![v2 registry auth](/images/v2-registry-auth.png) 1. Attempt to begin a push/pull operation with the registry. 2. If the registry requires authorization it will return a `401 Unauthorized` @@ -191,7 +191,7 @@ https://auth.docker.io/token?service=registry.docker.io&scope=repository:samalba The token server should first attempt to authenticate the client using any authentication credentials provided with the request. From Docker 1.11 the -Docker engine supports both Basic Authentication and [OAuth2](oauth.md) for +Docker engine supports both Basic Authentication and [OAuth2](../oauth) for getting tokens. Docker 1.10 and before, the registry client in the Docker Engine only supports Basic Authentication. If an attempt to authenticate to the token server fails, the token server should return a `401 Unauthorized` response diff --git a/docs/content/spec/deprecated-schema-v1.md b/docs/content/spec/deprecated-schema-v1.md index b9a35302..3c56d579 100644 --- a/docs/content/spec/deprecated-schema-v1.md +++ b/docs/content/spec/deprecated-schema-v1.md @@ -1,10 +1,9 @@ --- -title: Update deprecated schema image manifest version 2, v1 images -description: Update deprecated schema v1 iamges +title: Image manifest version 2, schema 1 +description: Update deprecated schema v1 images keywords: registry, on-prem, images, tags, repository, distribution, api, advanced, manifest --- -## Image manifest version 2, schema 1 With the release of image manifest version 2, schema 2, image manifest version 2, schema 1 has been deprecated. This could lead to compatibility and vulnerability issues in images that haven't been updated to image manifest @@ -17,7 +16,7 @@ associated with the deprecated image manifest that will block your image from running successfully. A list of possible methods to help update your image is also included below. -### Update to image manifest version 2, schema 2 +## Update to image manifest version 2, schema 2 One way to upgrade an image from image manifest version 2, schema 1 to schema 2 is to `docker pull` the image and then `docker push` the image with a @@ -29,8 +28,7 @@ manifest format, but does not update the contents within the image. Images using manifest version 2, schema 1 may contain unpatched vulnerabilities. We recommend looking for an alternative image or rebuilding it. - -### Update FROM statement +## Update FROM statement You can rebuild the image by updating the `FROM` statement in your `Dockerfile`. If your image manifest is out-of-date, there is a chance the diff --git a/docs/content/spec/implementations.md b/docs/content/spec/implementations.md index cd042838..e4f5f9d5 100644 --- a/docs/content/spec/implementations.md +++ b/docs/content/spec/implementations.md @@ -1,5 +1,5 @@ --- -published: false +draft: true --- # Distribution API Implementations diff --git a/docs/content/spec/json.md b/docs/content/spec/json.md index 825b17ac..7f8d3d57 100644 --- a/docs/content/spec/json.md +++ b/docs/content/spec/json.md @@ -1,5 +1,5 @@ --- -published: false +draft: true title: "Docker Distribution JSON Canonicalization" description: "Explains registry JSON objects" keywords: ["registry, service, images, repository, json"] diff --git a/docs/content/spec/manifest-v2-2.md b/docs/content/spec/manifest-v2-2.md index 5da1d0ad..1e85fad7 100644 --- a/docs/content/spec/manifest-v2-2.md +++ b/docs/content/spec/manifest-v2-2.md @@ -1,5 +1,5 @@ --- -title: "Image Manifest V 2, Schema 2 " +title: "Image Manifest V 2, Schema 2" description: "image manifest for the Registry." keywords: registry, on-prem, images, tags, repository, distribution, api, advanced, manifest --- @@ -10,7 +10,7 @@ This document outlines the format of the V2 image manifest, schema version 2. The original (and provisional) image manifest for V2 (schema 1), was introduced in the Docker daemon in the [v1.3.0 release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453) -and is specified in the [schema 1 manifest definition](manifest-v2-1.md) +and is now deprecated. This second schema version has two primary goals. The first is to allow multi-architecture images, through a "fat manifest" which references image @@ -71,7 +71,7 @@ image manifest based on the Content-Type returned in the HTTP response. - **`digest`** *string* The digest of the content, as defined by the - [Registry V2 HTTP API Specificiation](api.md#digest-parameter). + [Registry V2 HTTP API Specificiation](../api#digest-parameter). - **`platform`** *object* @@ -113,7 +113,8 @@ image manifest based on the Content-Type returned in the HTTP response. ## Example Manifest List -*Example showing a simple manifest list pointing to image manifests for two platforms:* +Example showing a simple manifest list pointing to image manifests for two platforms: + ```json { "schemaVersion": 2, @@ -186,7 +187,7 @@ image. It's the direct replacement for the schema-1 manifest. - **`digest`** *string* The digest of the content, as defined by the - [Registry V2 HTTP API Specificiation](api.md#digest-parameter). + [Registry V2 HTTP API Specificiation](../api#digest-parameter). - **`layers`** *array* @@ -212,7 +213,7 @@ image. It's the direct replacement for the schema-1 manifest. - **`digest`** *string* The digest of the content, as defined by the - [Registry V2 HTTP API Specificiation](api.md#digest-parameter). + [Registry V2 HTTP API Specificiation](../api#digest-parameter). - **`urls`** *array* @@ -222,7 +223,8 @@ image. It's the direct replacement for the schema-1 manifest. ## Example Image Manifest -*Example showing an image manifest:* +Example showing an image manifest: + ```json { "schemaVersion": 2, diff --git a/docs/content/spec/menu.md b/docs/content/spec/menu.md deleted file mode 100644 index 7e52d8d7..00000000 --- a/docs/content/spec/menu.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Reference" -description: "Explains registry JSON objects" -keywords: registry, service, images, repository, json -type: "menu" -identifier: "smn_registry_ref" ---- diff --git a/docs/content/storage-drivers/_index.md b/docs/content/storage-drivers/_index.md index f7fc4b42..f9face2d 100644 --- a/docs/content/storage-drivers/_index.md +++ b/docs/content/storage-drivers/_index.md @@ -1,8 +1,6 @@ --- description: Explains how to use storage drivers keywords: registry, on-prem, images, tags, repository, distribution, storage drivers, advanced -redirect_from: -- /registry/storagedrivers/ title: Registry storage driver --- @@ -12,11 +10,11 @@ This document describes the registry storage driver model, implementation, and e This storage driver package comes bundled with several drivers: -- [inmemory](inmemory.md): A temporary storage driver using a local inmemory map. This exists solely for reference and testing. -- [filesystem](filesystem.md): A local storage driver configured to use a directory tree in the local filesystem. -- [s3](s3.md): A driver storing objects in an Amazon Simple Storage Service (S3) bucket. -- [azure](azure.md): A driver storing objects in [Microsoft Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/). -- [gcs](gcs.md): A driver storing objects in a [Google Cloud Storage](https://cloud.google.com/storage/) bucket. +- [inmemory](inmemory): A temporary storage driver using a local inmemory map. This exists solely for reference and testing. +- [filesystem](filesystem): A local storage driver configured to use a directory tree in the local filesystem. +- [s3](s3): A driver storing objects in an Amazon Simple Storage Service (S3) bucket. +- [azure](azure): A driver storing objects in [Microsoft Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/). +- [gcs](gcs): A driver storing objects in a [Google Cloud Storage](https://cloud.google.com/storage/) bucket. - oss: *NO LONGER SUPPORTED* - swift: *NO LONGER SUPPORTED* @@ -41,16 +39,17 @@ with a driver name and parameters map. If no such storage driver can be found, ## Driver contribution New storage drivers are not currently being accepted. -See https://github.com/distribution/distribution/issues/3988 for discussion. +See for discussion. There are forks of this repo that implement custom storage drivers. These are not supported by the OCI distribution project. The known forks are: -- Storj DCS: https://github.com/storj/docker-registry -- HuaweiCloud OBS: https://github.com/setoru/distribution/tree/obs -- us3: https://github.com/lambertxiao/distribution/tree/main -- Baidu BOS: https://github.com/dolfly/distribution/tree/bos -- HDFS: https://github.com/haosdent/distribution/tree/master + +- Storj DCS: +- HuaweiCloud OBS: +- us3: +- Baidu BOS: +- HDFS: ### Writing new storage drivers diff --git a/docs/content/storage-drivers/gcs.md b/docs/content/storage-drivers/gcs.md index 624ea616..f970b73e 100644 --- a/docs/content/storage-drivers/gcs.md +++ b/docs/content/storage-drivers/gcs.md @@ -15,5 +15,6 @@ An implementation of the `storagedriver.StorageDriver` interface which uses Goog | `rootdirectory` | no | The root directory tree in which all registry files are stored. Defaults to the empty string (bucket root). If a prefix is used, the path `bucketname/` has to be pre-created before starting the registry. The prefix is applied to all Google Cloud Storage keys to allow you to segment data in your bucket if necessary.| | `chunksize` | no (default 5242880) | This is the chunk size used for uploading large blobs, must be a multiple of 256*1024. | -**Note:** Instead of a key file you can use [Google Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). - +{{< hint type=note >}} +Instead of a key file you can use [Google Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). +{{< /hint >}} diff --git a/docs/content/storage-drivers/inmemory.md b/docs/content/storage-drivers/inmemory.md index b4bdaeed..ba9cd93e 100644 --- a/docs/content/storage-drivers/inmemory.md +++ b/docs/content/storage-drivers/inmemory.md @@ -7,9 +7,11 @@ title: In-memory storage driver (testing only) For purely tests purposes, you can use the `inmemory` storage driver. This driver is an implementation of the `storagedriver.StorageDriver` interface which uses local memory for object storage. If you would like to run a registry from -volatile memory, use the [`filesystem` driver](filesystem.md) on a ramdisk. +volatile memory, use the [`filesystem` driver](../filesystem) on a ramdisk. -**IMPORTANT**: This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production. +{{< hint type=important >}} +This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production. +{{< /hint >}} ## Parameters diff --git a/docs/content/storage-drivers/s3.md b/docs/content/storage-drivers/s3.md index fa9ab72d..491ed5ff 100644 --- a/docs/content/storage-drivers/s3.md +++ b/docs/content/storage-drivers/s3.md @@ -11,8 +11,8 @@ Amazon S3 or S3 compatible services for object storage. | Parameter | Required | Description | |:--------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `accesskey` | no | Your AWS Access Key. If you use [IAM roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. | -| `secretkey` | no | Your AWS Secret Key. If you use [IAM roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. | +| `accesskey` | no | Your AWS Access Key. If you use [IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. | +| `secretkey` | no | Your AWS Secret Key. If you use [IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. | | `region` | yes | The AWS region in which your bucket exists. | | `regionendpoint` | no | Endpoint for S3 compatible storage services (Minio, etc). | | `forcepathstyle` | no | To enable path-style addressing when the value is set to `true`. The default is `true`. | @@ -30,10 +30,10 @@ Amazon S3 or S3 compatible services for object storage. > **Note** You can provide empty strings for your access and secret keys to run the driver > on an ec2 instance and handles authentication with the instance's credentials. If you -> use [IAM roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), +> use [IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), > omit these keys to fetch temporary credentials from IAM. -`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, see [Regions, Availability Zones, and Local Zones](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). +`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, see [Regions, Availability Zones, and Local Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). `regionendpoint`: (optional) Endpoint URL for S3 compatible APIs. This should not be provided when using Amazon S3. @@ -55,7 +55,7 @@ Amazon S3 or S3 compatible services for object storage. `storageclass`: (optional) The storage class applied to each registry file. Defaults to STANDARD. Valid options are STANDARD and REDUCED_REDUNDANCY. -`objectacl`: (optional) The canned object ACL to be applied to each registry object. Defaults to `private`. If you are using a bucket owned by another AWS account, it is recommended that you set this to `bucket-owner-full-control` so that the bucket owner can access your objects. Other valid options are available in the [AWS S3 documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl). +`objectacl`: (optional) The canned object ACL to be applied to each registry object. Defaults to `private`. If you are using a bucket owned by another AWS account, it is recommended that you set this to `bucket-owner-full-control` so that the bucket owner can access your objects. Other valid options are available in the [AWS S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl). `loglevel`: (optional) Valid values are: `off` (default), `debug`, `debugwithsigning`, `debugwithhttpbody`, `debugwithrequestretries`, `debugwithrequesterrors` and `debugwitheventstreambody`. See the [AWS SDK for Go API reference](https://docs.aws.amazon.com/sdk-for-go/api/aws/#LogLevelType) for details. @@ -91,7 +91,7 @@ The following AWS policy is required by the registry for push and pull. Make sur } ``` -See [the S3 policy documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html) for more details. +See [the S3 policy documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html) for more details. # CloudFront as Middleware with S3 backend @@ -112,7 +112,7 @@ to see whether you need CloudFront or S3 Transfer Acceleration. If you are unfamiliar with creating a CloudFront distribution, see [Getting Started with -Cloudfront](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html). +Cloudfront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html). Defaults can be kept in most areas except: @@ -162,4 +162,4 @@ middleware: A CloudFront key-pair is required for all AWS accounts needing access to your CloudFront distribution. You must have access to your AWS account's root credentials to create the required Cloudfront keypair. For information, see [Creating CloudFront Key -Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). +Pairs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). diff --git a/docs/hugo.yaml b/docs/hugo.yaml index 02b64590..b307411d 100644 --- a/docs/hugo.yaml +++ b/docs/hugo.yaml @@ -1,4 +1,4 @@ -baseURL: https://example.com/ +baseURL: / languageCode: en-us title: CNCF Distribution theme: hugo-geekdoc diff --git a/docs/content/images/notifications.gliffy b/docs/static/images/notifications.gliffy similarity index 100% rename from docs/content/images/notifications.gliffy rename to docs/static/images/notifications.gliffy diff --git a/docs/content/images/notifications.png b/docs/static/images/notifications.png similarity index 100% rename from docs/content/images/notifications.png rename to docs/static/images/notifications.png diff --git a/docs/content/images/notifications.svg b/docs/static/images/notifications.svg similarity index 100% rename from docs/content/images/notifications.svg rename to docs/static/images/notifications.svg diff --git a/docs/content/images/v2-registry-auth.png b/docs/static/images/v2-registry-auth.png similarity index 100% rename from docs/content/images/v2-registry-auth.png rename to docs/static/images/v2-registry-auth.png