# Updating a VM

After you create a VM, you can edit its name, description, labels, platform, or metadata.

For information about editing a VM configuration, see [Changing VM computing resources](vm-update-resources.md).

{% list tabs group=instructions %}

- Management console {#console}

  To update a VM:
  1. In the [management console](https://console.yandex.cloud), select the folder this VM belongs to.
  1. Navigate to **Compute Cloud**.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/server.svg) **Virtual machines** and click the name of the VM.
  1. Click ![image](../../../_assets/pencil.svg) **Edit VM**.
  1. Change the VM parameters, e.g., rename the VM by editing the **Name** field.
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for updating VM parameters:

     ```bash
     yc compute instance update --help
     ```

  1. Get a list of VMs in the default folder:

     ```bash
     yc compute instance list
     ```
     
     Result:
     ```text
     +----------------------+-----------------+---------------+---------+----------------------+
     |          ID          |       NAME      |    ZONE ID    | STATUS  |     DESCRIPTION      |
     +----------------------+-----------------+---------------+---------+----------------------+
     | fhm0b28lgfp4******** | first-instance  | ru-central1-a | RUNNING | my first vm via CLI  |
     | fhm9gk85nj7g******** | second-instance | ru-central1-a | RUNNING | my second vm via CLI |
     +----------------------+-----------------+---------------+---------+----------------------+
     ```

  1. Select the `ID` or `NAME` of the VM you need, e.g., `first-instance`.
  1. Change the VM parameters, e.g., rename the VM:

     ```bash
     yc compute instance update first-instance \
       --new-name windows-vm
     ```

- API {#api}

  To update a VM, use the [update](../../api-ref/Instance/update.md) REST API method for the [Instance](../../api-ref/Instance/index.md) resource or the [InstanceService/Update](../../api-ref/grpc/Instance/update.md) gRPC API call.

{% endlist %}

{% note info %}

Changing the VM name does not change the host name or FQDN. For more information about generating the FQDN, see [Host name and internal FQDN](../../concepts/network.md#hostname).

{% endnote %}

## Examples {#examples}

### Viewing a list of parameters to update {#viewing-a-list-of-configurable-parameters}

To view a list of parameters to update, run this command:

{% list tabs group=instructions %}

- CLI {#cli}

  ```bash
  yc compute instance update --help
  ```

{% endlist %}

### Changing the name and description {#changing-the-name-and-description}

To change the name and description of a VM, follow these steps:

{% list tabs group=instructions %}

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Get a list of VMs in the default folder:

     ```bash
     yc compute instance list
     ```
     
     Result:
     ```text
     +----------------------+-----------------+---------------+---------+----------------------+
     |          ID          |       NAME      |    ZONE ID    | STATUS  |     DESCRIPTION      |
     +----------------------+-----------------+---------------+---------+----------------------+
     | fhm0b28lgfp4******** | first-instance  | ru-central1-a | RUNNING | my first vm via CLI  |
     | fhm9gk85nj7g******** | second-instance | ru-central1-a | RUNNING | my second vm via CLI |
     +----------------------+-----------------+---------------+---------+----------------------+
     ```

  1. Select the `ID` or `NAME` of the VM, e.g., `first-instance`.
  1. Update the VM name and description:

     ```bash
     yc compute instance update first-instance \
       --new-name first-vm \
       --description "changed description vm via CLI"
     ```

- API {#api}

  Use the [update](../../api-ref/Instance/update.md) REST API method for the [Instance](../../api-ref/Instance/index.md) resource or the [InstanceService/Update](../../api-ref/grpc/Instance/update.md) gRPC API call.

{% endlist %}

{% note alert %}

Do not rename a VM if it belongs to a Managed Service for Kubernetes cluster [node group](../../../managed-kubernetes/concepts/index.md#node-group). The names of these VMs are generated automatically, and changing them will disrupt the cluster.

{% endnote %}

### Updating metadata {#changing-metadata}

When updating VM metadata using the Yandex Cloud [`yc compute instance update`](../../../cli/cli-ref/compute/cli-ref/instance/update.md) CLI command, the [update](../../api-ref/Instance/update.md) REST API method for the [Instance](../../api-ref/Instance/index.md) resource, or the [InstanceService/Update](../../api-ref/grpc/Instance/update.md) gRPC API call, the entire existing set of [metadata](../../concepts/vm-metadata.md) in the [user-data](../../concepts/metadata/directories.md#dir-user) folder and in the `instance/attributes/*` path of the [computeMetadata](../../concepts/metadata/directories.md#dir-compute) folder is fully overwritten with the newly updated set.

To add, modify, or delete individual keys in the `instance/attributes/*` path of the `computeMetadata` folder, use the Yandex Cloud [`yc compute instance add-metadata`](../../../cli/cli-ref/compute/cli-ref/instance/add-metadata.md) and [`yc compute instance remove-metadata`](../../../cli/cli-ref/compute/cli-ref/instance/remove-metadata.md) CLI commands, the [updateMetadata](../../api-ref/Instance/updateMetadata.md) REST API method for the [Instance](../../api-ref/Instance/index.md) resource, or the [InstanceService/UpdateMetadata](../../api-ref/grpc/Instance/updateMetadata.md) gRPC API call. In which case the `user-data` folder metadata will always be fully overwritten with new values.

To update the VM metadata:

{% list tabs group=instructions %}

- Management console {#console}

  {% note info %}

  When creating VM users via metadata using the `user-data` key, all users, including the default one specified under **Access**, will be overwritten. To avoid this, specify the data of all users in the `user-data` key, including the user specified under **Access**.

  {% endnote %}

  1. In the [management console](https://console.yandex.cloud), select the folder this VM belongs to.
  1. Navigate to **Compute Cloud**.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/server.svg) **Virtual machines**.
  1. In the VM row, click ![image](../../../_assets/console-icons/ellipsis.svg) and select ![image](../../../_assets/console-icons/pencil.svg) **Edit**.
  1. Under **Metadata**, provide the metadata in `Key:Value` format.

      For example, to create multiple users in the virtual machine OS, add the `user-data` key and specify the following configuration in it:

      ```yml
      #cloud-config
      datasource:
        Ec2:
          strict_id: false
      ssh_pwauth: no
      users:
      - name: <username_1>
        sudo: 'ALL=(ALL) NOPASSWD:ALL'
        shell: /bin/bash
        ssh_authorized_keys:
        - <public_SSH_key_1>
      - name: <username_2>
        sudo: 'ALL=(ALL) NOPASSWD:ALL'
        shell: /bin/bash
        ssh_authorized_keys:
        - <public_SSH_key_2>
      ...
      - name: <username_n>
        sudo: 'ALL=(ALL) NOPASSWD:ALL'
        shell: /bin/bash
        ssh_authorized_keys:
        - <public_SSH_key_n>
      runcmd: []
      ```

  1. Click **Save changes**.

- CLI {#cli}

  {% note info %}

  When creating VM users via metadata using the `user-data` key, all users, including the default one specified under `--ssh-key`, will be overwritten. To avoid this, specify the data of all users in the `user-data` key, including the user specified under `--ssh-key`.

  {% endnote %}

  In the Yandex Cloud CLI, you can provide metadata in any of the three parameters:

  * `--metadata-from-file`: As a configuration file in this format: `--metadata-from-file key=<file_path>`. Use this method to conveniently deliver a value consisting of several lines.

      For example, to add several users to a VM at the same time, describe the configuration in a [YAML](https://yaml.org/) file:

      ```yml
      #cloud-config
      datasource:
        Ec2:
          strict_id: false
      ssh_pwauth: no
      users:
      - name: <username_1>
        sudo: 'ALL=(ALL) NOPASSWD:ALL'
        shell: /bin/bash
        ssh_authorized_keys:
        - <public_SSH_key_1>
      - name: <username_2>
        sudo: 'ALL=(ALL) NOPASSWD:ALL'
        shell: /bin/bash
        ssh_authorized_keys:
        - <public_SSH_key_2>
      ...
      - name: <username_n>
        sudo: 'ALL=(ALL) NOPASSWD:ALL'
        shell: /bin/bash
        ssh_authorized_keys:
        - <public_SSH_key_n>
      runcmd: []
      ```

      {% note info %}
      
      The commands [`yc compute instance create`](../../../cli/cli-ref/compute/cli-ref/instance/create.md) | [`create-with-container`](../../../cli/cli-ref/compute/cli-ref/instance/create-with-container.md) | [`update`](../../../cli/cli-ref/compute/cli-ref/instance/update.md) | [`add-metadata`](../../../cli/cli-ref/compute/cli-ref/instance/add-metadata.md) support substitution of environment variable values into VM metadata. When you execute a Yandex Cloud CLI command, these values, specified in the `user-data` key in `$<variable_name>` format, will be substituted into the VM metadata from the environment variables of the environment the command is executed in. 
      
      To change such behavior, i.e. to provide a variable name to the VM metadata in `$<variable_name>` format rather than take the variable value from the CLI command runtime environment, use the two-dollar syntax, e.g., `$$<variable_name>`.
      
      For more information, see [Specifics of providing environment variables in metadata via the CLI](../../concepts/metadata/sending-metadata.md#environment-variables).
      
      {% endnote %}

  * `--metadata`: As a comma-separated list of `key=value` pairs, e.g., `--metadata foo1=bar,foo2=baz`.

      For a multiline value, use `\n` as a separator: `--metadata user-data="#ps1\nnet user Administrator Passw0rd"`.
  * `--ssh-key`: SSH key. Only for Linux VMs.

    Compute Cloud creates the `yc-user` user and adds the specified SSH key to the list of authorized keys. After the VM is created, you can use this key to connect to it over SSH.

  You can combine these parameters, for example:

  ```bash
  yc compute instance update \
    --name my-instance \
    --metadata-from-file user-data=metadata.yaml \
    --metadata serial-port-enable=1
  ...
  ```

- Terraform {#tf}

  {% note info %}

  When creating VM users via metadata using the `user-data` key, all users, including the default one specified under `ssh-keys`, will be overwritten. To avoid this, specify the data of all users in the `user-data` key, including the user specified under `ssh-keys`.

  {% endnote %}

  In Terraform, you can specify metadata in three ways:
  * As a separate file with user metadata to process by the `cloud-init` agent. To do this, under `metadata`, specify the path to the file with user metadata, such as `cloud-init.yaml`:

    ```hcl
    ...
    metadata = {
      user-data = "${file("cloud-init.yaml")}"
    }
    ...
    ```

    {% cut "Sample contents of the `cloud-init.yaml`" file %}

    ```yml
    #cloud-config
    datasource:
      Ec2:
        strict_id: false
    ssh_pwauth: no
    users:
    - name: <username_1>
      sudo: 'ALL=(ALL) NOPASSWD:ALL'
      shell: /bin/bash
      ssh_authorized_keys:
      - <public_SSH_key_1>
    - name: <username_2>
      sudo: 'ALL=(ALL) NOPASSWD:ALL'
      shell: /bin/bash
      ssh_authorized_keys:
      - <public_SSH_key_2>
    ...
    - name: <username_n>
      sudo: 'ALL=(ALL) NOPASSWD:ALL'
      shell: /bin/bash
      ssh_authorized_keys:
      - <public_SSH_key_n>
    runcmd: []
    ```

    {% endcut %}

  * Under `metadata`, as a line with user metadata. For a multiline value, use `\n` as a separator. Here is an example:

    ```hcl
    ...
    metadata = {
      user-data = "#cloud-config\nusers:\n  - name: <username>\n    groups: sudo\n    shell: /bin/bash\n    sudo: 'ALL=(ALL) NOPASSWD:ALL'\n    ssh_authorized_keys:\n      - <SSH_key_contents>"
    }
    ...
    ```

  * Only for Linux VMs. Under `ssh-keys`, specify the username and the SSH key to access Linux VMs. Enter your username and the contents of your SSH key as follows:

    ```hcl
    ...
    metadata = {
      ssh-keys = "<username>:<SSH_key_contents>"
    }
    ...
    ```

    If you are using an out-of-the-box public [image](../../concepts/image.md) from Yandex Cloud Marketplace, the specified username does not matter. The key will be assigned to the user specified in the `cloud-init` configuration by default. Such users differ depending on the image.

    If you do not know the default user, find the string containing `Authorized keys from` in the [serial port output](../vm-info/get-serial-port-output.md). It will contain the name of the user the authorized keys are assigned to.

    If you cannot find this string but you see the `no authorized ssh keys fingerprints found for user` string, it means you have provided your SSH key incorrectly. Check the format once again or try providing the SSH keys in the `user-data`field.

- API {#api}

  In the API, specify the metadata in the `metadata` property as a JSON object, e.g.:

  ```json
  "metadata": {
    "ssh-keys": "ssh-ed25519 AAAAB3Nza... user@example.com",
    "serial-port-enable": "1"
  }
  ```

  For a line break, use `\n`.

{% endlist %}

{% note warning %}

All metadata, including user-defined metadata, is unencrypted. If the metadata contains sensitive information, make sure to protect it, e.g., through encryption.

{% endnote %}

### Removing SSH keys from metadata {#delete-keys-from-metadata}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder this VM belongs to.
  1. Navigate to **Compute Cloud**.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/server.svg) **Virtual machines**.
  1. In the VM row, click ![image](../../../_assets/console-icons/ellipsis.svg) and select ![image](../../../_assets/console-icons/pencil.svg) **Edit**.
  1. Expand the **Metadata** section and remove the keys by clicking ![image](../../../_assets/console-icons/xmark.svg).
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for removing metadata:

      ```bash
      yc compute instance remove-metadata --help
      ```

  1. Remove the keys:

      ```bash
      yc compute instance remove-metadata <VM_ID> --keys <SSH_key_name>
      ```

- API {#api}

  To remove SSH keys from the VM metadata, use the [updateMetadata](../../api-ref/Instance/updateMetadata.md) REST API method for the [Instance](../../api-ref/Instance/index.md) resource or the [InstanceService/UpdateMetadata](../../api-ref/grpc/Instance/updateMetadata.md) gRPC API call.

  In your request, provide the `delete` parameter with the SSH key.

  **REST API request example**

  ```bash
  curl \
    --request POST \
    --header "Authorization: Bearer <IAM_token>" \
    --data '{"delete":["<SSH_key_name>"]}' \
    https://compute.api.cloud.yandex.net/compute/v1/instances/<VM_ID>/updateMetadata
  ```

{% endlist %}

### Enabling access via OS Login {#enable-oslogin-access}

To make sure users can [connect](../vm-connect/os-login.md) to the VM via [OS Login](../../../organization/concepts/os-login.md), enable this option in the VM settings:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder this VM belongs to.
  1. Navigate to **Compute Cloud**.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/server.svg) **Virtual machines**.
  1. In the VM row, click ![image](../../../_assets/console-icons/ellipsis.svg) and select ![image](../../../_assets/console-icons/pencil.svg) **Edit**.
  1. Under **Access**, select **Access by OS Login**.
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for updating VM parameters:

     ```bash
     yc compute instance update --help
     ```

  1. Get a list of VMs in the default folder:

     ```bash
     yc compute instance list
     ```
     
     Result:
     ```text
     +----------------------+-----------------+---------------+---------+----------------------+
     |          ID          |       NAME      |    ZONE ID    | STATUS  |     DESCRIPTION      |
     +----------------------+-----------------+---------------+---------+----------------------+
     | fhm0b28lgfp4******** | first-instance  | ru-central1-a | RUNNING | my first vm via CLI  |
     | fhm9gk85nj7g******** | second-instance | ru-central1-a | RUNNING | my second vm via CLI |
     +----------------------+-----------------+---------------+---------+----------------------+
     ```

  1. Select the `ID` or `NAME` of the VM, e.g., `first-instance`.

  1. Enable access via OS Login:

     ```bash
     yc compute instance update first-instance \
       --metadata enable-oslogin=true
     ```

- API {#api}

  Use the `metadata` field to provide `enable-oslogin=true` in the [update](../../api-ref/Instance/update.md) REST API method for the [Instance](../../api-ref/Instance/index.md) resource or in the [InstanceService/Update](../../api-ref/grpc/Instance/update.md) gRPC API call.

{% endlist %}

{% note info %}

For users added via metadata:

* After enabling access to a VM via OS Login, the keys specified in `user-data` and `ssh-keys` are removed from the metadata.
* After disabling access to a VM via OS Login, the removed keys are recreated.

{% endnote %}