Image registries client-side changes by nmezhenskyi · Pull Request #18203 · canonical/lxd

nmezhenskyi · 2026-04-28T21:49:55Z

This PR introduces the client-side changes needed to make use of the new image registries feature for image download operations. It also defines new API structs for image registries and new ProtocolLXD client methods for interacting with image registry API.

This is the first PR in a series to introduce image registries and update LXD's image sourcing functionality.

The actual image registry API for LXD is introduced in the following PRs.

Copilot

Pull request overview

This PR adds the client-side and shared-API plumbing needed for LXD's upcoming image registries feature, so the CLI and Go client can describe image-registry sources before the server-side API lands.

Changes:

Adds new shared API types/fields for image registries and image-registry-based image sources.
Extends the Go client with image registry CRUD/list methods and image-copy support for server-side registry resolution.
Updates lxc init, launch, rebuild, and image copy to route image download operations through image registries when the target server advertises support.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`shared/api/instance.go`	Adds `image_registry` to instance image sources.
`shared/api/image.go`	Adds registry-related image source fields, including `copy_aliases`.
`shared/api/image_registry.go`	Introduces image registry API structs and transitional SimpleStreams helpers.
`shared/api/image_registry_test.go`	Adds unit tests for transitional registry helper functions.
`lxc/utils.go`	Adds helper logic for resolving registry-backed image sources.
`lxc/rebuild.go`	Updates rebuild to use registry-aware image resolution.
`lxc/launch.go`	Updates launch help text for registry-aware image sourcing.
`lxc/init.go`	Updates init/create flow to support server-side registry resolution and fallback logic.
`lxc/image.go`	Updates image copy/info flows for image registries.
`lxc/config/remote.go`	Adds unchecked remote parsing to allow registry names.
`doc/rest-api.yaml`	Adds OpenAPI schema entries for image registry types and fields.
`client/lxd.go`	Adjusts source image connection handling for server-side registry resolution.
`client/lxd_instances.go`	Marks legacy source fields deprecated in instance copy/rebuild paths.
`client/lxd_images.go`	Adds server-side registry-aware image copy handling.
`client/lxd_image_registries.go`	Adds new `ProtocolLXD` image registry client methods.
`client/interfaces.go`	Extends the client interfaces and copy args for image registries.

tomponline · 2026-05-07T07:57:15Z

+	GetImageRegistryNames() (names []string, err error)
+	GetImageRegistryImages(name string) (images []api.Image, err error)
+	GetImageRegistries() (imageRegistries []api.ImageRegistry, err error)
+	CreateImageRegistry(imageRegistry api.ImageRegistriesPost) (err error)


Lets future proof these by making all mutate actions return an Operation

tomponline · 2026-05-07T08:20:21Z

+		// server's own local image store (e.g., when copying between projects).
+
+		// Enforce the pull mode for image download.
+		if args.Mode != "pull" {


Is args.Mode required for local images (i.e when args.ImageRegistry is empty?)

Is args.Mode required for local images (i.e when args.ImageRegistry is empty?)

No, it's not required for local images, good catch.

I've fixed the condition.

tomponline · 2026-05-07T08:22:57Z

+// resolveRegistryImageSource determines the image source when the target server supports image registries.
+// For local copies (same server), it resolves the source project and returns an empty registry name.
+// For remote copies, it returns the image remote as the registry name.
+func resolveRegistryImageSource(conf *config.Config, imgRemote string, imgRef string, instRemote string, projectOverride string) (imgInfo *api.Image, registryName string) {


If we dont modify config.Config does it need to be a pointer?

It doesn't need to be a pointer, true. Now that I'm thinking, perhaps we shouldn't even be passing the whole config, and instead we can pass only the map conf.Remotes.

agreed, reduce the size of the API scope where possible.

tomponline · 2026-05-07T08:24:03Z

+// resolveRegistryImageSource determines the image source when the target server supports image registries.
+// For local copies (same server), it resolves the source project and returns an empty registry name.
+// For remote copies, it returns the image remote as the registry name.
+func resolveRegistryImageSource(conf *config.Config, imgRemote string, imgRef string, instRemote string, projectOverride string) (imgInfo *api.Image, registryName string) {


Please can we have a unit test for this function.

tomponline · 2026-05-07T08:27:00Z

-		return err
-	}
+	// Parse source remote without validating its existence in the local config.
+	remoteName, name := c.global.conf.ParseRemoteUnchecked(args[0])


Can we call this only inside the if destinationServer.HasExtension("image_registries") block and then use c.global.conf.ParseRemote for the fallback block for that the remote name is still validated in that case?

tomponline · 2026-05-07T08:28:15Z

-		return err
+	if sourceServer != nil {
+		// Resolve any alias and then grab the image information from the source
+		imgInfo, _, err = c.image.dereferenceAlias(sourceServer, imageType, name)


this section seems to override the imgInfo.Type = imageType line you added above?

maybe the imgInfo.Type = imageType should be in an else after this block?

Good catch, updated

tomponline · 2026-05-07T08:30:33Z

 	progress.Done("Image copied successfully!")

+	// If using an image registry, the aliases are handled server-side.
+	if sourceServer == nil {


what happens if the sourceServer is nil and the target server doesn't support image_registries extension, is this validated earlier on?

sourceServer is only set to nil inside the if destinationServer.HasExtension("image_registries") block. The else branch always populates sourceServer via GetImageServer() function, which either succeeds or returns an error.

So yes, this is essentially validated earlier on.

tomponline · 2026-05-07T08:31:55Z

+		}
 	}

 	// Store the fingerprint for use when creating aliases later (as imgInfo.Fingerprint may be overridden)


can this alias section be moved down after the the function has returned if using a target with image_registry support?

This section is needed for both paths. It builds the copyArgs variable which is used in both cases (including its Aliases field). There's an early return already on lines 316-319 that skips the legacy only part:

// If using an image registry, the aliases are handled server-side. if sourceServer == nil { return nil }

tomponline · 2026-05-07T08:35:40Z

+with --project and the instance remote with --target-project (if different from --project).
+
+If the destination LXD server supports image registries, the source image
+must be from an image registry or a local store.`)


"or a local store" suggests there can be multiple local stores.

Also its not clear what is "local" in this case.

Please can you clarify, something like:

If the destination LXD remote supports image registries, the source image must be from an image registry or available locally on the destination remote.

Also can you update other places you've updated with similar messages. Thanks

Finally we should avoid saying "LXD server" in this case, and use "LXD remote", because the remote may be a LXD cluster and not a single server.

tomponline · 2026-05-07T08:39:11Z

+			}
+		} else {
+			// Fetch image info from the given remote (legacy client-side resolution path).
+			// Normalize empty remote to the default remote, since ParseRemoteUnchecked


Like my earlier comment, I wonder if we should only be using ParseRemoteUnchecked inside the if d.HasExtension("image_registries") { block and in the fallback section using conf.ParseRemote?

I wonder if we should only be using ParseRemoteUnchecked inside the if d.HasExtension("image_registries") { block and in the fallback section using conf.ParseRemote?

Hm, yes, I think that's a better approach

tomponline · 2026-05-07T08:41:16Z


-		if conf.Remotes[iremote].Protocol != "simplestreams" {
+		// Only perform legacy type and protocol checks if we are NOT using an image registry.
+		if imgRemoteServer != nil && conf.Remotes[legacyRemote].Protocol != "simplestreams" {


As you've defined constants for "simplestreams" now, we should use them where possible.