# openstack.compute.v2.server

## The Server Class

The `Server` class inherits from `Resource`.

class openstack.compute.v2.server.Server(_synchronized=False, connection=None, **attrs)

  The base resource

  Parameters:

    - _synchronized (bool) – This is not intended to be used directly. See `new()` and `existing()`.

    - connection (openstack.connection.Connection) – Reference to the Connection being used. Defaults to None to allow Resource objects to be used without an active Connection, such as in unit tests. Use of `self._connection` in Resource code should protect itself with a check for None.

  resource_key = 'server'

    Singular form of key for resource.

  resources_key = 'servers'

    Plural form of key for resource.

  base_path = '/servers'

    The base part of the URI for this resource.

  allow_create = True

    Allow create operation for this resource.

  allow_fetch = True

    Allow get operation for this resource.

  allow_commit = True

    Allow update operation for this resource.

  allow_delete = True

    Allow delete operation for this resource.

  allow_list = True

    Allow list operation for this resource.

  links

    A list of dictionaries holding links relevant to this server.

  addresses

    A dictionary of addresses this server can be accessed through. The dictionary contains keys such as `private` and `public`, each containing a list of dictionaries for addresses of that type. The addresses are contained in a dictionary with keys `addr` and `version`, which is either 4 or 6 depending on the protocol of the IP address. Type: dict

  admin_password

    When a server is first created, it provides the administrator password.

  attached_volumes

    A list of an attached volumes. Each item in the list contains at least an “id” key to identify the specific volumes.

  availability_zone

    The name of the availability zone this server is a part of.

  block_device_mapping

    Enables fine grained control of the block device mapping for an instance. This is typically used for booting servers from volumes.

  config_drive

    Indicates whether or not a config drive was used for this server.

  compute_host

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

  created_at

    Timestamp of when the server was created.

  description

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

  disk_config

    The disk configuration. Either AUTO or MANUAL.

  flavor_id

    The flavor reference, as a ID or full URL, for the flavor to use for this server.

  flavor

    The flavor property as returned from server.

  has_config_drive

    Indicates whether a configuration drive enables metadata injection. Not all cloud providers enable this feature.

  host_id

    An ID representing the host of this server.

  fault

    A fault object. Only available when the server status is ERROR or DELETED and a fault occurred.

  host

    The host to boot the server on.

  host_status

    The host status.

  hostname

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

  hypervisor_hostname

    The hypervisor host name. Appears in the response for administrative users only.

  image_id

    The image reference, as a ID or full URL, for the image to use for this server.

  image

    The image property as returned from server.

  instance_name

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

  interface_ip

    The address to use to connect to this server from the current calling context. This will be set to public_ipv6 if the calling host has routable ipv6 addresses, and to private_ipv4 if the Connection was created with private=True. Otherwise it will be set to public_ipv4.

  kernel_id

    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.

  key_name

    The name of an associated keypair

  launch_index

    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.

  launched_at

    The timestamp when the server was launched.

  locked_reason

    The reason the server was locked, if any.

  max_count

    The maximum number of servers to create.

  min_count

    The minimum number of servers to create.

  networks

    A networks object. Required parameter when there are multiple networks defined for the tenant. When you do not specify the networks parameter, the server attaches to the only network created for the current tenant.

  personality

    Personality files. This should be a list of dicts with each dict containing a file name (‘name’) and a base64-encoded file contents (‘contents’)

  pinned_availability_zone

    The availability zone requested during server creation OR pinned availability zone, which is configured using default_schedule_zone config option.

  power_state

    The power state of this server.

  progress

    While the server is building, this value represents the percentage of completion. Once it is completed, it will be 100. Type: int

  project_id

    The ID of the project this server is associated with.

  private_v4

    The private IPv4 address of this server

  private_v6

    The private IPv6 address of this server

  public_v4

    The public IPv4 address of this server

  public_v6

    The public IPv6 address of this server

  ramdisk_id

    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.

  reservation_id

    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.

  root_device_name

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

  scheduler_hints

    The dictionary of data to send to the scheduler.

  security_groups

    A list of applicable security groups. Each group contains keys for description, name, id, and rules.

  server_groups

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

  status

    The state this server is in. Valid values include `ACTIVE`, `BUILDING`, `DELETED`, `ERROR`, `HARD_REBOOT`, `PASSWORD`, `PAUSED`, `REBOOT`, `REBUILD`, `RESCUED`, `RESIZED`, `REVERT_RESIZE`, `SHUTOFF`, `SOFT_DELETED`, `STOPPED`, `SUSPENDED`, `UNKNOWN`, or `VERIFY_RESIZE`.

  task_state

    The task state of this server.

  terminated_at

    The timestamp when the server was terminated (if it has been).

  trusted_image_certificates

    A list of trusted certificate IDs, that were used during image signature verification to verify the signing certificate.

  updated_at

    Timestamp of when this server was last updated.

  user_data

    Configuration information or scripts to use upon launch. Must be Base64 encoded.

  user_id

    The ID of the owners of this server.

  vm_state

    The VM state of this server.

  change_password(session, password, *, microversion=None)

    Change the administrator password to the given password.

    Parameters:

      - session – The session to use for making this request.

      - password – The new password.

    Returns:

      None

  get_password(session, *, microversion=None)

    Get the encrypted administrator password.

    Parameters:

      session – The session to use for making this request.

    Returns:

      The encrypted administrator password.

  clear_password(session, *, microversion=None)

    Clear the administrator password.

    This removes the password from the database. It does not actually change the server password.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  reboot(session, reboot_type)

    Reboot server where reboot_type might be ‘SOFT’ or ‘HARD’.

    Parameters:

      - session – The session to use for making this request.

      - reboot_type – The type of reboot. One of: `SOFT`, `HARD`.

    Returns:

      None

  force_delete(session)

    Force delete the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  rebuild(session, image, name=<openstack.types.Unset object>, admin_password=<openstack.types.Unset object>, preserve_ephemeral=<openstack.types.Unset object>, access_ipv4=<openstack.types.Unset object>, access_ipv6=<openstack.types.Unset object>, metadata=<openstack.types.Unset object>, user_data=<openstack.types.Unset object>, key_name=<openstack.types.Unset object>, description=<openstack.types.Unset object>, trusted_image_certificates=<openstack.types.Unset object>, hostname=<openstack.types.Unset object>)

    Rebuild the server with the given arguments.

    Parameters:

      - session – The session to use for making this request.

      - image – The image to rebuild to. Either an ID or a `Image` instance.

      - name – A name to set on the rebuilt server. (Optional)

      - admin_password – An admin password to set on the rebuilt server. (Optional)

      - preserve_ephemeral – Whether to preserve the ephemeral drive during the rebuild. (Optional)

      - access_ipv4 – An IPv4 address that will be used to access the rebuilt server. (Optional)

      - access_ipv6 – An IPv6 address that will be used to access the rebuilt server. (Optional)

      - metadata – Metadata to set on the updated server. (Optional)

      - user_data – User data to set on the updated server. (Optional)

      - key_name – A key name to set on the updated server. (Optional)

      - description – The description to set on the updated server. (Optional) (Requires API microversion 2.19)

      - trusted_image_certificates – The trusted image certificates to set on the updated server. (Optional) (Requires API microversion 2.78)

      - hostname – The hostname to set on the updated server. (Optional) (Requires API microversion 2.90)

    Returns:

      The updated server.

  resize(session, flavor)

    Resize server to flavor reference.

    Parameters:

      - session – The session to use for making this request.

      - flavor – The server to resize to.

    Returns:

      None

  confirm_resize(session)

    Confirm the resize of the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  revert_resize(session)

    Revert the resize of the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  create_image(session, name, metadata=None)

    Create image from server.

    Parameters:

      - session – The session to use for making this request.

      - name – The name to use for the created image.

      - metadata – Metadata to set on the created image. (Optional)

    Returns:

      None

  add_security_group(session, security_group_name)

    Add a security group to the server.

    Parameters:

      - session – The session to use for making this request.

      - security_group_name – The security group to add to the server.

    Returns:

      None

  remove_security_group(session, security_group_name)

    Remove a security group from the server.

    Parameters:

      - session – The session to use for making this request.

      - security_group_name – The security group to remove from the server.

    Returns:

      None

  reset_state(session, state)

    Reset server state.

    This is admin-only by default.

    Parameters:

      - session – The session to use for making this request.

      - state – The state to set on the server.

    Returns:

      None

  add_fixed_ip(session, network_id)

    Add a fixed IP to the server.

    This is effectively an alias for adding a network.

    Parameters:

      - session – The session to use for making this request.

      - network_id – The network to connect the server to.

    Returns:

      None

  remove_fixed_ip(session, address)

    Remove a fixed IP from the server.

    This is effectively an alias from removing a port from the server.

    Parameters:

      - session – The session to use for making this request.

      - network_id – The address to remove from the server.

    Returns:

      None

  add_floating_ip(session, address, fixed_address=None)

    Add a floating IP to the server.

    Parameters:

      - session – The session to use for making this request.

      - address – The floating IP address to associate with the server.

      - fixed_address – A fixed IP address with which to associated the floating IP. (Optional)

    Returns:

      None

  remove_floating_ip(session, address)

    Remove a floating IP from the server.

    Parameters:

      - session – The session to use for making this request.

      - address – The floating IP address to disassociate from the server.

    Returns:

      None

  backup(session, name, backup_type, rotation)

    Create a backup of the server.

    Parameters:

      - session – The session to use for making this request.

      - name – The name to use for the backup image.

      - backup_type – The type of backup. The value and meaning of this atribute is user-defined and can be used to separate backups of different types. For example, this could be used to distinguish between `daily` and `weekly` backups.

      - rotation – The number of backups to retain. All images older than the rotation’th image will be deleted.

    Returns:

      None

  pause(session)

    Pause the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  unpause(session)

    Unpause the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  suspend(session)

    Suspend the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  resume(session)

    Resume the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  lock(session, locked_reason=None)

    Lock the server.

    Parameters:

      - session – The session to use for making this request.

      - locked_reason – The reason for locking the server.

    Returns:

      None

  unlock(session)

    Unlock the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  rescue(session, admin_pass=None, image_ref=None)

    Rescue the server.

    This is admin-only by default.

    Parameters:

      - session – The session to use for making this request.

      - admin_pass – A new admin password to set on the rescued server. (Optional)

      - image_ref – The image to use when rescuing the server. If not provided, the server will use the existing image. (Optional)

    Returns:

      None

  unrescue(session)

    Unrescue the server.

    This is admin-only by default.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  evacuate(session, host=None, admin_pass=None, force=None, on_shared_storage=None)

    Evacuate the server.

    Parameters:

      - session – The session to use for making this request.

      - host – The host to evacuate the instance to. (Optional)

      - admin_pass – The admin password to set on the evacuated instance. (Optional)

      - force – Whether to force evacuation.

      - on_shared_storage – Whether the host is using shared storage. (Optional) (Only supported before microversion 2.14)

    Returns:

      None

  start(session)

    Start the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  stop(session)

    Stop the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  restore(session)

    Restore the server.

    This is only supported if the server is soft-deleted. This is cloud-specific.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  shelve(session)

    Shelve the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  shelve_offload(session)

    Shelve-offload the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  unshelve(session, availability_zone=<openstack.types.Unset object>, host=None)

    Unshelve the server.

    Parameters:

      - session – The session to use for making this request.

      - availability_zone – If specified the instance will be unshelved to the availability_zone. If None is passed the instance defined availability_zone is unpin and the instance will be scheduled to any availability_zone (free scheduling). If not specified the instance will be unshelved to either its defined availability_zone or any availability_zone (free scheduling).

      - host – If specified the host to unshelve the instance.

  migrate(session, *, host=None)

    Migrate the server.

    Parameters:

      - session – The session to use for making this request.

      - host – The host to migrate the server to. (Optional)

    Returns:

      None

  trigger_crash_dump(session)

    Trigger a crash dump for the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  get_console_output(session, length=None)

    Get console output for the server.

    Parameters:

      - session – The session to use for making this request.

      - length – The max length of the console output to return. (Optional)

    Returns:

      None

  get_console_url(session, console_type)

    Get the console URL for the server.

    Parameters:

      - session – The session to use for making this request.

      - console_type – The type of console to return. This is cloud-specific. One of: `novnc`, `xvpvnc`, `spice-html5`, `spice-direct` (after Nova microversion 2.99), `rdp-html5`, or `serial`.

    Returns:

      None

  live_migrate(session, host, force, block_migration, disk_over_commit=False)

    Live migrate the server.

    Parameters:

      - session – The session to use for making this request.

      - host – The host to live migrate the server to. (Optional)

      - force – Whether to force the migration. (Optional)

      - block_migration – Whether to do block migration. One of: `True`, `False`, `'auto'`. (Optional)

      - disk_over_commit – Whether to allow disk over-commit on the destination host. (Optional)

    Returns:

      None

  fetch_topology(session)

    Fetch the topology information for the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  fetch_security_groups(session)

    Fetch security groups of the server.

    Parameters:

      session – The session to use for making this request.

    Returns:

      Updated Server instance.

this page last updated: 2026-01-16 23:06:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.