diff --git a/doc/source/cli/command-objects/server.rst b/doc/source/cli/command-objects/server.rst index 1118282204..a7fef2578c 100644 --- a/doc/source/cli/command-objects/server.rst +++ b/doc/source/cli/command-objects/server.rst @@ -4,990 +4,83 @@ server Compute v2 -server add fixed ip -------------------- +.. autoprogram-cliff:: openstack.compute.v2 + :command: server add * -Add fixed IP address to server +.. autoprogram-cliff:: openstack.compute.v2 + :command: server create -.. program:: server add fixed ip -.. code:: bash +.. autoprogram-cliff:: openstack.compute.v2 + :command: server delete - openstack server add fixed ip - [--fixed-ip-address ] - - +.. autoprogram-cliff:: openstack.compute.v2 + :command: server dump create -.. option:: --fixed-ip-address +.. autoprogram-cliff:: openstack.compute.v2 + :command: server list - Requested fixed IP address +.. autoprogram-cliff:: openstack.compute.v2 + :command: server lock -.. describe:: +.. autoprogram-cliff:: openstack.compute.v2 + :command: server migrate - Server to receive the fixed IP address (name or ID) +.. autoprogram-cliff:: openstack.compute.v2 + :command: server pause -.. describe:: +.. autoprogram-cliff:: openstack.compute.v2 + :command: server reboot - Network to allocate the fixed IP address from (name or ID) +.. autoprogram-cliff:: openstack.compute.v2 + :command: server rebuild -server add floating ip ----------------------- +.. autoprogram-cliff:: openstack.compute.v2 + :command: server remove * -Add floating IP address to server +.. autoprogram-cliff:: openstack.compute.v2 + :command: server rescue -.. program:: server add floating ip -.. code:: bash +.. autoprogram-cliff:: openstack.compute.v2 + :command: server resize - openstack server add floating ip - [--fixed-ip-address ] - - +.. autoprogram-cliff:: openstack.compute.v2 + :command: server restore -.. option:: --fixed-ip-address +.. autoprogram-cliff:: openstack.compute.v2 + :command: server resume - Fixed IP address to associate with this floating IP address +.. autoprogram-cliff:: openstack.compute.v2 + :command: server set -.. describe:: +.. autoprogram-cliff:: openstack.compute.v2 + :command: server shelve - Server to receive the floating IP address (name or ID) +.. autoprogram-cliff:: openstack.compute.v2 + :command: server show -.. describe:: +.. autoprogram-cliff:: openstack.compute.v2 + :command: server ssh - Floating IP address to assign to server (IP only) +.. autoprogram-cliff:: openstack.compute.v2 + :command: server start -server add port ---------------- +.. autoprogram-cliff:: openstack.compute.v2 + :command: server stop -Add port to server +.. autoprogram-cliff:: openstack.compute.v2 + :command: server suspend -.. program:: server add port -.. code:: bash +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unlock - openstack server add port - - +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unpause -.. describe:: +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unrescue - Server to add the port to (name or ID) +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unset -.. describe:: - - Port to add to the server (name or ID) - -server add security group -------------------------- - -Add security group to server - -.. program:: server add security group -.. code:: bash - - openstack server add security group - - - -.. describe:: - - Server (name or ID) - -.. describe:: - - Security group to add (name or ID) - -server add volume ------------------ - -Add volume to server - -.. program:: server add volume -.. code:: bash - - openstack server add volume - [--device ] - - - -.. option:: --device - - Server internal device name for volume - -.. describe:: - - Server (name or ID) - -.. describe:: - - Volume to add (name or ID) - -server create -------------- - -Create a new server - -.. program:: server create -.. code:: bash - - openstack server create - --image | --volume - --flavor - [--security-group [...] ] - [--key-name ] - [--property [...] ] - [--file ] [...] ] - [--user-data ] - [--availability-zone ] - [--block-device-mapping [...] ] - [--nic [...] ] - [--network ] - [--port ] - [--hint [...] ] - [--config-drive |True ] - [--min ] - [--max ] - [--wait] - - -.. option:: --image - - Create server boot disk from this image (name or ID) - -.. option:: --volume - - Create server using this volume as the boot disk (name or ID) - - This option automatically creates a block device mapping with a boot - index of 0. On many hypervisors (libvirt/kvm for example) this will - be device ``vda``. Do not create a duplicate mapping using - :option:`--block-device-mapping` for this volume. - -.. option:: --flavor - - Create server with this flavor (name or ID) - -.. option:: --security-group - - Security group to assign to this server (name or ID) - (repeat option to set multiple groups) - -.. option:: --key-name - - Keypair to inject into this server (optional extension) - -.. option:: --property - - Set a property on this server - (repeat option to set multiple values) - -.. option:: --file - - File to inject into image before boot - (repeat option to set multiple files) - -.. option:: --user-data - - User data file to serve from the metadata server - -.. option:: --availability-zone - - Select an availability zone for the server - -.. option:: --block-device-mapping - - Create a block device on the server. - - Block device mapping in the format - - =::: - - : block device name, like: vdb, xvdc (required) - - : UUID of the volume or snapshot (required) - - : volume or snapshot; default: volume (optional) - - : volume size if create from snapshot (optional) - - : true or false; default: false (optional) - - (optional extension) - -.. option:: --nic - - Create a NIC on the server. Specify option multiple times to create - multiple NICs. Either net-id or port-id must be provided, but not both. - net-id: attach NIC to network with this UUID, - port-id: attach NIC to port with this UUID, - v4-fixed-ip: IPv4 fixed address for NIC (optional), - v6-fixed-ip: IPv6 fixed address for NIC (optional). - none: (v2.37+) no network is attached. - auto: (v2.37+) the compute service will automatically allocate a network. - Specifying a --nic of auto or none cannot be used with any other - --nic value. - -.. option:: --network - - Create a NIC on the server and connect it to network. - Specify option multiple times to create multiple NICs. - For more options on NICs see --nic parameter. - network: attach NIC to this network - -.. option:: --port - - Create a NIC on the server and connect it to port. - Specify option multiple times to create multiple NICs. - For more options on NICs see --nic parameter. - port: attach NIC to this port - -.. option:: --hint - - Hints for the scheduler (optional extension) - -.. option:: --config-drive |True - - Use specified volume as the config drive, or 'True' to use an ephemeral drive - -.. option:: --min - - Minimum number of servers to launch (default=1) - -.. option:: --max - - Maximum number of servers to launch (default=1) - -.. option:: --wait - - Wait for build to complete - -.. describe:: - - New server name - -.. - -The parameters ``--network `` and ``--port `` are actually -wrappers to ``--nic net-id=`` and ``--nic port-id=``. ``--nic`` -also provides additional options to specify an IP address, automatic network -assignment and NICs which are not assigned to any port. This functionality -is not part of ``--network`` and ``--port``, which aim to provide a simple -syntax for the standard use cases of connecting a new server to a given -network or port. - -server delete -------------- - -Delete server(s) - -.. program:: server delete -.. code:: bash - - openstack server delete - [ ...] [--wait] - -.. option:: --wait - - Wait for delete to complete - -.. describe:: - - Server(s) to delete (name or ID) - -server dump create ------------------- -Create a dump file in server(s) - -Trigger crash dump in server(s) with features like kdump in Linux. It will -create a dump file in the server(s) dumping the server(s)' memory, and also -crash the server(s). OSC sees the dump file (server dump) as a kind of -resource. - -.. program:: server dump create -.. code:: bash - - openstack server dump create - [ ...] - -.. describe:: - - Server(s) to create dump file (name or ID) - -server list ------------ - -List servers - -.. code:: bash - - openstack server list - [--reservation-id ] - [--ip ] - [--ip6 ] - [--name ] - [--instance-name ] - [--status ] - [--flavor ] - [--image ] - [--host ] - [--all-projects] - [--project [--project-domain ]] - [--long] - [--no-name-lookup | -n] - [--marker ] - [--limit ] - [--deleted] - [--changes-since ] - -.. option:: --reservation-id - - Only return instances that match the reservation - -.. option:: --ip - - Regular expression to match IP addresses - -.. option:: --ip6 - - Regular expression to match IPv6 addresses - -.. option:: --name - - Regular expression to match names - -.. option:: --instance-name - - Regular expression to match instance name (admin only) - -.. option:: --status - - Search by server status - -.. option:: --flavor - - Search by flavor (name or ID) - -.. option:: --image - - Search by image (name or ID) - -.. option:: --host - - Search by hostname - -.. option:: --all-projects - - Include all projects (admin only) - -.. option:: --project - - Search by project (admin only) (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --user - - Search by user (admin only) (name or ID) - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - This can be used in case collisions between user names exist. - -.. option:: --long - - List additional fields in output - -.. option:: --no-name-lookup - - Skips image and flavor names lookup - - ``-n`` may be used as an alias for this option. - -.. option:: --marker - - The last server of the previous page. Display list of servers - after marker. Display all servers if not specified. (name or ID) - -.. option:: --limit - - Maximum number of servers to display. If limit equals -1, all servers will - be displayed. If limit is greater than 'osapi_max_limit' option of Nova - API, 'osapi_max_limit' will be used instead. - -.. option:: --deleted - - Only display deleted servers (Admin only). - -.. option:: --changes-since - - List only servers changed after a certain point of time. The provided time - should be an ISO 8061 formatted time. ex 2016-03-04T06:27:59Z. - -server lock ------------ - -Lock server(s). A non-admin user will not be able to execute actions - -.. program:: server lock -.. code:: bash - - openstack server lock - [ ...] - -.. describe:: - - Server(s) to lock (name or ID) - -server migrate --------------- - -Migrate server to different host - -.. program:: server migrate -.. code:: bash - - openstack server migrate - --live - [--shared-migration | --block-migration] - [--disk-overcommit | --no-disk-overcommit] - [--wait] - - -.. option:: --live - - Target hostname - -.. option:: --shared-migration - - Perform a shared live migration (default) - -.. option:: --block-migration - - Perform a block live migration - -.. option:: --disk-overcommit - - Allow disk over-commit on the destination host - -.. option:: --no-disk-overcommit - - Do not over-commit disk on the destination host (default) - -.. option:: --wait - - Wait for migrate to complete - -.. describe:: - - Server to migrate (name or ID) - -server pause ------------- - -Pause server(s) - -.. program:: server pause -.. code:: bash - - openstack server pause - [ ...] - -.. describe:: - - Server(s) to pause (name or ID) - -server reboot -------------- - -Perform a hard or soft server reboot - -.. program:: server reboot -.. code:: bash - - openstack server reboot - [--hard | --soft] - [--wait] - - -.. option:: --hard - - Perform a hard reboot - -.. option:: --soft - - Perform a soft reboot - -.. option:: --wait - - Wait for reboot to complete - -.. describe:: - - Server (name or ID) - -server rebuild --------------- - -Rebuild server - -.. program:: server rebuild -.. code:: bash - - openstack server rebuild - [--image ] - [--password ] - [--wait] - - -.. option:: --image - - Recreate server from the specified image (name or ID). Defaults to the - currently used one. - -.. option:: --password - - Set the password on the rebuilt instance - -.. option:: --wait - - Wait for rebuild to complete - -.. describe:: - - Server (name or ID) - -server remove fixed ip ----------------------- - -Remove fixed IP address from server - -.. program:: server remove fixed ip -.. code:: bash - - openstack server remove fixed ip - - - -.. describe:: - - Server to remove the fixed IP address from (name or ID) - -.. describe:: - - Fixed IP address to remove from the server (IP only) - -server remove floating ip -------------------------- - -Remove floating IP address from server - -.. program:: server remove floating ip -.. code:: bash - - openstack server remove floating ip - - - -.. describe:: - - Server to remove the floating IP address from (name or ID) - -.. describe:: - - Floating IP address to remove from server (IP only) - -server remove port ------------------- - -Remove port from server - -.. program:: server remove port -.. code:: bash - - openstack server remove port - - - -.. describe:: - - Server to remove the port from (name or ID) - -.. describe:: - - Port to remove from the server (name or ID) - -server remove security group ----------------------------- - -Remove security group from server - -.. program:: server remove security group -.. code:: bash - - openstack server remove security group - - - -.. describe:: - - Name or ID of server to use - -.. describe:: - - Name or ID of security group to remove from server - -server remove volume --------------------- - -Remove volume from server - -.. program:: server remove volume -.. code:: bash - - openstack server remove volume - - - -.. describe:: - - Server (name or ID) - -.. describe:: - - Volume to remove (name or ID) - -server rescue -------------- - -Put server in rescue mode - -.. program:: server rescue -.. code:: bash - - openstack server rescue - - -.. describe:: - - Server (name or ID) - -server resize -------------- - -Scale server to a new flavor - -.. program:: server resize -.. code:: bash - - openstack server resize - --flavor - [--wait] - - - openstack server resize - --confirm | --revert - - -.. option:: --flavor - - Resize server to specified flavor - -.. option:: --confirm - - Confirm server resize is complete - -.. option:: --revert - - Restore server state before resize - -.. option:: --wait - - Wait for resize to complete - -.. describe:: - - Server (name or ID) - -A resize operation is implemented by creating a new server and copying -the contents of the original disk into a new one. It is also a two-step -process for the user: the first is to perform the resize, the second is -to either confirm (verify) success and release the old server, or to declare -a revert to release the new server and restart the old one. - -server restore --------------- - -Restore server(s) from soft-deleted state - -.. program:: server restore -.. code:: bash - - openstack server restore - [ ...] - -.. describe:: - - Server(s) to restore (name or ID) - -server resume -------------- - -Resume server(s) - -.. program:: server resume -.. code:: bash - - openstack server resume - [ ...] - -.. describe:: - - Server(s) to resume (name or ID) - -server set ----------- - -Set server properties - -.. program:: server set -.. code:: bash - - openstack server set - --name - --property - [--property ] ... - --root-password - --state - - -.. option:: --name - - New server name - -.. option:: --root-password - - Set new root password (interactive only) - -.. option:: --property - - Property to add/change for this server - (repeat option to set multiple properties) - -.. option:: --state - - New server state (valid value: active, error) - -.. describe:: - - Server (name or ID) - -server shelve -------------- - -Shelve server(s) - -.. program:: server shelve -.. code:: bash - - openstack server shelve - [ ...] - -.. describe:: - - Server(s) to shelve (name or ID) - -server show ------------ - -Show server details - -.. program:: server show -.. code:: bash - - openstack server show - [--diagnostics] - - -.. option:: --diagnostics - - Display server diagnostics information - -.. describe:: - - Server (name or ID) - -server ssh ----------- - -SSH to server - -.. program:: server ssh -.. code:: bash - - openstack server ssh - [--login ] - [--port ] - [--identity ] - [--option ] - [--public | --private | --address-type ] - - -.. option:: --login - - Login name (ssh -l option) - -.. option:: --port - - Destination port (ssh -p option) - -.. option:: --identity - - Private key file (ssh -i option) - -.. option:: --option - - Options in ssh_config(5) format (ssh -o option) - -.. option:: --public - - Use public IP address - -.. option:: --private - - Use private IP address - -.. option:: --address-type - - Use other IP address (public, private, etc) - -.. describe:: - - Server (name or ID) - -server start ------------- - -Start server(s) - -.. program:: server start -.. code:: bash - - openstack server start - [ ...] - -.. describe:: - - Server(s) to start (name or ID) - -server stop ------------ - -Stop server(s) - -.. program:: server stop -.. code:: bash - - openstack server stop - [ ...] - -.. describe:: - - Server(s) to stop (name or ID) - -server suspend --------------- - -Suspend server(s) - -.. program:: server suspend -.. code:: bash - - openstack server suspend - [ ...] - -.. describe:: - - Server(s) to suspend (name or ID) - -server unlock -------------- - -Unlock server(s) - -.. program:: server unlock -.. code:: bash - - openstack server unlock - [ ...] - -.. describe:: - - Server(s) to unlock (name or ID) - -server unpause --------------- - -Unpause server(s) - -.. program:: server unpause -.. code:: bash - - openstack server unpause - [ ...] - -.. describe:: - - Server(s) to unpause (name or ID) - -server unrescue ---------------- - -Restore server from rescue mode - -.. program:: server unrescue -.. code:: bash - - openstack server unrescue - - -.. describe:: - - Server (name or ID) - -server unset ------------- - -Unset server properties - -.. program:: server unset -.. code:: bash - - openstack server unset - --property - [--property ] ... - - -.. option:: --property - - Property key to remove from server - (repeat option to remove multiple values) - -.. describe:: - - Server (name or ID) - -server unshelve ---------------- - -Unshelve server(s) - -.. program:: server unshelve -.. code:: bash - - openstack server unshelve - [ ...] - -.. describe:: - - Server(s) to unshelve (name or ID) +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unshelve diff --git a/doc/source/conf.py b/doc/source/conf.py index fc7520fd0d..bd4fa73031 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -34,6 +34,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'openstackdocstheme', 'stevedore.sphinxext', + 'cliff.sphinxext', ] # openstackdocstheme options @@ -269,3 +270,12 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' + + +# -- Options for cliff.sphinxext plugin --------------------------------------- + +autoprogram_cliff_application = 'openstack' + +autoprogram_cliff_ignored = [ + '--help', '--format', '--column', '--max-width', '--fit-width', + '--print-empty', '--prefix', '--noindent'] diff --git a/openstackclient/compute/v2/server.py b/openstackclient/compute/v2/server.py index ce4191c1cd..151c6783c7 100644 --- a/openstackclient/compute/v2/server.py +++ b/openstackclient/compute/v2/server.py @@ -394,10 +394,13 @@ class CreateServer(command.ShowOne): disk_group.add_argument( '--volume', metavar='', - help=_( - 'Create server using this volume as the boot disk ' - '(name or ID)' - ), + help=_('Create server using this volume as the boot disk (name ' + 'or ID).\n' + 'This option automatically creates a block device mapping ' + 'with a boot index of 0. On many hypervisors (libvirt/kvm ' + 'for example) this will be device vda. Do not create a ' + 'duplicate mapping using --block-device-mapping for this ' + 'volume.'), ) parser.add_argument( '--flavor', @@ -489,8 +492,11 @@ class CreateServer(command.ShowOne): type=_prefix_checked_value('net-id='), help=_("Create a NIC on the server and connect it to network. " "Specify option multiple times to create multiple NICs. " - "For more options on NICs see --nic parameter. " - "network: attach NIC to this network "), + "This is a wrapper for the '--nic net-id=' " + "parameter that provides simple syntax for the standard " + "use case of connecting a new server to a given network. " + "For more advanced use cases, refer to the '--nic' " + "parameter."), ) parser.add_argument( '--port', @@ -500,8 +506,10 @@ class CreateServer(command.ShowOne): type=_prefix_checked_value('port-id='), help=_("Create a NIC on the server and connect it to port. " "Specify option multiple times to create multiple NICs. " - "For more options on NICs see --nic parameter. " - "port: attach NIC this port "), + "This is a wrapper for the '--nic port-id=' " + "parameter that provides simple syntax for the standard " + "use case of connecting a new server to a given port. For " + "more advanced use cases, refer to the '--nic' parameter."), ) parser.add_argument( '--hint', @@ -1591,7 +1599,13 @@ class RescueServer(command.ShowOne): class ResizeServer(command.Command): - _description = _("Scale server to a new flavor") + _description = _("""Scale server to a new flavor. + +A resize operation is implemented by creating a new server and copying the +contents of the original disk into a new one. It is also a two-step process for +the user: the first is to perform the resize, the second is to either confirm +(verify) success and release the old server, or to declare a revert to release +the new server and restart the old one.""") def get_parser(self, prog_name): parser = super(ResizeServer, self).get_parser(prog_name)