diff --git a/doc/howto/instances_configure.md b/doc/howto/instances_configure.md index e339841f46dd..9185bd5b973a 100644 --- a/doc/howto/instances_configure.md +++ b/doc/howto/instances_configure.md @@ -13,36 +13,59 @@ To store and reuse different instance configurations, use {ref}`profiles `. +Alternatively, you can update the instance options after the instance is created. ````{tabs} ```{group-tab} CLI -Alternatively, to update instance options after the instance is created, use the [`lxc config set`](lxc_config_set.md) command. +Use the [`lxc config set`](lxc_config_set.md) command to update instance options. Specify the instance name and the key and value of the instance option: lxc config set = = ... ``` ```{group-tab} API -Alternatively, to update instance options after the instance is created, send a PATCH request to the instance. +Send a PATCH request to the instance to update instance options. Specify the instance name and the key and value of the instance option: lxc query --request PATCH /1.0/instances/ --data '{"config": {"":"","":""}}' See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) for more information. ``` + +```{group-tab} UI +To update instance options, go to the {guilabel}`Configuration` tab of the instance detail page and click {guilabel}`Edit instance`. + +Find the configuration option that you want to update and change its value. +Click {guilabel}`Save changes` to save the updated configuration. + +To configure instance options that are not displayed in the UI, follow the instructions in {ref}`instances-configure-edit`. +``` ```` See {ref}`instance-options` for a list of available options and information about which options are available for which instance type. -For example, to change the memory limit for your container, enter the following command: +For example, change the memory limit for your container: ````{tabs} ```{group-tab} CLI - lxc config set my-container limits.memory=128MiB +To set the memory limit to 8 GiB, enter the following command: + + lxc config set my-container limits.memory=8GiB ``` ```{group-tab} API - lxc query --request PATCH /1.0/instances/my-container --data '{"config": {"limits.memory":"128MiB"}}' +To set the memory limit to 8 GiB, send the following request: + + lxc query --request PATCH /1.0/instances/my-container --data '{"config": {"limits.memory":"8GiB"}}' +``` + +```{group-tab} UI +To set the memory limit to 8 GiB, go to the {guilabel}`Configuration` tab of the instance detail page and select {guilabel}`Advanced > Resource limits`. +Then click {guilabel}`Edit instance`. + +Select {guilabel}`Override` for the **Memory limit** and enter 8 GiB as the absolute value. + +![Setting the memory limit for an instance to 8 GiB](/images/UI/limits_memory_example.png) ``` ```` @@ -84,6 +107,11 @@ To unset an instance property, send a PUT request that contains the full instanc See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) and [`PUT /1.0/instances/{name}`](swagger:/instances/instance_put) for more information. ``` + +```{group-tab} UI +The LXD UI does not distinguish between instance options and instance properties. +Therefore, you can configure instance properties in the same way as you {ref}`configure instance options `. +``` ```` (instances-configure-devices)= @@ -143,6 +171,21 @@ For example, to add the storage at `/share/c1` on the host system to your instan See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) for more information. ```` + +````{group-tab} UI +The UI currently has limited support for devices. + +To attach a device to your instance, you must first create it. +Then you can update your instance configuration (in the same way as you {ref}`configure instance options `) to attach the device to the instance. + +```{note} +Some of the devices that are displayed in the instance configuration are inherited from a {ref}`profile ` or defined through a {ref}`project `. +These devices cannot be edited for an instance. +``` + +To add and configure devices that are not currently supported in the UI, follow the instructions in {ref}`instances-configure-edit`. +```` + ````` ## Display instance configuration @@ -161,6 +204,13 @@ To retrieve the current configuration of your instance, including writable insta See [`GET /1.0/instances/{name}`](swagger:/instances/instance_get) for more information. ``` + +```{group-tab} UI +To view the current configuration of your instance, go to {guilabel}`Instances`, select your instance, and then switch to the {guilabel}`Configuration` tab. + +To see the full configuration including instance properties, instance options, devices and device options (also the ones that aren't yet supported by the UI), select {guilabel}`YAML configuration`. +This view shows the full YAML of the instance configuration. +``` ```` (instances-configure-edit)= @@ -188,5 +238,28 @@ See [`PUT /1.0/instances/{name}`](swagger:/instances/instance_put) for more info ```{note} If you include changes to any read-only instance properties in the configuration you provide, they are ignored. +``` +```` + +````{group-tab} UI +Instead of using the UI forms to configure your instance, you can choose to edit the YAML configuration of the instance. +You must use this method if you need to update any configurations that are not available in the UI. + +```{important} +When doing updates, do not navigate away from the YAML configuration without saving your changes. +If you do, your updates are lost. +``` + +To edit the YAML configuration of your instance, go to the instance detail page, switch to the {guilabel}`Configuration` tab and select {guilabel}`YAML configuration`. +Then click {guilabel}`Edit instance`. + +Edit the YAML configuration as required. +Then click {guilabel}`Save changes` to save the updated configuration. + +```{note} +For convenience, the YAML contains the full configuration including read-only instance properties. +However, you cannot edit those properties. +Any changes are ignored. +``` ```` ````` diff --git a/doc/howto/instances_manage.md b/doc/howto/instances_manage.md index 03928d532ef6..5b115aab2759 100644 --- a/doc/howto/instances_manage.md +++ b/doc/howto/instances_manage.md @@ -45,6 +45,15 @@ For example: See [`GET /1.0/instances`](swagger:/instances/instances_get) for more information. ``` + +```{group-tab} UI +Go to {guilabel}`Instances` to see a list of all instances. + +You can filter the instances that are displayed by status, instance type, or the profile they use by selecting the corresponding filter. + +In addition, you can search for instances by entering a search text. +The text you enter is matched against the name, the description, and the name of the base image. +``` ```` ## Show information about an instance @@ -67,6 +76,12 @@ Query the following endpoint to show detailed information about an instance: See [`GET /1.0/instances/{name}`](swagger:/instances/instance_get) for more information. ``` + +```{group-tab} UI +Clicking an instance line in the overview will show a summary of the instance information right next to the instance list. + +Click the instance name to go to the instance detail page, which contains detailed information about the instance. +``` ```` ## Start an instance @@ -104,6 +119,15 @@ Use the following query to monitor the state of the instance: See [`GET /1.0/instances/{name}/state`](swagger:/instances/instance_state_get) and [`PUT /1.0/instances/{name}/state`](swagger:/instances/instance_state_put)for more information. ``` + +```{group-tab} UI +To start an instance, go to the instance list or the respective instance and click the {guilabel}`Start` button (▷). + +You can also start several instances at the same time by selecting them in the instance list and clicking the {guilabel}`Start` button at the top. + +On the instance detail page, select the {guilabel}`Console` tab to see the boot log with information about the instance starting up. +Once it is running, you can select the {guilabel}`Terminal` tab to access the instance. +``` ```` (instances-manage-stop)= @@ -128,8 +152,24 @@ To stop an instance, send a PUT request to change the instance state: :start-after: :end-before: ``` +```` + +````{group-tab} UI +To stop an instance, go to the instance list or the respective instance and click the {guilabel}`Stop` button (□). +You are then prompted to confirm. + + +```{tip} +To skip the confirmation prompt, hold the {kbd}`Shift` key while clicking. +``` + + +You can choose to force-stop the instance. +If stopping the instance takes a long time or the instance is not responding to the stop request, click the spinning stop button to go back to the confirmation prompt, where you can select to force-stop the instance. +You can also stop several instances at the same time by selecting them in the instance list and clicking the {guilabel}`Stop` button at the top. ```` + ````` ## Delete an instance @@ -137,7 +177,7 @@ To stop an instance, send a PUT request to change the instance state: If you don't need an instance anymore, you can remove it. The instance must be stopped before you can delete it. -````{tabs} +`````{tabs} ```{group-tab} CLI Enter the following command to delete an instance: @@ -151,7 +191,20 @@ To delete an instance, send a DELETE request to the instance: See [`DELETE /1.0/instances/{name}`](swagger:/instances/instance_delete) for more information. ``` + +````{group-tab} UI +To delete an instance, go to its instance detail page and click {guilabel}`Delete instance`. +You are then prompted to confirm. + +% Include content from above +```{include} ./instances_manage.md + :start-after: + :end-before: +``` + +You can also delete several instances at the same time by selecting them in the instance list and clicking the {guilabel}`Delete` button at the top. ```` +````` ```{caution} This command permanently deletes the instance and all its snapshots. @@ -200,4 +253,8 @@ To rebuild the instance with an empty root disk, specify the source type as `non See [`POST /1.0/instances/{name}/rebuild`](swagger:/instances/instance_rebuild_post) for more information. ``` + +```{group-tab} UI +Rebuilding an instance is not yet supported in the UI. +``` ```` diff --git a/doc/images/UI/limits_memory_example.png b/doc/images/UI/limits_memory_example.png new file mode 100644 index 000000000000..7430093aaa62 Binary files /dev/null and b/doc/images/UI/limits_memory_example.png differ