# 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](https://canonical.com/lxd/docs/latest/reference/remote_image_servers/index.html.md#remote-image-servers) 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`](https://canonical.com/lxd/docs/latest/reference/projects/index.html.md#project-restricted:restricted.registries) configuration option. See [Project restrictions](https://canonical.com/lxd/docs/latest/reference/projects/index.html.md#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](https://canonical.com/lxd/docs/latest/howto/cluster_links_create/index.html.md#howto-cluster-links-create). Use a public cluster link for a public LXD server, or a unidirectional or bidirectional cluster link to authenticate to a private server. CLI Use the required `cluster` configuration key to specify the cluster link: ```bash lxc image registry create cluster= source_project= ``` API Send a `POST` request to the `/1.0/image-registries` endpoint, specifying the required `cluster` configuration key: ```bash lxc query --request POST /1.0/image-registries --data '{"name": "my-registry", "config": {"cluster": "my-cluster-link", "source_project": "default"}}' ``` See [`POST /1.0/image-registries`](/lxd/latest/api/#/image-registries/image_registries_post) for more information. #### 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](https://canonical.com/lxd/docs/latest/howto/cluster_links_create/index.html.md#howto-cluster-links-auth) 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. CLI Use the required `url` configuration key to specify the SimpleStreams server: ```bash lxc image registry create url= ``` API Send a `POST` request to the `/1.0/image-registries` endpoint, specifying the required `url` configuration key: ```bash lxc query --request POST /1.0/image-registries --data '{"name": "my-registry", "config": {"url": "https://images.example.org"}}' ``` See [`POST /1.0/image-registries`](/lxd/latest/api/#/image-registries/image_registries_post) for more information. ## View image registries CLI To list all configured image registries, run: ```bash lxc image registry list ``` To view the configuration of a specific image registry, run: ```bash lxc image registry show ``` API To list all image registries, send the following request: ```bash lxc query --request GET /1.0/image-registries ``` To view the configuration of a specific image registry, send the following request: ```bash lxc query --request GET /1.0/image-registries/ ``` See [`GET /1.0/image-registries`](/lxd/latest/api/#/image-registries/image_registries_get) and [`GET /1.0/image-registries/{name}`](/lxd/latest/api/#/image-registries/%7Bname%7D/image_registry_get) for more information. ## List the images in a registry To see which images an image registry provides, list its images. CLI Use the `--registry` flag of the [`lxc image list`](https://canonical.com/lxd/docs/latest/reference/manpages/lxc/image/list/index.html.md#lxc-image-list-md) command: ```bash lxc image list --registry ``` You can filter the results in the same way as when [listing local images](https://canonical.com/lxd/docs/latest/howto/images_manage/index.html.md#images-manage-filter). API Send a `GET` request to the `images` sub-endpoint of the registry: ```bash lxc query --request GET /1.0/image-registries//images ``` See [`GET /1.0/image-registries/{name}/images`](/lxd/latest/api/#/image-registries/%7Bname%7D/image_registry_images_get) for more information. ## 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. - To create an instance from an image provided by a registry, see [How to create instances](https://canonical.com/lxd/docs/latest/howto/instances_create/index.html.md#instances-create). - To copy an image from a registry into your local image store, see [How to copy and import images](https://canonical.com/lxd/docs/latest/howto/images_copy/index.html.md#images-copy). ## Configure an image registry You can edit the configuration for an image registry in your text editor or set specific configuration options. CLI To edit an image registry in your default text editor, run: ```bash lxc image registry edit ``` To set a specific configuration option, run: ```bash lxc image registry set ``` For example, to update the source project: ```bash lxc image registry set my-registry source_project foo ``` API To update an image registry, send a `PUT` or `PATCH` request to the `/1.0/image-registries/` endpoint. ```bash lxc query --request PATCH /1.0/image-registries/my-registry --data '{"description": "New description"}' ``` See [`PUT /1.0/image-registries/{name}`](/lxd/latest/api/#/image-registries/%7Bname%7D/image_registry_put) and [`PATCH /1.0/image-registries/{name}`](/lxd/latest/api/#/image-registries/%7Bname%7D/image_registry_patch) for more information. For a list of available configuration options, see [Image registries](https://canonical.com/lxd/docs/latest/reference/image_registries/index.html.md#ref-image-registries). ## Delete an image registry To delete an image registry, run: CLI ```bash lxc image registry delete ``` API ```bash lxc query --request DELETE /1.0/image-registries/ ``` See [`DELETE /1.0/image-registries/{name}`](/lxd/latest/api/#/image-registries/%7Bname%7D/image_registry_delete) for more information.