Fix remaining v2 -> v3 changes in docs and configuration

[thaJeztah]

Description

I noticed some things that we need to address before v3.0.0 w.r.t. configuration or the official image, and documentation; this is just a quick list, but there may be more;

• update the documentation to refer to the new image tag (documentation currently uses registry:2) #4356
• update the location of the configuration file () #4357
  • the path should likely no longer contain "docker"; decide on a new location
  • can we have some / do we need some fallback for the old location? (symlink, or ideally; binary checking both?)
  • update the official image accordingly; https://github.com/distribution/distribution-library-image/blob/73483231b14174569cbc2ecaf8af15a990f460c6/Dockerfile#L32
  • is there a default location that the registry uses? if so, can we remove the ENTRYPOINT and let the registry use the default location (if present)?
• verify the default configuration file in the official image. The registry-library-image has a default / example configuration file; https://github.com/distribution/distribution-library-image/blob/eb58390c830bc5017f1a4eafc365b45206ad21fe/config-example.yml. We need to;
  • verify if the example is still correct for v3 (is version 0.1 still accurate?)
  • do we have a canonical "default" config file in the main repository that we can use instead?
  • or; does the registry have an option to output the default config (similar to containerd's containerd config default, which dumps the default config file)?
  • are any of the options specified different from built-in defaults?
  • if none are different from the default, can we remove the configuration file entirely?

[thaJeztah]

cc @milosgajdos @dvdksn @Jamstah

[milosgajdos]

🫠 I wonder if we should create v3-stable Mileston in GH to track there

[Jamstah]

🫠 I wonder if we should create v3-stable Mileston in GH to track there

I think we can just reuse the 3.0.0 milestone

[milosgajdos]

update the location of the configuration file (/etc/docker/registry/config.yaml)

I suggest we go with /etc/distribution/config.yaml

can we have some / do we need some fallback for the old location? (symlink, or ideally; binary checking both?)

I don't think it's worth it; as long as it's picked up by ENTRYPOINT we are good; the default config is there to make the first experience with docker run registry seamless; besides, I would not be overthinking this with some elaborate symlinking

is there a default location that the registry uses? if so, can we remove the ENTRYPOINT and let the registry use the default location (if present)?

Alas, no. Registry simply picks it up as the first arg to its subcommand (serve, gc):

distribution/registry/registry.go

Lines 96 to 110 in e0a54de

	var ServeCmd = &cobra.Command{
	Use: "serve <config>",
	Short: "`serve` stores and distributes Docker images",
	Long: "`serve` stores and distributes Docker images.",
	Run: func(cmd *cobra.Command, args []string) {
	// setup context
	ctx := dcontext.WithVersion(dcontext.Background(), version.Version())
	config, err := resolveConfiguration(args)
	if err != nil {
	fmt.Fprintf(os.Stderr, "configuration error: %v\n", err)
	// nolint:errcheck
	cmd.Usage()
	os.Exit(1)
	}

I would keep it as is, personally. We could be clever but I wouldn't. Not for this release, anyway.
Also we do support REGISTRY_CONFIGURATION_PATH that lets you provide ur own config path which can be used if the config arg is omitted:

distribution/registry/registry.go

Lines 457 to 461 in e0a54de

	if len(args) > 0 {
	configurationPath = args[0]
	} else if os.Getenv("REGISTRY_CONFIGURATION_PATH") != "" {
	configurationPath = os.Getenv("REGISTRY_CONFIGURATION_PATH")
	}

verify if the example is still correct for v3 (is version 0.1 still accurate?)

Yep, still works for me on the v3 build; as I mentioned above it's deliberately kept simple.

do we have a canonical "default" config file in the main repository that we can use instead?

I don't think we have a "canonical"/"default", but we have a couple of example config files here: https://github.com/distribution/distribution/tree/e0a54de7fc1dd9046f1d6449cc615af209003cbb/cmd/registry and more elaborate ones we use in testing here: https://github.com/distribution/distribution/tree/e0a54de7fc1dd9046f1d6449cc615af209003cbb/tests

or; does the registry have an option to output the default config (similar to containerd's containerd config default, which dumps the default config file)?

Nope, but that'd be pretty cool and should be hard to implement actually 🤔

or; does the registry have an option to output the default config (similar to containerd's containerd config default, which dumps the default config file)?

Nope and I wouldn't do this anyway.

are any of the options specified different from built-in defaults?
if none are different from the default, can we remove the configuration file entirely?

there is no such thing as defaults per see at the moment. Reworking the existing code into using some sort of selected defaults would be maybe a chunky piece of work...maybe not; hard to tell but right now we read all config opts from the config file. I wouldn't do it for this release. Maybe next.

Some of these suggestions are super interesting and we should do them for v4.

[ajschmidt8]

Any thoughts on when v3 will be released?

[milosgajdos]

No exact ETA but wed like to get a Beta out soon, first!