How to manage image registries

Image registries store information about global, read-only sources of images, such as SimpleStreams servers or other LXD servers. You can use image registries to centrally define and manage the image sources that are accessible to all members of the cluster. Once you create an image registry, you can use it to download images for LXD.

Image registries are the mechanism that LXD uses to download images. Every LXD server comes with a set of built-in image registries for the most common public image sources. Built-in registries cannot be renamed, reconfigured, or deleted. You can add your own registries in addition to the built-in ones.

Note

Access to image registries can be restricted per project with the restricted.registries configuration option. See Project restrictions for more information.

Create an image registry

The requirements for creating a new image registry depend on the protocol used by the image source.

To create a registry for an image source that uses the lxd protocol, you must connect to the remote LXD server through a cluster link. Use a public cluster link for a public LXD server, or a unidirectional or bidirectional cluster link to authenticate to a private server.

Use the required cluster configuration key to specify the cluster link:

lxc image registry create <registry_name> cluster=<cluster_link_name> source_project=<project>

Note

The source_project option selects which project on the remote server the registry draws images from.

Public images can exist only in the default project; every other project can contain private images only (the default project can also contain private images). A public cluster link connects to the remote server anonymously, so it can access only public images, which means public images in the server’s default project. To expose private images from any project, use a unidirectional or bidirectional cluster link whose authentication group has the can_view_images permission on the source project. Otherwise the registry still connects, but it cannot see the private images, so they remain inaccessible.

To create a registry for an image source that uses the simplestreams protocol, specify the URL of the SimpleStreams server.

Use the required url configuration key to specify the SimpleStreams server:

lxc image registry create <registry_name> url=<URL>

View image registries

To list all configured image registries, run:

lxc image registry list

To view the configuration of a specific image registry, run:

lxc image registry show <registry_name>

List the images in a registry

To see which images an image registry provides, list its images.

Use the --registry flag of the lxc image list command:

lxc image list --registry <registry_name>

You can filter the results in the same way as when listing local images.

Use an image registry

You use an image registry the same way you would use any other image source: reference the registry name together with an image alias or fingerprint.

Configure an image registry

You can edit the configuration for an image registry in your text editor or set specific configuration options.

To edit an image registry in your default text editor, run:

lxc image registry edit <registry_name>

To set a specific configuration option, run:

lxc image registry set <registry_name> <key> <value>

For example, to update the source project:

lxc image registry set my-registry source_project foo

For a list of available configuration options, see Image registries.

Delete an image registry

To delete an image registry, run:

lxc image registry delete <registry_name>