<commit_before>===============
Server concepts
===============

For the OpenStack Compute API, a server is a virtual machine (VM) instance,
a physical machine or a container.

Server status
~~~~~~~~~~~~~

You can filter the list of servers by image, flavor, name, and status
through the respective query parameters.

Server contains a status attribute that indicates the current server
state. You can filter on the server status when you complete a list
servers request. The server status is returned in the response body. The
server status is one of the following values:

**Server status values**

-  ``ACTIVE``: The server is active.

-  ``BUILD``: The server has not yet finished the original build process.

-  ``DELETED``: The server is deleted.

-  ``ERROR``: The server is in error.

-  ``HARD_REBOOT``: The server is hard rebooting. This is equivalent to
   pulling the power plug on a physical server, plugging it back in, and
   rebooting it.

-  ``MIGRATING``: The server is migrating. This is caused by a
   live migration (moving a server that is active) action.

-  ``PASSWORD``: The password is being reset on the server.

-  ``PAUSED``: The server is paused.

-  ``REBOOT``: The server is in a soft reboot state. A reboot command
   was passed to the operating system.

-  ``REBUILD``: The server is currently being rebuilt from an image.

-  ``RESCUE``: The server is in rescue mode.

-  ``RESIZE``: Server is performing the differential copy of data that
   changed during its initial copy. Server is down for this stage.

-  ``REVERT_RESIZE``: The resize or migration of a server failed for
   some reason. The destination server is being cleaned up and the
   original source server is restarting.

-  ``SHELVED``: The server is in shelved state. Depends on the shelve offload
   time, the server will be automatically shelved off loaded.

-  ``SHELVED_OFFLOADED``: The shelved server is offloaded (removed from the
   compute host) and it needs unshelved action to be used again.

-  ``SHUTOFF``: The server was powered down by the user, either through the
   OpenStack Compute API or from within the server. For example, the user
   issued a :command:`shutdown -h` command from within the server.
   If the OpenStack Compute manager detects that the VM was powered down,
   it transitions the server to the SHUTOFF status.

-  ``SOFT_DELETED``: The server is marked as deleted but will remain in the
   cloud for some configurable amount of time. While soft-deleted, an
   authorized user can restore the server back to normal state. When the time
   expires, the server will be deleted permanently.

-  ``SUSPENDED``: The server is suspended, either by request or
   necessity. This status appears for only the following hypervisors:
   XenServer/XCP, KVM, and ESXi. Administrative users may suspend a
   server if it is infrequently used or to perform system maintenance.
   When you suspend a server, its state is stored on disk, all
   memory is written to disk, and the server is stopped.
   Suspending a server is similar to placing a device in hibernation;
   memory and vCPUs become available to create other servers.

-  ``UNKNOWN``: The state of the server is unknown. It could be because a part
   of the infrastructure is temporarily down (see :doc:`down_cells`
   for more information). Contact your cloud provider.

-  ``VERIFY_RESIZE``: System is awaiting confirmation that the server is
   operational after a move or resize.

Server status is caculated from vm_state and task_state, which
are exposed to administrators:

- vm_state describes a VM's current stable (not transition) state. That is, if
  there is no ongoing compute API calls (running tasks), vm_state should reflect
  what the customer expect the VM to be. When combined with task states,
  a better picture can be formed regarding the server's health and progress.
  Refer to :nova-doc:`VM States <reference/vm-states.html>`.

- task_state represents what is happening to the instance at the
  current moment. These tasks can be generic, such as `spawning`, or specific,
  such as `block_device_mapping`. These task states allow for a better view into
  what a server is doing.

Server creation
~~~~~~~~~~~~~~~

Status Transition:

- ``BUILD``

  .. todo:: Add more details.

- ``ACTIVE``

  .. todo:: Add more details.

