From 83dd4ff0a6cf56ed205c7ee80923cd55f3b9c44a Mon Sep 17 00:00:00 2001 From: James Hewitt Date: Thu, 12 Oct 2023 11:39:36 +0100 Subject: [PATCH] Cleanup of naming in docs Signed-off-by: James Hewitt --- BUILDING.md | 2 +- GOVERNANCE.md | 2 +- doc.go | 2 +- docs/content/_index.md | 18 +++++++++++------- docs/content/about/_index.md | 8 ++++---- docs/content/about/configuration.md | 2 +- docs/content/about/deploying.md | 2 +- docs/content/about/deprecated.md | 20 -------------------- docs/content/about/garbage-collection.md | 2 +- docs/content/about/glossary.md | 2 +- docs/content/recipes/mirror.md | 12 ++++-------- docs/content/recipes/systemd.md | 4 ++-- docs/content/spec/auth/_index.md | 6 +++--- docs/content/spec/auth/jwt.md | 4 ++-- docs/content/spec/auth/oauth.md | 4 ++-- docs/content/spec/auth/scope.md | 2 +- docs/content/spec/auth/token.md | 17 +++++++---------- docs/content/spec/implementations.md | 4 ++-- docs/content/spec/json.md | 6 +++--- releases/README.md | 2 +- 20 files changed, 49 insertions(+), 72 deletions(-) delete mode 100644 docs/content/about/deprecated.md diff --git a/BUILDING.md b/BUILDING.md index aa1bcff00..8e3cf3d40 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -7,7 +7,7 @@ This is useful if you intend to actively work on the registry. ### Alternatives -Most people should use the [official Registry docker image](https://hub.docker.com/r/library/registry/). +Most people should use prebuilt images, for example, the [Registry docker image](https://hub.docker.com/r/library/registry/) provided by Docker. People looking for advanced operational use cases might consider rolling their own image with a custom Dockerfile inheriting `FROM registry:2`. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index bd40c44af..17067f7a8 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -94,7 +94,7 @@ performance must not be discussed on the pull request. ## How are decisions made? -Docker distribution is an open-source project with an open design philosophy. +CNCF distribution is an open-source project with an open design philosophy. This means that the repository is the source of truth for EVERY aspect of the project, including its philosophy, design, road map, and APIs. *If it's part of the project, it's in the repo. If it's in the repo, it's part of the project.* diff --git a/doc.go b/doc.go index bdd8cb708..d28c892df 100644 --- a/doc.go +++ b/doc.go @@ -1,6 +1,6 @@ // Package distribution will define the interfaces for the components of // docker distribution. The goal is to allow users to reliably package, ship -// and store content related to docker images. +// and store content related to container images. // // This is currently a work in progress. More details are available in the // README.md. diff --git a/docs/content/_index.md b/docs/content/_index.md index 367ac6ad7..a5de9915e 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -1,13 +1,13 @@ --- description: High-level overview of the Registry keywords: registry, on-prem, images, tags, repository, distribution -title: Docker Registry +title: Distribution Registry --- ## What it is The Registry is a stateless, highly scalable server side application that stores -and lets you distribute Docker images. The Registry is open-source, under the +and lets you distribute container images. The Registry is open-source, under the permissive [Apache license](https://en.wikipedia.org/wiki/Apache_License). ## Why use it @@ -21,13 +21,17 @@ You should use the Registry if you want to: ## Alternatives Users looking for a zero maintenance, ready-to-go solution are encouraged to -head-over to the [Docker Hub](https://hub.docker.com), which provides a -free-to-use, hosted Registry, plus additional features (organization accounts, -automated builds, and more). +use one of the existing registry services. Many of these provide support and security +scanning, and are free for public repositories. For example: +- [Docker Hub](https://hub.docker.com) +- [Quay.io](https://quay.io/) +- [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) -## Requirements +Cloud infrastructure providers such as [AWS](https://aws.amazon.com/ecr/), [Azure](https://azure.microsoft.com/products/container-registry/), [Google Cloud](https://cloud.google.com/artifact-registry) and [IBM Cloud](https://www.ibm.com/products/container-registry) also have container registry services available at a cost. -The Registry is compatible with Docker engine **version 1.6.0 or higher**. +## Compatibility + +The distribution registry implements the [OCI Distribution Spec](https://github.com/opencontainers/distribution-spec) version 1.0.1. ## Basic commands diff --git a/docs/content/about/_index.md b/docs/content/about/_index.md index 80bc4d4f9..e63e1696a 100644 --- a/docs/content/about/_index.md +++ b/docs/content/about/_index.md @@ -4,12 +4,12 @@ keywords: registry, on-prem, images, tags, repository, distribution, use cases, title: About Registry --- -A registry is a storage and content delivery system, holding named Docker +A registry is a storage and content delivery system, holding named container images, available in different tagged versions. > Example: the image `distribution/registry`, with tags `2.0` and `2.1`. -Users interact with a registry by using docker push and pull commands. +Users interact with a registry by pushing and pulling images. > Example: `docker pull registry-1.docker.io/distribution/registry:2.1`. @@ -35,11 +35,11 @@ mostly useful for large installations that want to collect metrics. Image names as used in typical docker commands reflect their origin: - * `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from the official Docker Hub. This is simply a shortcut for the longer `docker pull docker.io/library/ubuntu` command + * `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from Docker Hub. This is simply a shortcut for the longer `docker pull docker.io/library/ubuntu` command * `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](https://docs.docker.com/engine/reference/commandline/cli/). +the [Docker engine documentation](https://docs.docker.com/engine/reference/commandline/cli/). ## Use cases diff --git a/docs/content/about/configuration.md b/docs/content/about/configuration.md index 6c759e13b..3f4cb18e3 100644 --- a/docs/content/about/configuration.md +++ b/docs/content/about/configuration.md @@ -10,7 +10,7 @@ before moving your systems to production. ## Override specific configuration options -In a typical setup where you run your Registry from the official image, you can +In a typical setup where you run your registry as a container, you can specify a configuration variable from the environment by passing `-e` arguments to your `docker run` stanza or from within a Dockerfile using the `ENV` instruction. diff --git a/docs/content/about/deploying.md b/docs/content/about/deploying.md index c94ae6918..1c022bc2e 100644 --- a/docs/content/about/deploying.md +++ b/docs/content/about/deploying.md @@ -401,7 +401,7 @@ authentication to work. {{< /hint >}} {{< hint type=warning >}} -The official registry image **only** supports htpasswd credentials in +The distribution registry **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 >}} diff --git a/docs/content/about/deprecated.md b/docs/content/about/deprecated.md deleted file mode 100644 index 0261cf4d0..000000000 --- a/docs/content/about/deprecated.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: describes deprecated functionality -keywords: registry, manifest, images, signatures, repository, distribution, digest -title: Docker Registry deprecation ---- - -This document details functionality or components which are deprecated within -the registry. - -### v2.5.0 - -The signature store has been removed from the registry. Since `v2.4.0` it has -been possible to configure the registry to generate manifest signatures rather -than load them from storage. In this version of the registry this becomes -the default behavior. Signatures which are attached to manifests on put are -not stored in the registry. This does not alter the functional behavior of -the registry. - -Old signatures blobs can be removed from the registry storage by running the -garbage-collect subcommand. diff --git a/docs/content/about/garbage-collection.md b/docs/content/about/garbage-collection.md index f52d7794f..dd1768d60 100644 --- a/docs/content/about/garbage-collection.md +++ b/docs/content/about/garbage-collection.md @@ -9,7 +9,7 @@ This document describes what this command does and how and why it should be used ## About garbage collection -In the context of the Docker registry, garbage collection is the process of +In the context of the registry, garbage collection is the process of removing blobs from the filesystem when they are no longer referenced by a manifest. Blobs can include both layers and manifests. diff --git a/docs/content/about/glossary.md b/docs/content/about/glossary.md index e31c4f443..2bd7a740e 100644 --- a/docs/content/about/glossary.md +++ b/docs/content/about/glossary.md @@ -17,7 +17,7 @@ This page contains definitions for distribution related terms.

