Prev Next

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"
    }
  }
}

Version 5.0.0 — Feb 01, 2022

Prev Next