diff options
| author | Thomas Goirand <zigo@debian.org> | 2016-01-14 05:30:14 +0000 |
|---|---|---|
| committer | git-ubuntu importer <ubuntu-devel-discuss@lists.ubuntu.com> | 2016-01-14 10:10:52 +0000 |
| commit | e0d4c1dc3577ed26f13556ccead5c4d478c7b45f (patch) | |
| tree | 55f2c7a117edc5ab3e2ea0c3b4a60a2aee0e0722 /doc/source | |
| parent | bf2067db8c46b8842569fa37ba675f3e1d4246b8 (diff) | |
2.0.0-1 (patches unapplied)import/2.0.0-1
Imported using git-ubuntu import.
Notes
Notes:
* New upstream release.
* Fixed (build-)depends for this release.
Diffstat (limited to 'doc/source')
29 files changed, 1166 insertions, 101 deletions
diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst index bf23b66..a3986ee 100644 --- a/doc/source/authentication.rst +++ b/doc/source/authentication.rst @@ -83,7 +83,7 @@ by the ``ClientManager`` object. * Load the selected plugin class. * When an operation that requires authentication is attempted ``ClientManager`` - makes the actual inital request to the Identity service. + makes the actual initial request to the Identity service. * if ``--os-auth-url`` is not supplied for any of the types except Token/Endpoint, exit with an error. @@ -132,7 +132,7 @@ If using a domain as authorization scope, set either it's name or ID. Note that if the user and project share the same domain, then simply setting ``os-default-domain`` or ``OS_DEFAULT_DOMAIN`` is sufficient. -Thus, a minimal set of of environment variables would be: +Thus, a minimal set of environment variables would be: .. code-block:: bash diff --git a/doc/source/backwards-incompatible.rst b/doc/source/backwards-incompatible.rst index e89cc3a..94873c1 100644 --- a/doc/source/backwards-incompatible.rst +++ b/doc/source/backwards-incompatible.rst @@ -90,6 +90,30 @@ List of Backwards Incompatible Changes * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1453229 * Commit: https://review.openstack.org/#/c/181514/ +7. `image set` commands will no longer return the modified resource + + Previously, modifying an image would result in the new image being displayed + to the user. To keep things consistent with other `set` commands, we will + no longer be showing the modified resource. + + * In favor of: Use `set` then `show` + * As of: NA + * Removed in: NA + * Bug: NA + * Commit: NA + +8. `region` commands no longer support `url` + + The Keystone team removed support for thr `url` attribute from the client + and server side. Changes to the `create`, `set` and `list` commands for + regions have been affected. + + * In favor of: NA + * As of 1.9.0 + * Removed in: NA + * Bug: https://launchpad.net/bugs/1506841 + * Commit: https://review.openstack.org/#/c/236736/ + For Developers ============== diff --git a/doc/source/command-objects/compute-agent.rst b/doc/source/command-objects/compute-agent.rst new file mode 100644 index 0000000..395ee4f --- /dev/null +++ b/doc/source/command-objects/compute-agent.rst @@ -0,0 +1,100 @@ +============= +compute agent +============= + +Compute v2 + +compute agent create +-------------------- + +Create compute agent + +.. program:: compute agent create +.. code:: bash + + os compute agent create + <os> <architecture> <version> <url> <md5hash> + <hypervisor> + +.. _compute_agent-create: +.. describe:: <os> + + Type of OS + +.. describe:: <architecture> + + Type of architecture + +.. describe:: <version> + + Version + +.. describe:: <url> + + URL + +.. describe:: <md5hash> + + MD5 hash + +.. describe:: <hypervisor> + + Type of hypervisor + +compute agent delete +-------------------- + +Delete compute agent command + +.. program:: compute agent delete +.. code:: bash + + os compute agent delete <id> + +.. _compute_agent-delete: +.. describe:: <id> + + ID of agent to delete + +compute agent list +------------------ + +List compute agent command + +.. program:: compute agent list +.. code:: bash + + os compute agent list [--hypervisor <hypervisor>] + +.. _compute_agent-list: +.. describe:: --hypervisor <hypervisor> + + Optional type of hypervisor + +compute agent set +----------------- + +Set compute agent command + +.. program:: agent set +.. code:: bash + + os compute agent set + <id> <version> <url> <md5hash> + +.. _compute_agent-set: +.. describe:: <id> + + ID of the agent + +.. describe:: <version> + + Version of the agent + +.. describe:: <url> + + URL + +.. describe:: <md5hash> + + MD5 hash diff --git a/doc/source/command-objects/compute-service.rst b/doc/source/command-objects/compute-service.rst new file mode 100644 index 0000000..95a77bd --- /dev/null +++ b/doc/source/command-objects/compute-service.rst @@ -0,0 +1,73 @@ +=============== +compute service +=============== + +Compute v2 + +compute service delete +---------------------- + +Delete service command + +.. program:: compute service delete +.. code:: bash + + os compute service delete + <service> + +.. _compute-service-delete: +.. describe:: <service> + + Compute service to delete (ID only) + +compute service list +-------------------- + +List service command + +.. program:: compute service list +.. code:: bash + + os compute service list + [--host <host>] + [--service <service>] + +.. _compute-service-list: +.. describe:: --host <host> + + Name of host + +.. describe:: --service <service> + + Name of service + + +compute service set +------------------- + +Set service command + +.. program:: compute service set +.. code:: bash + + os compute service list + [--enable | --disable] + <host> <service> + +.. _compute-service-set: +.. describe:: --enable + + Enable service + +.. describe:: --disable + + Disable service + +.. describe:: <host> + + Name of host + +.. describe:: <service> + + Name of service + diff --git a/doc/source/command-objects/container.rst b/doc/source/command-objects/container.rst index 3372f4d..e6517e9 100644 --- a/doc/source/command-objects/container.rst +++ b/doc/source/command-objects/container.rst @@ -2,7 +2,7 @@ container ========= -Object Store v1 +Object Storage v1 container create ---------------- @@ -89,6 +89,26 @@ Save container contents locally Container to save +container set +------------- + +Set container properties + +.. program:: container set +.. code:: bash + + os container set + [--property <key=value> [...] ] + [<container>] + +.. option:: --property <key=value> + + Set a property on this container (repeat option to set multiple properties) + +.. describe:: <container> + + Container to modify + container show -------------- @@ -103,3 +123,23 @@ Display container details .. describe:: <container> Container to display + +container unset +--------------- + +Unset container properties + +.. program:: container unset +.. code:: bash + + os container unset + [--property <key>] + [<container>] + +.. option:: --property <key> + + Property to remove from container (repeat option to remove multiple properties) + +.. describe:: <container> + + Container to modify diff --git a/doc/source/command-objects/flavor.rst b/doc/source/command-objects/flavor.rst index 5254b12..2389f7d 100644 --- a/doc/source/command-objects/flavor.rst +++ b/doc/source/command-objects/flavor.rst @@ -91,6 +91,8 @@ List flavors os flavor list [--public | --private | --all] [--long] + [--marker <marker>] + [--limit <limit>] .. option:: --public @@ -108,6 +110,14 @@ List flavors List additional fields in output +.. option:: --marker <marker> + + The last flavor ID of the previous page + +.. option:: --limit <limit> + + Maximum number of flavors to display + flavor show ----------- diff --git a/doc/source/command-objects/identity-provider.rst b/doc/source/command-objects/identity-provider.rst index 90f0b49..ac46273 100644 --- a/doc/source/command-objects/identity-provider.rst +++ b/doc/source/command-objects/identity-provider.rst @@ -81,6 +81,7 @@ Set identity provider properties os identity provider set [--remote-id <remote-id> [...] | --remote-id-file <file-name>] + [--description <description>] [--enable | --disable] <identity-provider> @@ -94,6 +95,10 @@ Set identity provider properties Name of a file that contains many remote IDs to associate with the identity provider, one per line +.. option:: --description + + Set identity provider description + .. option:: --enable Enable the identity provider diff --git a/doc/source/command-objects/image.rst b/doc/source/command-objects/image.rst index d2698b0..d4b9916 100644 --- a/doc/source/command-objects/image.rst +++ b/doc/source/command-objects/image.rst @@ -57,8 +57,6 @@ Create/upload an image Image owner project name or ID - *Image version 1 only.* - .. option:: --size <size> Image size, in bytes (only used with --location and --copy-from) @@ -238,6 +236,13 @@ Set image properties [--checksum <checksum>] [--stdin] [--property <key=value> [...] ] + [--tag <tag> [...] ] + [--architecture <architecture>] + [--instance-id <instance-id>] + [--kernel-id <kernel-id>] + [--os-distro <os-distro>] + [--os-version <os-version>] + [--ramdisk-id <ramdisk-id>] <image> .. option:: --name <name> @@ -258,14 +263,11 @@ Set image properties .. option:: --container-format <container-format> - Container format of image. - Acceptable formats: ['ami', 'ari', 'aki', 'bare', 'ovf'] + Image container format (default: bare) .. option:: --disk-format <disk-format> - Disk format of image. - Acceptable formats: ['ami', 'ari', 'aki', 'vhd', 'vmdk', 'raw', 'qcow2', - 'vdi', 'iso'] + Image disk format (default: raw) .. option:: --size <size> @@ -339,45 +341,49 @@ Set image properties .. option:: --property <key=value> - Set a property on this image (repeat for multiple values) + Set a property on this image (repeat option to set multiple properties) - *Image version 1 only.* + .. versionadded:: 2 + +.. option:: --tag <tag> + + Set a tag on this image (repeat for multiple values) + + .. versionadded:: 2 .. option:: --architecture <architecture> - Operating system Architecture + Operating system architecture .. versionadded:: 2 -.. option:: --ramdisk-id <ramdisk-id> +.. option:: --instance-id <instance-id> - ID of image stored in Glance that should be used as - the ramdisk when booting an AMI-style image + ID of server instance used to create this image .. versionadded:: 2 -.. option:: --os-distro <os-distro> +.. option:: --kernel-id <kernel-id> - Common name of operating system distribution + ID of kernel image used to boot this disk image .. versionadded:: 2 -.. option:: --os-version <os-version> +.. option:: --os-distro <os-distro> - Operating system version as specified by the distributor + Operating system distribution name .. versionadded:: 2 -.. option:: --kernel-id <kernel-id> +.. option:: --os-version <os-version> - ID of image in Glance that should be used as the - kernel when booting an AMI-style image + Operating system distribution version .. versionadded:: 2 -.. option:: --instance-uuid <instance_uuid> +.. option:: --ramdisk-id <ramdisk-id> - ID of instance used to create this image + ID of ramdisk image used to boot this disk image .. versionadded:: 2 diff --git a/doc/source/command-objects/ip-fixed.rst b/doc/source/command-objects/ip-fixed.rst new file mode 100644 index 0000000..3a55b99 --- /dev/null +++ b/doc/source/command-objects/ip-fixed.rst @@ -0,0 +1,45 @@ +======== +ip fixed +======== + +Compute v2 + +ip fixed add +------------ + +Add fixed IP address to server + +.. program:: ip fixed add +.. code:: bash + + os ip fixed add + <network> + <server> + +.. describe:: <network> + + Network to fetch an IP address from (name or ID) + +.. describe:: <server> + + Server to receive the IP address (name or ID) + +ip fixed remove +--------------- + +Remove fixed IP address from server + +.. program:: ip fixed remove +.. code:: bash + + os ip fixed remove + <ip-address> + <server> + +.. describe:: <ip-address> + + IP address to remove from server (name only) + +.. describe:: <server> + + Server to remove the IP address from (name or ID) diff --git a/doc/source/command-objects/ip-floating-pool.rst b/doc/source/command-objects/ip-floating-pool.rst new file mode 100644 index 0000000..63a450e --- /dev/null +++ b/doc/source/command-objects/ip-floating-pool.rst @@ -0,0 +1,15 @@ +================ +ip floating pool +================ + +Compute v2 + +ip floating pool list +--------------------- + +List pools of floating IP addresses + +.. program:: ip floating pool list +.. code:: bash + + os ip floating pool list diff --git a/doc/source/command-objects/floatingip.rst b/doc/source/command-objects/ip-floating.rst index 1ae3041..6bfd7f4 100644 --- a/doc/source/command-objects/floatingip.rst +++ b/doc/source/command-objects/ip-floating.rst @@ -1,24 +1,24 @@ -========== -floatingip -========== +=========== +ip floating +=========== Compute v2 ip floating add --------------- -Add floating-ip to server +Add floating IP address to server .. program:: ip floating add .. code:: bash os ip floating add - <ip_address> + <ip-address> <server> -.. describe:: <ip_address> +.. describe:: <ip-address> - IP address to add to server + IP address to add to server (name only) .. describe:: <server> @@ -27,7 +27,7 @@ Add floating-ip to server ip floating create ------------------ -Create new floating-ip +Create new floating IP address .. program:: ip floating create .. code:: bash @@ -37,27 +37,27 @@ Create new floating-ip .. describe:: <pool> - Pool to fetch floating IP from + Pool to fetch IP address from (name or ID) ip floating delete ------------------ -Delete a floating-ip +Delete a floating IP address .. program:: ip floating delete .. code:: bash os ip floating delete - <ip_address> + <ip-address> -.. describe:: <ip_address> +.. describe:: <ip-address> - IP address to delete + IP address to delete (ID only) ip floating list ---------------- -List floating-ips +List floating IP addresses .. program:: ip floating list .. code:: bash @@ -67,18 +67,18 @@ List floating-ips ip floating remove ------------------ -Remove floating-ip from server +Remove floating IP address from server .. program:: ip floating remove .. code:: bash os ip floating remove - <ip_address> + <ip-address> <server> -.. describe:: <ip_address> +.. describe:: <ip-address> - IP address to remove from server + IP address to remove from server (name only) .. describe:: <server> diff --git a/doc/source/command-objects/object-store-account.rst b/doc/source/command-objects/object-store-account.rst new file mode 100644 index 0000000..ba37078 --- /dev/null +++ b/doc/source/command-objects/object-store-account.rst @@ -0,0 +1,45 @@ +==================== +object store account +==================== + +Object Storage v1 + +object store account set +------------------------ + +Set account properties + +.. program:: object store account set +.. code:: bash + + os object store account set + [--property <key=value> [...] ] + +.. option:: --property <key=value> + + Set a property on this account (repeat option to set multiple properties) + +object store account show +------------------------- + +Display account details + +.. program:: object store account show +.. code:: bash + + os object store account show + +object store account unset +-------------------------- + +Unset account properties + +.. program:: object store account unset +.. code:: bash + + os object store account unset + [--property <key>] + +.. option:: --property <key> + + Property to remove from account (repeat option to remove multiple properties) diff --git a/doc/source/command-objects/object.rst b/doc/source/command-objects/object.rst index 90bcfa1..5aaad8a 100644 --- a/doc/source/command-objects/object.rst +++ b/doc/source/command-objects/object.rst @@ -2,7 +2,7 @@ object ====== -Object Store v1 +Object Storage v1 object create ------------- @@ -119,6 +119,31 @@ Save object locally Object to save +object set +---------- + +Set object properties + +.. program:: object set +.. code:: bash + + os object set + [--property <key=value> [...] ] + <container> + [<object>] + +.. option:: --property <key=value> + + Set a property on this object (repeat option to set multiple properties) + +.. describe:: <container> + + Modify <object> from <container> + +.. describe:: <object> + + Object to modify + object show ----------- @@ -138,3 +163,28 @@ Display object details .. describe:: <object> Object to display + +object unset +------------ + +Unset object properties + +.. program:: object unset +.. code:: bash + + os object unset + [--property <key>] + <container> + [<object>] + +.. option:: --property <key> + + Property to remove from object (repeat option to remove multiple properties) + +.. describe:: <container> + + Modify <object> from <container> + +.. describe:: <object> + + Object to modify diff --git a/doc/source/command-objects/region.rst b/doc/source/command-objects/region.rst index cb4a059..1892fc2 100644 --- a/doc/source/command-objects/region.rst +++ b/doc/source/command-objects/region.rst @@ -15,7 +15,6 @@ Create new region os region create [--parent-region <region-id>] [--description <description>] - [--url <url>] <region-id> .. option:: --parent-region <region-id> @@ -26,10 +25,6 @@ Create new region New region description -.. option:: --url <url> - - New region URL - .. _region_create-region-id: .. describe:: <region-id> @@ -77,7 +72,6 @@ Set region properties os region set [--parent-region <region-id>] [--description <description>] - [--url <url>] <region-id> .. option:: --parent-region <region-id> @@ -88,10 +82,6 @@ Set region properties New region description -.. option:: --url <url> - - New region URL - .. _region_set-region-id: .. describe:: <region-id> diff --git a/doc/source/command-objects/security-group-rule.rst b/doc/source/command-objects/security-group-rule.rst new file mode 100644 index 0000000..8bd0d06 --- /dev/null +++ b/doc/source/command-objects/security-group-rule.rst @@ -0,0 +1,65 @@ +=================== +security group rule +=================== + +Compute v2 + +security group rule create +-------------------------- + +Create a new security group rule + +.. program:: security group rule create +.. code:: bash + + os security group rule create + [--proto <proto>] + [--src-ip <ip-address>] + [--dst-port <port-range>] + <group> + +.. option:: --proto <proto> + + IP protocol (icmp, tcp, udp; default: tcp) + +.. option:: --src-ip <ip-address> + + Source IP (may use CIDR notation; default: 0.0.0.0/0) + +.. option:: --dst-port <port-range> + + Destination port, may be a range: 137:139 (default: 0; only required for proto tcp and udp) + +.. describe:: <group> + + Create rule in this security group (name or ID) + +security group rule delete +-------------------------- + +Delete a security group rule + +.. program:: security group rule delete +.. code:: bash + + os security group rule delete + <rule> + +.. describe:: <rule> + + Security group rule to delete (ID only) + +security group rule list +------------------------ + +List security group rules + +.. program:: security group rule list +.. code:: bash + + os security group rule list + <group> + +.. describe:: <group> + + List all rules in this security group (name or ID) diff --git a/doc/source/command-objects/security-group.rst b/doc/source/command-objects/security-group.rst new file mode 100644 index 0000000..60de41d --- /dev/null +++ b/doc/source/command-objects/security-group.rst @@ -0,0 +1,95 @@ +============== +security group +============== + +Compute v2 + +security group create +--------------------- + +Create a new security group + +.. program:: security group create +.. code:: bash + + os security group create + [--description <description>] + <name> + +.. option:: --description <description> + + Security group description + +.. describe:: <name> + + New security group name + +security group delete +--------------------- + +Delete a security group + +.. program:: security group delete +.. code:: bash + + os security group delete + <group> + +.. describe:: <group> + + Security group to delete (name or ID) + +security group list +------------------- + +List security groups + +.. program:: security group list +.. code:: bash + + os security group list + [--all-projects] + +.. option:: --all-projects + + Display information from all projects (admin only) + +security group set +------------------ + +Set security group properties + +.. program:: security group set +.. code:: bash + + os security group set + [--name <new-name>] + [--description <description>] + <group> + +.. option:: --name <new-name> + + New security group name + +.. option:: --description <description> + + New security group description + +.. describe:: <group> + + Security group to modify (name or ID) + +security group show +------------------- + +Display security group details + +.. program:: security group show +.. code:: bash + + os security group show + <group> + +.. describe:: <group> + + Security group to display (name or ID) diff --git a/doc/source/command-objects/server.rst b/doc/source/command-objects/server.rst index 9ff4843..506a82d 100644 --- a/doc/source/command-objects/server.rst +++ b/doc/source/command-objects/server.rst @@ -165,7 +165,7 @@ Delete server(s) .. describe:: <server> - Server to delete (name or ID) + Server(s) to delete (name or ID) server list ----------- @@ -187,6 +187,8 @@ List servers [--all-projects] [--project <project> [--project-domain <project-domain>]] [--long] + [--marker <server>] + [--limit <limit>] .. option:: --reservation-id <reservation-id> @@ -250,20 +252,31 @@ List servers List additional fields in output +.. option:: --marker <server> + + The last server (name or ID) of the previous page. Display list of servers + after marker. Display all servers if not specified. + +.. option:: --limit <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. + server lock ----------- -Lock a server. A non-admin user will not be able to execute actions +Lock server(s). A non-admin user will not be able to execute actions .. program:: server lock .. code:: bash os server lock - <server> + <server> [<server> ...] .. describe:: <server> - Server (name or ID) + Server(s) to lock (name or ID) server migrate -------------- @@ -311,17 +324,17 @@ Migrate server to different host server pause ------------ -Pause server +Pause server(s) .. program:: server pause .. code:: bash os server pause - <server> + <server> [<server> ...] .. describe:: <server> - Server (name or ID) + Server(s) to pause (name or ID) server reboot ------------- @@ -483,17 +496,17 @@ a revert to release the new server and restart the old one. server resume ------------- -Resume server +Resume server(s) .. program:: server resume .. code:: bash os server resume - <server> + <server> [<server> ...] .. describe:: <server> - Server (name or ID) + Server(s) to resume (name or ID) server set ---------- @@ -527,6 +540,21 @@ Set server properties Server (name or ID) +server shelve +------------- + +Shelve server(s) + +.. program:: server shelve +.. code:: bash + + os server shelve + <server> [<server> ...] + +.. describe:: <server> + + Server(s) to shelve (name or ID) + server show ----------- @@ -595,50 +623,80 @@ Ssh to server Server (name or ID) +server start +------------ + +Start server(s) + +.. program:: server start +.. code:: bash + + os server start + <server> [<server> ...] + +.. describe:: <server> + + Server(s) to start (name or ID) + +server stop +----------- + +Stop server(s) + +.. program:: server stop +.. code:: bash + + os server stop + <server> [<server> ...] + +.. describe:: <server> + + Server(s) to stop (name or ID) + server suspend -------------- -Suspend server +Suspend server(s) .. program:: server suspend .. code:: bash os server suspend - <server> + <server> [<server> ...] .. describe:: <server> - Server (name or ID) + Server(s) to suspend (name or ID) server unlock ------------- -Unlock server +Unlock server(s) .. program:: server unlock .. code:: bash os server unlock - <server> + <server> [<server> ...] .. describe:: <server> - Server (name or ID) + Server(s) to unlock (name or ID) server unpause -------------- -Unpause server +Unpause server(s) .. program:: server unpause .. code:: bash os server unpause - <server> + <server> [<server> ...] .. describe:: <server> - Server (name or ID) + Server(s) to unpause (name or ID) server unrescue --------------- @@ -675,3 +733,18 @@ Unset server properties .. describe:: <server> Server (name or ID) + +server unshelve +--------------- + +Unshelve server(s) + +.. program:: server unshelve +.. code:: bash + + os server unshelve + <server> [<server> ...] + +.. describe:: <server> + + Server(s) to unshelve (name or ID) diff --git a/doc/source/command-objects/snapshot.rst b/doc/source/command-objects/snapshot.rst index 7bfd1d9..e05673b 100644 --- a/doc/source/command-objects/snapshot.rst +++ b/doc/source/command-objects/snapshot.rst @@ -60,6 +60,11 @@ List snapshots .. code:: bash os snapshot list + [--all-projects] + +.. option:: --all-projects + + Include all projects (admin only) .. option:: --long diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst index 556d164..cb52c56 100644 --- a/doc/source/command-objects/volume.rst +++ b/doc/source/command-objects/volume.rst @@ -102,18 +102,46 @@ List volumes .. code:: bash os volume list - [--status <status>] - [--name <name>] [--all-projects] + [--project <project> [--project-domain <project-domain>]] + [--user <user> [--user-domain <user-domain>]] + [--name <name>] + [--status <status>] [--long] -.. option:: --status <status> +.. option:: --project <project> - Filter results by status + Filter results by project (name or ID) (admin only) + + *Volume version 2 only* + +.. option:: --project-domain <project-domain> + + Domain the project belongs to (name or ID). + This can be used in case collisions between project names exist. + + *Volume version 2 only* + +.. option:: --user <user> + + Filter results by user (name or ID) (admin only) + + *Volume version 2 only* + +.. option:: --user-domain <user-domain> + + Domain the user belongs to (name or ID). + This can be used in case collisions between user names exist. + + *Volume version 2 only* .. option:: --name <name> - Filter results by name + Filter results by volume name + +.. option:: --status <status> + + Filter results by status .. option:: --all-projects diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst new file mode 100644 index 0000000..edafb15 --- /dev/null +++ b/doc/source/command-options.rst @@ -0,0 +1,135 @@ +=============== +Command Options +=============== + +OpenStackClient commands all have a set of zero or more options unique to +the command, however there are of course ways in which these options are +common and consistent across all of the commands that include them. + +These are the set of guidelines for OSC developers that help keep the +interface and commands consistent. + +In some cases (like the boolean variables below) we use the same pattern +for defining and using options in all situations. The alternative of only +using it when necessary leads to errors when copy-n-paste is used for a +new command without understanding why or why not that instance is correct. + +Boolean Options +=============== + +Boolean options for any command that sets a resource state, such as 'enabled' +or 'public', shall always have both positive and negative options defined. +The names of those options shall either be a naturally occuring pair of +words (in English) or a positive option and a negative option with `no-` +prepended (such as in the traditional GNU option usage) like `--share` and +`--no-share`. + +In order to handle those APIs that behave differently when a field is set to +`None` and when the field is not present in a passed argument list or dict, +each of the boolean options shall set its own variable to `True` as part of +a mutiually exclusive group, rather than the more common configuration of setting a +single destination variable `True` or `False` directly. This allows us to +detect the situation when neither option is present (both variables will be +`False`) and act accordingly for those APIs where this matters. + +This also requires that each of the boolean values be tested in the +`take_action()` method to correctly set (or not) the underlying API field +values. + +.. option:: --enable + + Enable <resource> (default) + +.. option:: --disable + + Disable <resource> + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this:: + +.. code-block: python + + enable_group = parser.add_mutually_exclusive_group() + enable_group.add_argument( + '--enable', + action='store_true', + help=_('Enable <resource> (default)'), + ) + enable_group.add_argument( + '--disable', + action='store_true', + help=_('Disable <resource>'), + ) + +An example handler in `take_action()`:: + + # This leaves 'enabled' undefined if neither option is present + if parsed_args.enable: + kwargs['enabled'] = True + if parsed_args.disable: + kwargs['enabled'] = False + +List Command Options +==================== + +Additional Fields +----------------- + +Most list commands only return a subset of the available fields by default. +Additional fields are available with the `--long` option. All list +commands should allow `--long` even if they return all fields by default. + +.. option:: --long + + List additional fields in output + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this:: + +.. code-block: python + + parser.add_argument( + '--long', + action='store_true', + default=False, + help='List additional fields in output', + ) + +Pagination +---------- + +There are many ways to do pagination, some OpenStack APIs support it, some don't. +OpenStackClient attempts to define a single common way to specify pagination on +the command line. + +.. option:: --marker <marker> + + Anchor for paging + +.. option:: --limit <limit> + + Limit number of <resource> returned (*integer*) + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this:: + +.. code-block: python + + parser.add_argument( + "--marker", + metavar="<marker>", + help="Anchor for paging", + ) + + parser.add_argument( + "--limit", + metavar="<limit>", + type=int, + help="Limit the number of <resource> returned", + ) diff --git a/doc/source/command-wrappers.rst b/doc/source/command-wrappers.rst new file mode 100644 index 0000000..b14eccd --- /dev/null +++ b/doc/source/command-wrappers.rst @@ -0,0 +1,52 @@ +====================== +Command Class Wrappers +====================== + +When we want to deprecate a command, policy says we need to alert the user. +We do this with a message logged at WARNING level before any command output +is emitted. + +OpenStackClient command classes are derived from the ``cliff`` classes. +Cliff uses ``setuptools`` entry points for dispatching the parsed command +to the respective handler classes. This lends itself to modifying the +command execution at run-time. + +The obvious approach to adding the deprecation message would be to just add +the message to the command class ``take_action()`` method directly. But then +the various deprecations are scattered throughout the code base. If we +instead wrap the deprecated command class with a new class we can put all of +the wrappers into a separate, dedicated module. This also lets us leave the +original class unmodified and puts all of the deprecation bits in one place. + +This is an example of a minimal wrapper around a command class that logs a +deprecation message as a warning to the user then calls the original class. + +* Subclass the deprecated command. + +* Set class attribute ``deprecated`` to ``True`` to signal cliff to not + emit help text for this command. + +* Log the deprecation message at WARNING level and refer to the replacement + for the deprecated command in the log warning message. + +* Change the entry point class in ``setup.cfg`` to point to the new class. + +Example Deprecation Class +------------------------- + +.. code-block: python + + class ListFooOld(ListFoo): + """List resources""" + + # This notifies cliff to not display the help for this command + deprecated = True + + log = logging.getLogger('deprecated') + + def take_action(self, parsed_args): + self.log.warning( + "%s is deprecated, use 'foobar list'", + getattr(self, 'cmd_name', 'this command'), + ) + return super(ListFooOld, self).take_action(parsed_args) diff --git a/doc/source/commands.rst b/doc/source/commands.rst index b52d945..6069895 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -77,10 +77,10 @@ referring to both Compute and Volume quotas. * ``console log``: (**Compute**) server console text dump * ``console url``: (**Compute**) server remote console URL * ``consumer``: (**Identity**) OAuth-based delegatee -* ``container``: (**Object Store**) a grouping of objects +* ``container``: (**Object Storage**) a grouping of objects * ``credentials``: (**Identity**) specific to identity providers * ``domain``: (**Identity**) a grouping of projects -* ``ec2 cedentials``: (**Identity**) AWS EC2-compatible credentials +* ``ec2 credentials``: (**Identity**) AWS EC2-compatible credentials * ``endpoint``: (**Identity**) the base URL used to contact a specific service * ``extension``: (**Compute**, **Identity**, **Volume**) OpenStack server API extensions * ``federation protocol``: (**Identity**) the underlying protocol used while federating identities @@ -91,14 +91,15 @@ referring to both Compute and Volume quotas. * ``hypervisor stats``: (**Compute**) hypervisor statistics over all compute nodes * ``identity provider``: (**Identity**) a source of users and authentication * ``image``: (**Image**) a disk image -* ``ip fixed``: Compute, Network - an internal IP address assigned to a server -* ``ip floating``: Compute, Network - a public IP address that can be mapped to a server +* ``ip fixed``: (**Compute**, **Network**) - an internal IP address assigned to a server +* ``ip floating``: (**Compute**, **Network**) - a public IP address that can be mapped to a server +* ``ip floating pool``: (**Compute**, **Network**) - a pool of public IP addresses * ``keypair``: (**Compute**) an SSH public key * ``limits``: (**Compute**, **Volume**) resource usage limits * ``mapping``: (**Identity**) a definition to translate identity provider attributes to Identity concepts * ``module``: internal - installed Python modules in the OSC process -* ``network``: Network - a virtual network for connecting servers and other resources -* ``object``: (**Object Store**) a single file in the Object Store +* ``network``: (**Network**) - a virtual network for connecting servers and other resources +* ``object``: (**Object Storage**) a single file in the Object Storage * ``policy``: (**Identity**) determines authorization * ``project``: (**Identity**) owns a group of resources * ``quota``: (**Compute**, **Volume**) resource usage restrictions @@ -106,8 +107,8 @@ referring to both Compute and Volume quotas. * ``request token``: (**Identity**) temporary OAuth-based token * ``role``: (**Identity**) a policy object used to determine authorization * ``role assignment``: (**Identity**) a relationship between roles, users or groups, and domains or projects -* ``security group``: Compute, Network - groups of network access rules -* ``security group rule``: Compute, Network - the individual rules that define protocol/IP/port access +* ``security group``: (**Compute**, **Network**) - groups of network access rules +* ``security group rule``: (**Compute**, **Network**) - the individual rules that define protocol/IP/port access * ``server``: (**Compute**) virtual machine instance * ``server image``: (**Compute**) saved server disk image * ``service``: (**Identity**) a cloud service @@ -120,6 +121,41 @@ referring to both Compute and Volume quotas. * ``volume``: (**Volume**) block volumes * ``volume type``: (**Volume**) deployment-specific types of volumes available + +Plugin Objects +-------------- + +The following are known `Objects` used by OpenStack :doc:`plugins`. These are +listed here to avoid name conflicts when creating new plugins. For a complete +list check out :doc:`plugin-commands`. + +* ``baremetal``: (**Baremetal (Ironic)**) +* ``congress datasource``: (**Policy (Congress)**) +* ``congress driver``: (**Policy (Congress)**) +* ``congress policy``: (**Policy (Congress)**) +* ``congress policy rule``: (**Policy (Congress)**) +* ``dataprocessing data source``: (**Data Processing (Sahara)**) +* ``dataprocessing image``: (**Data Processing (Sahara)**) +* ``dataprocessing image tags``: (**Data Processing (Sahara)**) +* ``dataprocessing plugin``: (**Data Processing (Sahara)**) +* ``management plan``: (**Management (Tuskar)**) +* ``management role``: (**Management (Tuskar)**) +* ``message-broker cluster``: (**Message Broker (Cue)**) +* ``message flavor``: (**Messaging (Zaqar)**) +* ``pool``: (**Messaging (Zaqar)**) +* ``ptr record``: (**DNS (Designate)**) +* ``queue``: (**Messaging (Zaqar)**) +* ``recordset``: (**DNS (Designate)**) +* ``secret``: (**Key Manager (Barbican)**) +* ``secret container``: (**Key Manager (Barbican)**) +* ``secret order``: (**Key Manager (Barbican)**) +* ``stack``: (**Orchestration (Heat)**) +* ``tld``: (**DNS (Designate)**) +* ``zone``: (**DNS (Designate)**) +* ``zone blacklist``: (**DNS (Designate)**) +* ``zone transfer``: (**DNS (Designate)**) + + Actions ------- @@ -132,28 +168,32 @@ Those actions with an opposite action are noted in parens if applicable. is built in the order of ``container add object <container> <object>``, the positional arguments appear in the same order * ``create`` (``delete``) - create a new occurrence of the specified object -* ``delete`` (``create``) - delete a specific occurrence of the specified object +* ``delete`` (``create``) - delete specific occurrences of the specified objects * ``issue`` (``revoke``) - issue a token * ``list`` - display summary information about multiple objects -* ``lock`` (``unlock``) +* ``lock`` (``unlock``) - lock one or more servers so that non-admin user won't be able to execute actions * ``migrate`` - move a server to a different host; ``--live`` performs a live migration if possible -* ``pause`` (``unpause``) - stop a server and leave it in memory +* ``pause`` (``unpause``) - stop one or more servers and leave them in memory * ``reboot`` - forcibly reboot a server * ``rebuild`` - rebuild a server using (most of) the same arguments as in the original create * ``remove`` (``add``) - remove an object from a group of objects * ``rescue`` (``unrescue``) - reboot a server in a special rescue mode allowing access to the original disks * ``resize`` - change a server's flavor -* ``resume`` (``suspend``) - return a suspended server to running state +* ``resume`` (``suspend``) - return one or more suspended servers to running state * ``revoke`` (``issue``) - revoke a token * ``save`` - download an object locally * ``set`` (``unset``) - set a property on the object, formerly called metadata +* ``shelve`` (``unshelve``) - shelve one or more servers * ``show`` - display detailed information about the specific object -* ``suspend`` (``resume``) - stop a server and save to disk freeing memory -* ``unlock`` (``lock``) -* ``unpause`` (``pause``) - return a paused server to running state +* ``start`` (``stop``) - start one or more servers +* ``stop`` (``start``) - stop one or more servers +* ``suspend`` (``resume``) - stop one or more servers and save to disk freeing memory +* ``unlock`` (``lock``) - unlock one or more servers +* ``unpause`` (``pause``) - return one or more paused servers to running state * ``unrescue`` (``rescue``) - return a server to normal boot mode * ``unset`` (``set``) - remove an attribute of the object +* ``unshelve`` (``shelve``) - unshelve one or more servers Implementation diff --git a/doc/source/conf.py b/doc/source/conf.py index f4434ec..792ba40 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -38,6 +38,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'oslosphinx', 'ext.apidoc', + 'stevedore.sphinxext', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/developing.rst b/doc/source/developing.rst index c41fbf3..9f8e55c 100644 --- a/doc/source/developing.rst +++ b/doc/source/developing.rst @@ -98,6 +98,41 @@ create HTML docs, run the following: The resultant HTML will be the ``doc/build/html`` directory. +Release Notes +------------- + +The release notes for a patch should be included in the patch. See the +`Project Team Guide`_ for more information on using reno in OpenStack. + +.. _`Project Team Guide`: http://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes + +If any of the following applies to the patch, a release note is required: + +* The deployer needs to take an action when upgrading +* The plugin interface changes +* A new feature is implemented +* A command or option is removed +* Current behavior is changed +* A security bug is fixed + +Reno is used to generate release notes. Please read the docs for details. In summary, use + +.. code-block:: bash + + $ tox -e venv -- reno new <bug-,bp-,whatever> + +Then edit the sample file that was created and push it with your change. + +To see the results: + +.. code-block:: bash + + $ git commit # Commit the change because reno scans git log. + + $ tox -e releasenotes + +Then look at the generated release notes files in releasenotes/build/html in your favorite browser. + Testing new code ---------------- diff --git a/doc/source/history.rst b/doc/source/history.rst new file mode 100644 index 0000000..69ed4fe --- /dev/null +++ b/doc/source/history.rst @@ -0,0 +1 @@ +.. include:: ../../ChangeLog diff --git a/doc/source/index.rst b/doc/source/index.rst index c90b8e5..4992997 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,7 +3,7 @@ OpenStackClient =============== OpenStackClient (aka OSC) is a command-line client for OpenStack that -brings the command set for Compute, Identity, Image, Object Store and Volume +brings the command set for Compute, Identity, Image, Object Storage and Volume APIs together in a single shell with a uniform command structure. User Documentation @@ -16,11 +16,11 @@ User Documentation commands configuration plugins + plugin-commands authentication interactive humaninterfaceguide backwards-incompatible - releases man/openstack Getting Started @@ -30,6 +30,15 @@ Getting Started * Read the source `on OpenStack's Git server`_ * Install OpenStackClient from `PyPi`_ or a `tarball`_ +Release Notes +------------- + +.. toctree:: + :maxdepth: 1 + + releases + history + Developer Documentation ----------------------- @@ -37,6 +46,8 @@ Developer Documentation :maxdepth: 1 developing + command-options + command-wrappers Project Goals ------------- diff --git a/doc/source/plugin-commands.rst b/doc/source/plugin-commands.rst new file mode 100644 index 0000000..893c4c4 --- /dev/null +++ b/doc/source/plugin-commands.rst @@ -0,0 +1,32 @@ +================= + Plugin Commands +================= + +.. list-plugins:: openstack.cli.extension + +.. list-plugins:: openstack.key_manager.v1 + :detailed: + +.. list-plugins:: openstack.baremetal.v1 + :detailed: + +.. list-plugins:: openstack.congressclient.v1 + :detailed: + +.. list-plugins:: openstack.workflow_engine.v2 + :detailed: + +.. list-plugins:: openstack.data_processing.v1 + :detailed: + +.. list-plugins:: openstack.dns.v1 + :detailed: + +.. list-plugins:: openstack.management.v1 + :detailed: + +.. list-plugins:: openstack.messaging.v1 + :detailed: + +.. list-plugins:: openstack.orchestration.v1 + :detailed: diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst index 469742d..5f82cc6 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -24,20 +24,20 @@ plugin. ============================= ====================================== project notes ============================= ====================================== -python-barbicanclient patch in progress (https://review.openstack.org/#/c/198732/) +python-barbicanclient using OpenStackClient python-ceilometerclient using argparse python-congressclient using OpenStackClient python-cueclient using OpenStackClient -python-designateclient patch in progress (https://review.openstack.org/#/c/133676/) +python-designateclient using OpenStackClient python-heatclient patch in progress (https://review.openstack.org/#/c/195867/) -python-ironicclient patch in progress (https://review.openstack.org/#/c/171672/) +python-ironicclient Using OpenStackClient python-magnumclient using argparse python-manilaclient using argparse -python-mistralclient using cliff, but not OpenStackClient +python-mistralclient using cliff python-muranoclient using argparse -python-saharaclient using argparse +python-saharaclient using OpenStackClient python-troveclient using argparse -python-tuskarclient using OpenStackClient and their own shell +python-tuskarclient using OpenStackClient python-zaqarclient using OpenStackClient ============================= ====================================== diff --git a/doc/source/releases.rst b/doc/source/releases.rst index 582f584..853ef95 100644 --- a/doc/source/releases.rst +++ b/doc/source/releases.rst @@ -2,6 +2,95 @@ Release Notes ============= +As of release 2.0 the release notes can be found on the OpenStack `Release Notes site`_. + +.. _`Release Notes site`: http://docs.openstack.org/releasenotes/python-openstackclient + +1.9.0 (17 Nov 2015) +=================== + +* Several updates to `openstack server` + Blueprint `servers <https://blueprints.launchpad.net/python-openstackclient/+spec/cmd-with-multi-servers>`_ + + * `openstack server start` + * `openstack server stop` + * `openstack server pause` + * `openstack server unpause` + * `openstack server lock` + * `openstack server unlock` + +* Obfuscate passwords when used in debug mode + Bug `1501598 <https://bugs.launchpad.net/bugs/1501598>`_ + +* Clean up `identity provider show` + Bug `1478995 <https://bugs.launchpad.net/bugs/1478995>`_ + +* Add `description` to `identity provider set` + Bug `1515815 <https://bugs.launchpad.net/bugs/1515815>`_ + +* Add `compute service delete` + Bug `1503510 <https://bugs.launchpad.net/bugs/1503510>`_ + +* Log a warning when setting non-ascii object store properties + Bug `1503898 <https://bugs.launchpad.net/bugs/1503898>`_ + +* Add 'marker' and 'limit' to `openstack flavor list` + Bug `1505874 <https://bugs.launchpad.net/bugs/1505874>`_ + +* Remove `url` from `region create` and `region set` + Bug `1506841 <https://bugs.launchpad.net/bugs/1506841>`_ + +* `openstack image add project` fails with AttributeError for image v2 + Bug `1509054 <https://bugs.launchpad.net/bugs/1509054>`_ + +* Inconsistent output with `openstack usage show` + Bug `1512220 <https://bugs.launchpad.net/bugs/1512220>`_ + +* Validate --lines with `openstack console log show` + Bug `1512263 <https://bugs.launchpad.net/bugs/1512263>`_ + +* Validate --project does not exist with `openstack quota set` + Bug `1512638 <https://bugs.launchpad.net/bugs/1512638>`_ + +* Cannot list servers while --user specified for `openstack server list` + Bug `1513701 <https://bugs.launchpad.net/bugs/1513701>`_ + +* Cannot list volumes while --user specified for `openstack volume list` + Bug `1514145 <https://bugs.launchpad.net/bugs/1514145>`_ + +* Cannot find volume with --block-device-mapping with `openstack server create` + Bug `1514394 <https://bugs.launchpad.net/bugs/1514394>`_ + +* Fix documentation for `credential set` + Bug `1418837 <https://bugs.launchpad.net/bugs/1418837>`_ + +1.8.0 (18 Oct 2015) +=================== + +* `image create --volume` command (v1) will attempt to create two images + Bug `1497221 <https://bugs.launchpad.net/bugs/1497221>`_ + +* Add filtering by project/uesr for command `volume list` + Bug `1483976 <https://bugs.launchpad.net/bugs/1483976>`_ + +* Password used by plugin shows up in debug mode + Bug `1501598 <https://bugs.launchpad.net/bugs/1501598>`_ + +* Add support for `object store account` + Bug `1501943 <https://bugs.launchpad.net/bugs/1501943>`_ + +* Add support for setting properties on objects and containers + Bug `1501945 <https://bugs.launchpad.net/bugs/1501945>`_ + +* `role list` ignores `--inherited` option + Bug `1502822 <https://bugs.launchpad.net/bugs/1502822>`_ + +* `compute service list` does not return service ID number + Bug `1503430 <https://bugs.launchpad.net/bugs/1503430>`_ + +* Containers and objects with non-ascii characters fails + Bug `1503508 <https://bugs.launchpad.net/bugs/1503508>`_ + 1.7.1 (30 Sep 2015) =================== |