- ``ERROR`` (on error)

  When you create a server, the operation asynchronously provisions a new
  server. The progress of this operation depends on several factors
  including location of the requested image, network I/O, host load, and
  the selected flavor. The progress of the request can be checked by
  performing a **GET** on /servers/*{server_id}*, which returns a progress
  attribute (from 0% to 100% complete). The full URL to the newly created
  server is returned through the ``Location`` header and is available as a
  ``self`` and ``bookmark`` link in the server representation. Note that
  when creating a server, only the server ID, its links, and the
  administrative password are guaranteed to be returned in the request.
  You can retrieve additional attributes by performing subsequent **GET**
  operations on the server.

Server query
~~~~~~~~~~~~

There are two APIs for querying servers ``GET /servers`` and
``GET /servers/detail``. Both of those APIs support filtering the query result
by using query options.

For different user roles, the user has different query options set:

- For general user, there is limited set of attributes of the servers can be
  used as query option. ``reservation_id``, ``name``, ``status``, ``image``,
  ``flavor``, ``ip``, ``changes-since``, ``changes-before``, ``ip6``,
  ``tags``, ``tags-any``, ``not-tags``, ``not-tags-any`` are supported options
  to be used. Other options will be ignored by nova silently.

- For administrator, most of the server attributes can be used as query
  options. Before the Ocata release, the fields in the database schema of
  server are exposed as query options, which may lead to unexpected API
  change. After the Ocata release, the definition of the query options and
  the database schema are decoupled. That is also the reason why the naming of
  the query options are different from the attribute naming in the servers API
  response.


Precondition: there are 2 servers existing in cloud with following info::

  {
      "servers": [
          {
              "name": "t1",
              "OS-EXT-STS:vm_state": "active",
              ...
          },
          {
              "name": "t2",
              "OS-EXT-STS:vm_state": "stopped",
              ...
          }<commit_msg>[Docs] Change the server query parameter display into a list.<commit_after>===============
Server concepts
===============

For the OpenStack Compute API, a server is a virtual machine (VM) instance,
a physical machine or a container.

Server status
~~~~~~~~~~~~~

You can filter the list of servers by image, flavor, name, and status
through the respective query parameters.

Server contains a status attribute that indicates the current server
state. You can filter on the server status when you complete a list
servers request. The server status is returned in the response body. The
server status is one of the following values:

**Server status values**

-  ``ACTIVE``: The server is active.

-  ``BUILD``: The server has not yet finished the original build process.

-  ``DELETED``: The server is deleted.

-  ``ERROR``: The server is in error.

-  ``HARD_REBOOT``: The server is hard rebooting. This is equivalent to
   pulling the power plug on a physical server, plugging it back in, and
   rebooting it.

-  ``MIGRATING``: The server is migrating. This is caused by a
   live migration (moving a server that is active) action.

-  ``PASSWORD``: The password is being reset on the server.

-  ``PAUSED``: The server is paused.

-  ``REBOOT``: The server is in a soft reboot state. A reboot command
   was passed to the operating system.

-  ``REBUILD``: The server is currently being rebuilt from an image.

-  ``RESCUE``: The server is in rescue mode.

-  ``RESIZE``: Server is performing the differential copy of data that
   changed during its initial copy. Server is down for this stage.

-  ``REVERT_RESIZE``: The resize or migration of a server failed for
   some reason. The destination server is being cleaned up and the
   original source server is restarting.

-  ``SHELVED``: The server is in shelved state. Depends on the shelve offload
   time, the server will be automatically shelved off loaded.

-  ``SHELVED_OFFLOADED``: The shelved server is offloaded (removed from the
   compute host) and it needs unshelved action to be used again.

-  ``SHUTOFF``: The server was powered down by the user, either through the
   OpenStack Compute API or from within the server. For example, the user
   issued a :command:`shutdown -h` command from within the server.
   If the OpenStack Compute manager detects that the VM was powered down,
   it transitions the server to the SHUTOFF status.

-  ``SOFT_DELETED``: The server is marked as deleted but will remain in the
   cloud for some configurable amount of time. While soft-deleted, an
   authorized user can restore the server back to normal state. When the time
   expires, the server will be deleted permanently.

-  ``SUSPENDED``: The server is suspended, either by request or
   necessity. This status appears for only the following hypervisors:
   XenServer/XCP, KVM, and ESXi. Administrative users may suspend a
   server if it is infrequently used or to perform system maintenance.
   When you suspend a server, its state is stored on disk, all
   memory is written to disk, and the server is stopped.
   Suspending a server is similar to placing a device in hibernation;
   memory and vCPUs become available to create other servers.

-  ``UNKNOWN``: The state of the server is unknown. It could be because a part
   of the infrastructure is temporarily down (see :doc:`down_cells`
   for more information). Contact your cloud provider.

-  ``VERIFY_RESIZE``: System is awaiting confirmation that the server is
   operational after a move or resize.

Server status is caculated from vm_state and task_state, which
are exposed to administrators:

- vm_state describes a VM's current stable (not transition) state. That is, if
  there is no ongoing compute API calls (running tasks), vm_state should reflect
  what the customer expect the VM to be. When combined with task states,
  a better picture can be formed regarding the server's health and progress.
  Refer to :nova-doc:`VM States <reference/vm-states.html>`.

- task_state represents what is happening to the instance at the
  current moment. These tasks can be generic, such as `spawning`, or specific,
  such as `block_device_mapping`. These task states allow for a better view into
  what a server is doing.

Server creation
~~~~~~~~~~~~~~~

Status Transition:

- ``BUILD``

  .. todo:: Add more details.

- ``ACTIVE``

  .. todo:: Add more details.

- ``ERROR`` (on error)

  When you create a server, the operation asynchronously provisions a new
  server. The progress of this operation depends on several factors
  including location of the requested image, network I/O, host load, and
  the selected flavor. The progress of the request can be checked by
  performing a **GET** on /servers/*{server_id}*, which returns a progress
  attribute (from 0% to 100% complete). The full URL to the newly created
  server is returned through the ``Location`` header and is available as a
  ``self`` and ``bookmark`` link in the server representation. Note that
  when creating a server, only the server ID, its links, and the
  administrative password are guaranteed to be returned in the request.
  You can retrieve additional attributes by performing subsequent **GET**
  operations on the server.

Server query
~~~~~~~~~~~~

There are two APIs for querying servers ``GET /servers`` and
``GET /servers/detail``. Both of those APIs support filtering the query result
by using query options.

For different user roles, the user has different query options set:

- For general user, there is limited set of attributes of the servers can be
  used as query option. The supported options are:

  - ``changes-since``
  - ``flavor``
  - ``image``
  - ``ip``
  - ``ip6`` (New in version 2.5)
  - ``name``
  - ``not-tags`` (New in version 2.26)
  - ``not-tags-any`` (New in version 2.26)
  - ``reservation_id``
  - ``status``
  - ``tags`` (New in version 2.26)
  - ``tags-any`` (New in version 2.26)
  - ``changes-before`` (New in version 2.66)

  Other options will be ignored by nova silently.

- For administrator, most of the server attributes can be used as query
  options. Before the Ocata release, the fields in the database schema of
  server are exposed as query options, which may lead to unexpected API
  change. After the Ocata release, the definition of the query options and
  the database schema are decoupled. That is also the reason why the naming of
  the query options are different from the attribute naming in the servers API
  response.


Precondition: there are 2 servers existing in cloud with following info::

  {
      "servers": [
          {
              "name": "t1",
              "OS-EXT-STS:vm_state": "active",
              ...
          },
          {
              "name": "t2",
              "OS-EXT-STS:vm_state": "stopped",
              ...
          }
{'fraction_non_alphanumeric': 0.0816204944891272, 'fraction_numerical': 0.0024575513851653264, 'mean_word_length': 3.5215488215488215, 'pattern_counts': {'":': 10, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6066660', 'n_tokens_mistral': 3595, 'n_tokens_neox': 3515, 'n_words': 1911}