13.4. Updating virtual machines configuration

PUT /servers/{server_id}

Update the editable attributes of a VM with the specified ID. One parameter at a time.

Source: https://docs.openstack.org/api-ref/compute/?expanded=#update-server

13.4.1. Request

Name In Type Description
server_id path string The UUID of the server.
server body object A server object.
accessIPv4 (Optional) body string IPv4 address that should be used to access this server.
accessIPv6 (Optional) body string IPv6 address that should be used to access this server.
name (Optional) body string The server name.
OS-DCF:diskConfig (Optional) body string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.
  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.
description (Optional) body string

A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name.

New in version 2.19

13.4.1.1. Example

# curl -ks -X PUT -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "server": {
    "name": "vm1-renamed"
  }
}' https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers/642b7726-bc3b-4824-872b-124097d2d20c

13.4.2. Response

Name In Type Description
server body object A server object.
accessIPv4 body string IPv4 address that should be used to access this server. May be automatically set by the provider.
accessIPv6 body string IPv6 address that should be used to access this server. May be automatically set by the provider.
addresses body object The addresses for the server. Servers with status BUILD hide their addresses information.
created body string

The date and time when the resource was created. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

flavor body object

Before microversion 2.47 this contains the ID and links for the flavor used to boot the server instance. This can be an empty object in case flavor information is no longer present in the system.

As of microversion 2.47 this contains a subset of the actual flavor information used to create the server instance, represented as a nested dictionary.

flavor.id body string

The ID of the flavor. While people often make this look like an int, this is really a string.

Available until version 2.46

flavor.links body array

Links to the flavor resource. See API Guide / Links and References for more info.

Available until version 2.46

flavor.vcpus body integer

The number of virtual CPUs that were allocated to the server.

New in version 2.47

flavor.ram body integer

The amount of RAM a flavor has, in MiB.

New in version 2.47

flavor.disk body integer

The size of the root disk that was created in GiB.

New in version 2.47

flavor.ephemeral body integer

The size of the ephemeral disk that was created, in GiB.

New in version 2.47

flavor.swap body integer

The size of a dedicated swap disk that was allocated, in MiB.

New in version 2.47

flavor.original_name body string

The display name of a flavor.

New in version 2.47

flavor.extra_specs (Optional) body object

A dictionary of the flavor’s extra-specs key-and-value pairs. This will only be included if the user is allowed by policy to index flavor extra_specs.

New in version 2.47

flavor.extra_specs.key body string

The extra spec key of a flavor.

New in version 2.47

flavor.extra_specs.value body string

The extra spec value of a flavor.

New in version 2.47

hostId body string An ID string representing the host. This is a hashed value so will not actually look like a hostname, and is hashed with data from the project_id, so the same physical host as seen by two different project_ids, will be different. It is useful when within the same project you need to determine if two instances are on the same or different physical hosts for the purposes of availability or performance.
id body string The UUID of the server.
image body object The UUID and links for the image for your server instance. The image object will be an empty string when you boot the server from a volume.
links body array Links to the resources in question. See API Guide / Links and References for more info.
metadata body object A dictionary of metadata key-and-value pairs, which is maintained for backward compatibility.
name body string The server name.
OS-DCF:diskConfig body string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.
  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.
status body string The server status.
tenant_id body string The UUID of the tenant in a multi-tenancy cloud.
updated body string

The date and time when the resource was updated. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

user_id body string The user ID of the user who owns the server.
fault (Optional) body object A fault object. Only displayed when the server status is ERROR or DELETED and a fault occurred.
fault.code body integer The error response code.
fault.created body string

The date and time when the exception was raised. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

fault.message body string The error message.
fault.details (Optional) body string The stack trace. It is available if the response code is not 500 or you have the administrator privilege
progress (Optional) body integer A percentage value of the operation progress. This parameter only appears when the server status is ACTIVE, BUILD, REBUILD, RESIZE, VERIFY_RESIZE or MIGRATING.
locked body boolean

True if the instance is locked otherwise False.

New in version 2.9

description body string

The description of the server. Before microversion 2.19 this was set to the server name.

New in version 2.19

tags body array

A list of tags. The maximum count of tags in this list is 50.

New in version 2.26

trusted_image_certificates body array

A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. The value is null if trusted certificate IDs are not set.

New in version 2.63

server_groups body array

The UUIDs of the server groups to which the server belongs. Currently this can contain at most one entry.

New in version 2.71

locked_reason body string

The reason behind locking a server.

New in version 2.73

config_drive body string

Indicates whether or not a config drive was used for this server. The value is True or an empty string. An empty string stands for False.

