registry: add DefaultRegistryHost const, and improve documentation

This is more in line with other consts that are used for defaults, and makes it
slightly easier to consume than DefaultV2Registry, e.g. see:
https://github.com/oras-project/oras-go/blob/v1.1.0/pkg/auth/docker/resolver.go#L81-L84

Note that both the "index.docker.io" and "registry-1.docker.io" domains
are here for historic reasons and backward-compatibility. These domains
are still supported by Docker Hub (and will continue to be supported), but
there are new domains already in use, and plans to consolidate all legacy
domains to new "canonical" domains. Once those domains are decided on, we
should update these consts (but making sure to preserve compatibility with
existing installs, clients, and user configuration).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

integration/system/login_test.go

@@ -2,10 +2,12 @@ package system // import "github.com/docker/docker/integration/system"
 
 import (
 	"context"
+	"fmt"
 	"testing"
 
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/integration/internal/requirement"
+	"github.com/docker/docker/registry"
 	"gotest.tools/v3/assert"
 	is "gotest.tools/v3/assert/cmp"
 	"gotest.tools/v3/skip"
@@ -25,5 +27,5 @@ func TestLoginFailsWithBadCredentials(t *testing.T) {
 	_, err := client.RegistryLogin(context.Background(), config)
 	assert.Assert(t, err != nil)
 	assert.Check(t, is.ErrorContains(err, "unauthorized: incorrect username or password"))
-	assert.Check(t, is.ErrorContains(err, "https://registry-1.docker.io/v2/"))
+	assert.Check(t, is.ErrorContains(err, fmt.Sprintf("https://%s/v2/", registry.DefaultRegistryHost)))
 }

registry/config.go

@@ -26,10 +26,24 @@ type serviceConfig struct {
 	registrytypes.ServiceConfig
 }
 
+// TODO(thaJeztah) both the "index.docker.io" and "registry-1.docker.io" domains
+// are here for historic reasons and backward-compatibility. These domains
+// are still supported by Docker Hub (and will continue to be supported), but
+// there are new domains already in use, and plans to consolidate all legacy
+// domains to new "canonical" domains. Once those domains are decided on, we
+// should update these consts (but making sure to preserve compatibility with
+// existing installs, clients, and user configuration).
 const (
 	// DefaultNamespace is the default namespace
 	DefaultNamespace = "docker.io"
-	// IndexHostname is the index hostname
+	// DefaultRegistryHost is the hostname for the default (Docker Hub) registry
+	// used for pushing and pulling images. This hostname is hard-coded to handle
+	// the conversion from image references without registry name (e.g. "ubuntu",
+	// or "ubuntu:latest"), as well as references using the "docker.io" domain
+	// name, which is used as canonical reference for images on Docker Hub, but
+	// does not match the domain-name of Docker Hub's registry.
+	DefaultRegistryHost = "registry-1.docker.io"
+	// IndexHostname is the index hostname, used for authentication and image search.
 	IndexHostname = "index.docker.io"
 	// IndexServer is used for user auth and image search
 	IndexServer = "https://" + IndexHostname + "/v1/"
@@ -38,10 +52,10 @@ const (
 )
 
 var (
-	// DefaultV2Registry is the URI of the default v2 registry
+	// DefaultV2Registry is the URI of the default (Docker Hub) registry.
 	DefaultV2Registry = &url.URL{
 		Scheme: "https",
-		Host:   "registry-1.docker.io",
+		Host:   DefaultRegistryHost,
 	}
 
 	// ErrInvalidRepositoryName is an error returned if the repository name did