Image

-
An image is a named set of immutable data from which a Docker container can be created.
+
An image is a named set of immutable data from which a container can be created.

An image is represented by a json file called a manifest, and is conceptually a set of layers. diff --git a/docs/content/recipes/mirror.md b/docs/content/recipes/mirror.md index bd17a96bb..ca85487fc 100644 --- a/docs/content/recipes/mirror.md +++ b/docs/content/recipes/mirror.md @@ -6,16 +6,12 @@ title: Registry as a pull through cache ## Use-case -If you have multiple instances of Docker running in your environment, such as -multiple physical or virtual machines all running Docker, each daemon goes out -to the internet and fetches an image it doesn't have locally, from the Docker -repository. You can run a local registry mirror and point all your daemons +If you have multiple consumers of containers running in your environment, such as +multiple physical or virtual machines using containers, or a Kubernetes cluster, +each cunsumer fetches an images it doesn't have locally, from the external registry. +You can run a local registry mirror and point all your consumers there, to avoid this extra internet traffic. -> **Note** -> -> Docker Official Images are an intellectual property of Docker. - ### Alternatives Alternatively, if the set of images you are using is well delimited, you can diff --git a/docs/content/recipes/systemd.md b/docs/content/recipes/systemd.md index f3d84ab2f..43c52215b 100644 --- a/docs/content/recipes/systemd.md +++ b/docs/content/recipes/systemd.md @@ -22,7 +22,7 @@ registry.service ```ini [Unit] -Description=Docker registry +Description=Distribution registry After=docker.service Requires=docker.service @@ -63,7 +63,7 @@ registry.socket ```ini [Unit] -Description=container registry +Description=Distribution registry [Socket] ListenStream=5000 diff --git a/docs/content/spec/auth/_index.md b/docs/content/spec/auth/_index.md index 719c430c7..c2d12b049 100644 --- a/docs/content/spec/auth/_index.md +++ b/docs/content/spec/auth/_index.md @@ -1,10 +1,10 @@ --- -title: "Docker Registry Token Authentication" -description: "Docker Registry v2 authentication schema" +title: "Distribution Registry Token Authentication" +description: "Distribution Registry v2 authentication schema" keywords: registry, on-prem, images, tags, repository, distribution, authentication, advanced --- -# Docker Registry v2 authentication +# Distribution Registry v2 authentication See the [Token Authentication Specification](token), [Token Authentication Implementation](jwt), diff --git a/docs/content/spec/auth/jwt.md b/docs/content/spec/auth/jwt.md index 9f09885fe..6c18fd999 100644 --- a/docs/content/spec/auth/jwt.md +++ b/docs/content/spec/auth/jwt.md @@ -1,10 +1,10 @@ --- title: "Token Authentication Implementation" -description: "Describe the reference implementation of the Docker Registry v2 authentication schema" +description: "Describe the reference implementation of the Distribution Registry v2 authentication schema" keywords: registry, on-prem, images, tags, repository, distribution, JWT authentication, advanced --- -# Docker Registry v2 Bearer token specification +# Distribution Registry v2 Bearer token specification This specification covers the `distribution/distribution` implementation of the v2 Registry's authentication schema. Specifically, it describes the JSON diff --git a/docs/content/spec/auth/oauth.md b/docs/content/spec/auth/oauth.md index 93c43e8a3..ca61d2edd 100644 --- a/docs/content/spec/auth/oauth.md +++ b/docs/content/spec/auth/oauth.md @@ -1,10 +1,10 @@ --- title: "Oauth2 Token Authentication" -description: "Specifies the Docker Registry v2 authentication" +description: "Specifies the Distribution Registry v2 authentication" keywords: registry, on-prem, images, tags, repository, distribution, oauth2, advanced --- -# Docker Registry v2 authentication using OAuth2 +# Distribution Registry v2 authentication using OAuth2 This document describes support for the OAuth2 protocol within the authorization server. [RFC6749](https://tools.ietf.org/html/rfc6749) should be used as a diff --git a/docs/content/spec/auth/scope.md b/docs/content/spec/auth/scope.md index 19ba0b279..a2236bb75 100644 --- a/docs/content/spec/auth/scope.md +++ b/docs/content/spec/auth/scope.md @@ -4,7 +4,7 @@ description: "Describes the scope and access fields used for registry authorizat keywords: registry, on-prem, images, tags, repository, distribution, advanced, access, scope --- -# Docker Registry Token Scope and Access +# Distribution Registry Token Scope and Access Tokens used by the registry are always restricted what resources they may be used to access, where those resources may be accessed, and what actions diff --git a/docs/content/spec/auth/token.md b/docs/content/spec/auth/token.md index a3484107f..1696280de 100644 --- a/docs/content/spec/auth/token.md +++ b/docs/content/spec/auth/token.md @@ -1,12 +1,12 @@ --- title: "Token Authentication Specification" -description: "Specifies the Docker Registry v2 authentication" +description: "Specifies the Distribution Registry v2 authentication" keywords: registry, on-prem, images, tags, repository, distribution, Bearer authentication, advanced --- -# Docker Registry v2 authentication via central service +# Distribution Registry v2 authentication via central service -This document outlines the v2 Docker registry authentication scheme: +This document outlines the v2 Distribution registry authentication scheme: ![v2 registry auth](/images/v2-registry-auth.png) @@ -27,9 +27,9 @@ This document outlines the v2 Docker registry authentication scheme: - Registry clients which can understand and respond to token auth challenges returned by the resource server. - An authorization server capable of managing access controls to their - resources hosted by any given service (such as repositories in a Docker + resources hosted by any given service (such as repositories in a Distribution Registry). -- A Docker Registry capable of trusting the authorization server to sign tokens +- A Distribution Registry capable of trusting the authorization server to sign tokens which clients can use for authorization and the ability to verify these tokens for single use or for use during a sufficiently short period of time. @@ -39,11 +39,8 @@ The described server is meant to serve as a standalone access control manager for resources hosted by other services which wish to authenticate and manage authorizations using a separate access control manager. -A service like this is used by the official Docker Registry to authenticate -clients and verify their authorization to Docker image repositories. - -As of Docker 1.6, the registry client within the Docker Engine has been updated -to handle such an authorization workflow. +A service like this is used by public and private registries to authenticate +clients and verify their authorization to image repositories. ## How to authenticate diff --git a/docs/content/spec/implementations.md b/docs/content/spec/implementations.md index e4f5f9d5e..0def59a52 100644 --- a/docs/content/spec/implementations.md +++ b/docs/content/spec/implementations.md @@ -6,9 +6,9 @@ draft: true This is a list of known implementations of the Distribution API spec. -## [Docker Distribution Registry](https://github.com/distribution/distribution) +## [CNCF Distribution Registry](https://github.com/distribution/distribution) -Docker distribution is the reference implementation of the distribution API +CNCF distribution is the reference implementation of the distribution API specification. It aims to fully implement the entire specification. ### Releases diff --git a/docs/content/spec/json.md b/docs/content/spec/json.md index 7f8d3d57b..f7e1cf735 100644 --- a/docs/content/spec/json.md +++ b/docs/content/spec/json.md @@ -1,15 +1,15 @@ --- draft: true -title: "Docker Distribution JSON Canonicalization" +title: "CNCF Distribution JSON Canonicalization" description: "Explains registry JSON objects" keywords: ["registry, service, images, repository, json"] --- -# Docker Distribution JSON Canonicalization +# CNCF Distribution JSON Canonicalization -To provide consistent content hashing of JSON objects throughout Docker +To provide consistent content hashing of JSON objects throughout CNCF Distribution APIs, the specification defines a canonical JSON format. Adopting such a canonicalization also aids in caching JSON responses. diff --git a/releases/README.md b/releases/README.md index fa63e2e6b..da272a9bb 100644 --- a/releases/README.md +++ b/releases/README.md @@ -43,4 +43,4 @@ e.g. to release `2.3.1` `2.3 -> 2.3.1` -90. Build a new distribution/registry image on [Docker hub](https://hub.docker.com/u/distribution/dashboard) by adding a new automated build with the new tag and re-building the images. +90. Build a new distribution/registry image on [Docker Hub](https://hub.docker.com/u/distribution/dashboard) by adding a new automated build with the new tag and re-building the images.