New in version 2.75

OS-EXT-AZ:availability_zone body string

The availability zone name.

New in version 2.75

OS-EXT-SRV-ATTR:host body string

The name of the compute host on which this instance is running. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:hypervisor_hostname body string

The hypervisor host name provided by the Nova virt driver. For the Ironic driver, it is the Ironic node uuid. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:instance_name body string

The instance name. The Compute API generates the instance name from the instance name template. Appears in the response for administrative users only.

New in version 2.75

OS-EXT-STS:power_state body integer

The power state of the instance. This is an enum value that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED

New in version 2.75

OS-EXT-STS:task_state body string

The task state of the instance.

New in version 2.75

OS-EXT-STS:vm_state body string

The VM state.

New in version 2.75

OS-EXT-SRV-ATTR:hostname (Optional) body string

The hostname set on the instance when it is booted. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:reservation_id (Optional) body string

The reservation id for the server. This is an id that can be useful in tracking groups of servers created with multiple create, that will all have the same reservation_id. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:launch_index (Optional) body integer

When servers are launched via multiple create, this is the sequence in which the servers were launched. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:kernel_id (Optional) body string

The UUID of the kernel image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:ramdisk_id (Optional) body string

The UUID of the ramdisk image when using an AMI. Will be null if not. By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:root_device_name (Optional) body string

The root device name for the instance By default, it appears in the response for administrative users only.

New in version 2.75

OS-EXT-SRV-ATTR:user_data (Optional) body string

The user_data the instance was created with. By default, it appears in the response for administrative users only.

New in version 2.75

os-extended-volumes:volumes_attached body array

The attached volumes, if any.

New in version 2.75

os-extended-volumes:volumes_attached.id body string

The attached volume ID.

New in version 2.75

os-extended-volumes:volumes_attached.delete_on_termination body boolean

A flag indicating if the attached volume will be deleted when the server is deleted. By default this is False.

New in version 2.75

OS-SRV-USG:launched_at body string

The date and time when the server was launched.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The hh±:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.

New in version 2.75

OS-SRV-USG:terminated_at body string

The date and time when the server was deleted.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. If the deleted_at date and time stamp is not set, its value is null.

New in version 2.75

security_groups (Optional) body array

One or more security groups objects.

New in version 2.75

security_group.name body string

The security group name.

New in version 2.75

host_status (Optional) body string

The host status. Values where next value in list can override the previous:

  • UP if nova-compute up.
  • UNKNOWN if nova-compute not reported by servicegroup driver.
  • DOWN if nova-compute forced down.
  • MAINTENANCE if nova-compute is disabled.
  • Empty string indicates there is no host for server.

This attribute appears in the response only if the policy permits. By default, only administrators can get this parameter.

New in version 2.75

key_name body string

The name of associated key pair, if any.

New in version 2.75

13.4.2.1. Status codes

13.4.2.1.1. Success

Code Reason
200 - OK Request was successful.

13.4.2.1.2. Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

13.4.2.2. Example

{
  "server": {
    "status": "ACTIVE",
    "updated": "2020-02-10T12:53:35Z",
    "hostId": "07a515b19bd643cd2422089ea20d5043e1161004b62e297f4e52196f",
    "user_id": "eb481bff7b7c4ec6a686646957d8064b",
    "name": "vm1-renamed",
    "links": [
      {
        "href": "https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers/642b7726-bc3b-4824-872b-124097d2d20c",
        "rel": "self"
      },
      {
        "href": "https://<node_IP_addr>:8774/f5d834d636c642c7bfe8af86139c6f26/servers/642b7726-bc3b-4824-872b-124097d2d20c",
        "rel": "bookmark"
      }
    ],
    "created": "2020-02-10T12:37:42Z",
    "tenant_id": "f5d834d636c642c7bfe8af86139c6f26",
    "image": "",
    "OS-DCF:diskConfig": "MANUAL",
    "addresses": {
      "public": [
        {
          "version": 4,
          "addr": "10.94.139.172"
        }
      ],
      "private": [
        {
          "version": 4,
          "addr": "192.168.128.88"
        }
      ]
    },
    "accessIPv4": "",
    "accessIPv6": "",
    "progress": 0,
    "flavor": {
      "id": "100",
      "links": [
        {
          "href": "https://<node_IP_addr>:8774/f5d834d636c642c7bfe8af86139c6f26/flavors/100",
          "rel": "bookmark"
        }
      ]
    },
    "id": "642b7726-bc3b-4824-872b-124097d2d20c",
    "metadata": {
      "ha_enabled": "True"
    }
  }
}