diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/command-errors.rst | 42 | ||||
| -rw-r--r-- | doc/source/command-objects/address-scope.rst | 120 | ||||
| -rw-r--r-- | doc/source/command-objects/availability-zone.rst | 3 | ||||
| -rw-r--r-- | doc/source/command-objects/credential.rst (renamed from doc/source/command-objects/credentials.rst) | 10 | ||||
| -rw-r--r-- | doc/source/command-objects/network.rst | 29 | ||||
| -rw-r--r-- | doc/source/command-objects/port.rst | 4 | ||||
| -rw-r--r-- | doc/source/command-objects/router.rst | 8 | ||||
| -rw-r--r-- | doc/source/command-objects/security-group-rule.rst | 45 | ||||
| -rw-r--r-- | doc/source/command-objects/security-group.rst | 4 | ||||
| -rw-r--r-- | doc/source/command-objects/snapshot.rst | 11 | ||||
| -rw-r--r-- | doc/source/command-objects/subnet-pool.rst | 15 | ||||
| -rw-r--r-- | doc/source/command-objects/subnet.rst | 8 | ||||
| -rw-r--r-- | doc/source/command-objects/volume-service.rst | 31 | ||||
| -rw-r--r-- | doc/source/command-options.rst | 33 | ||||
| -rw-r--r-- | doc/source/commands.rst | 4 | ||||
| -rw-r--r-- | doc/source/developing.rst | 4 | ||||
| -rw-r--r-- | doc/source/specs/ip-availability.rst | 61 |
17 files changed, 397 insertions, 35 deletions
diff --git a/doc/source/command-errors.rst b/doc/source/command-errors.rst index 35d7f9d0..a24dc317 100644 --- a/doc/source/command-errors.rst +++ b/doc/source/command-errors.rst @@ -99,8 +99,8 @@ to be handled by having the proper options in a set command available to allow recovery in the case where the primary resource has been created but the subsequent calls did not complete. -Example -~~~~~~~ +Example 1 +~~~~~~~~~ This example is taken from the ``volume snapshot set`` command where ``--property`` arguments are set using the volume manager's ``set_metadata()`` method, @@ -161,3 +161,41 @@ remaining arguments are set using the ``update()`` method. # without aborting prematurely if result > 0: raise SomeNonFatalException + +Example 2 +~~~~~~~~~ + +This example is taken from the ``network delete`` command which takes multiple +networks to delete. All networks will be delete in a loop, which makes multiple +``delete_network()`` calls. + +.. code-block:: python + + class DeleteNetwork(common.NetworkAndComputeCommand): + """Delete network(s)""" + + def update_parser_common(self, parser): + parser.add_argument( + 'network', + metavar="<network>", + nargs="+", + help=("Network(s) to delete (name or ID)") + ) + return parser + + def take_action(self, client, parsed_args): + ret = 0 + + for network in parsed_args.network: + try: + obj = client.find_network(network, ignore_missing=False) + client.delete_network(obj) + except Exception: + self.app.log.error("Failed to delete network with name " + "or ID %s." % network) + ret += 1 + + if ret > 0: + total = len(parsed_args.network) + msg = "Failed to delete %s of %s networks." % (ret, total) + raise exceptions.CommandError(msg) diff --git a/doc/source/command-objects/address-scope.rst b/doc/source/command-objects/address-scope.rst new file mode 100644 index 00000000..a2ab566c --- /dev/null +++ b/doc/source/command-objects/address-scope.rst @@ -0,0 +1,120 @@ +============= +address scope +============= + +An **address scope** is a scope of IPv4 or IPv6 addresses that belongs +to a given project and may be shared between projects. + +Network v2 + +address scope create +-------------------- + +Create new address scope + +.. program:: address scope create +.. code:: bash + + os address scope create + [--project <project> [--project-domain <project-domain>]] + [--ip-version <ip-version>] + [--share | --no-share] + <name> + +.. option:: --project <project> + + Owner's project (name or ID) + +.. option:: --project-domain <project-domain> + + Domain the project belongs to (name or ID). + This can be used in case collisions between project names exist. + +.. option:: --ip-version <ip-version> + + IP version (4 or 6, default is 4) + +.. option:: --share + + Share the address scope between projects + +.. option:: --no-share + + Do not share the address scope between projects (default) + +.. _address_scope_create-name: +.. describe:: <name> + + New address scope name + +address scope delete +-------------------- + +Delete an address scope + +.. program:: address scope delete +.. code:: bash + + os address scope delete + <address-scope> + +.. _address_scope_delete-address-scope: +.. describe:: <address-scope> + + Address scope to delete (name or ID) + +address scope list +------------------ + +List address scopes + +.. program:: address scope list +.. code:: bash + + os address scope list + +address scope set +----------------- + +Set address scope properties + +.. program:: address scope set +.. code:: bash + + os address scope set + [--name <name>] + [--share | --no-share] + <address-scope> + +.. option:: --name <name> + + Set address scope name + +.. option:: --share + + Share the address scope between projects + +.. option:: --no-share + + Do not share the address scope between projects + +.. _address_scope_set-address-scope: +.. describe:: <address-scope> + + Address scope to modify (name or ID) + +address scope show +------------------ + +Display address scope details + +.. program:: address scope show +.. code:: bash + + os address scope show + <address-scope> + +.. _address_scope_show-address-scope: +.. describe:: <address-scope> + + Address scope to display (name or ID) diff --git a/doc/source/command-objects/availability-zone.rst b/doc/source/command-objects/availability-zone.rst index 1f568438..149e1081 100644 --- a/doc/source/command-objects/availability-zone.rst +++ b/doc/source/command-objects/availability-zone.rst @@ -2,6 +2,9 @@ availability zone ================= +An **availability zone** is a logical partition of cloud block storage, +compute and network services. + Block Storage v2, Compute v2, Network v2 availability zone list diff --git a/doc/source/command-objects/credentials.rst b/doc/source/command-objects/credential.rst index 9f4aabe4..ed8a00db 100644 --- a/doc/source/command-objects/credentials.rst +++ b/doc/source/command-objects/credential.rst @@ -1,27 +1,27 @@ =========== -credentials +credential =========== Identity v3 -credentials create +credential create ------------------ .. ''[consider rolling the ec2 creds into this too]'' .. code:: bash - os credentials create + os credential create --x509 [<private-key-file>] [<certificate-file>] -credentials show +credential show ---------------- .. code:: bash - os credentials show + os credential show [--token] [--user] [--x509 [--root]] diff --git a/doc/source/command-objects/network.rst b/doc/source/command-objects/network.rst index 5d534c59..8668daee 100644 --- a/doc/source/command-objects/network.rst +++ b/doc/source/command-objects/network.rst @@ -2,6 +2,13 @@ network ======= +A **network** is an isolated Layer 2 networking segment. There are two types +of networks, project and provider networks. Project networks are fully isolated +and are not shared with other projects. Provider networks map to existing +physical networks in the data center and provide external network access for +servers and other resources. Only an OpenStack administrator can create +provider networks. Networks can be connected via routers. + Compute v2, Network v2 network create @@ -21,6 +28,7 @@ Create new network [--provider-network-type <provider-network-type>] [--provider-physical-network <provider-physical-network>] [--provider-segment <provider-segment>] + [--transparent-vlan | --no-transparent-vlan] <name> .. option:: --project <project> @@ -116,6 +124,18 @@ Create new network *Network version 2 only* +.. option:: --transparent-vlan + + Make the network VLAN transparent + + *Network version 2 only* + +.. option:: --no-transparent-vlan + + Do not make the network VLAN transparent + + *Network version 2 only* + .. _network_create-name: .. describe:: <name> @@ -175,6 +195,7 @@ Set network properties [--provider-network-type <provider-network-type>] [--provider-physical-network <provider-physical-network>] [--provider-segment <provider-segment>] + [--transparent-vlan | --no-transparent-vlan] <network> .. option:: --name <name> @@ -227,6 +248,14 @@ Set network properties VLAN ID for VLAN networks or Tunnel ID for GRE/VXLAN networks +.. option:: --transparent-vlan + + Make the network VLAN transparent + +.. option:: --no-transparent-vlan + + Do not make the network VLAN transparent + .. _network_set-network: .. describe:: <network> diff --git a/doc/source/command-objects/port.rst b/doc/source/command-objects/port.rst index 36e83082..e4cf2cd2 100644 --- a/doc/source/command-objects/port.rst +++ b/doc/source/command-objects/port.rst @@ -2,6 +2,10 @@ port ==== +A **port** is a connection point for attaching a single device, such as the +NIC of a server, to a network. The port also describes the associated network +configuration, such as the MAC and IP addresses to be used on that port. + Network v2 port create diff --git a/doc/source/command-objects/router.rst b/doc/source/command-objects/router.rst index 1503516e..9ca7661e 100644 --- a/doc/source/command-objects/router.rst +++ b/doc/source/command-objects/router.rst @@ -2,6 +2,10 @@ router ====== +A **router** is a logical component that forwards data packets between +networks. It also provides Layer 3 and NAT forwarding to provide external +network access for servers on project networks. + Network v2 router add port @@ -182,7 +186,7 @@ Set router properties [--name <name>] [--enable | --disable] [--distributed | --centralized] - [--route destination=<subnet>,gateway=<ip-address> | --clear-routes] + [--route destination=<subnet>,gateway=<ip-address> | --no-route] <router> .. option:: --name <name> @@ -212,7 +216,7 @@ Set router properties gateway: nexthop IP address (repeat option to set multiple routes) -.. option:: --clear-routes +.. option:: --no-route Clear routes associated with the router diff --git a/doc/source/command-objects/security-group-rule.rst b/doc/source/command-objects/security-group-rule.rst index 8218c81a..97cce35c 100644 --- a/doc/source/command-objects/security-group-rule.rst +++ b/doc/source/command-objects/security-group-rule.rst @@ -2,6 +2,9 @@ security group rule =================== +A **security group rule** specifies the network access rules for servers +and other resources on the network. + Compute v2, Network v2 security group rule create @@ -13,18 +16,14 @@ Create a new security group rule .. code:: bash os security group rule create - [--proto <proto>] [--src-ip <ip-address> | --src-group <group>] - [--dst-port <port-range>] + [--dst-port <port-range> | [--icmp-type <icmp-type> [--icmp-code <icmp-code>]]] + [--protocol <protocol>] [--ingress | --egress] [--ethertype <ethertype>] [--project <project> [--project-domain <project-domain>]] <group> -.. option:: --proto <proto> - - IP protocol (icmp, tcp, udp; default: tcp) - .. option:: --src-ip <ip-address> Source IP address block @@ -36,8 +35,35 @@ Create a new security group rule .. option:: --dst-port <port-range> - Destination port, may be a single port or port range: 137:139 - (only required for IP protocols tcp and udp) + Destination port, may be a single port or a starting and + ending port range: 137:139. Required for IP protocols TCP + and UDP. Ignored for ICMP IP protocols. + +.. option:: --icmp-type <icmp-type> + + ICMP type for ICMP IP protocols + + *Network version 2 only* + +.. option:: --icmp-code <icmp-code> + + ICMP code for ICMP IP protocols + + *Network version 2 only* + +.. option:: --protocol <protocol> + + IP protocol (icmp, tcp, udp; default: tcp) + + *Compute version 2* + + IP protocol (ah, dccp, egp, esp, gre, icmp, igmp, + ipv6-encap, ipv6-frag, ipv6-icmp, ipv6-nonxt, + ipv6-opts, ipv6-route, ospf, pgm, rsvp, sctp, tcp, + udp, udplite, vrrp and integer representations [0-255]; + default: tcp) + + *Network version 2* .. option:: --ingress @@ -53,7 +79,8 @@ Create a new security group rule .. option:: --ethertype <ethertype> - Ethertype of network traffic (IPv4, IPv6; default: IPv4) + Ethertype of network traffic + (IPv4, IPv6; default: based on IP protocol) *Network version 2 only* diff --git a/doc/source/command-objects/security-group.rst b/doc/source/command-objects/security-group.rst index 2c6e7a8a..3af11b5a 100644 --- a/doc/source/command-objects/security-group.rst +++ b/doc/source/command-objects/security-group.rst @@ -2,6 +2,10 @@ security group ============== +A **security group** acts as a virtual firewall for servers and other +resources on a network. It is a container for security group rules +which specify the network access rules. + Compute v2, Network v2 security group create diff --git a/doc/source/command-objects/snapshot.rst b/doc/source/command-objects/snapshot.rst index b4838684..90330118 100644 --- a/doc/source/command-objects/snapshot.rst +++ b/doc/source/command-objects/snapshot.rst @@ -2,7 +2,7 @@ snapshot ======== -Block Storage v1 +Block Storage v1, v2 snapshot create --------------- @@ -82,6 +82,7 @@ Set snapshot properties [--name <name>] [--description <description>] [--property <key=value> [...] ] + [--state <state>] <snapshot> .. _snapshot_restore-snapshot: @@ -97,6 +98,14 @@ Set snapshot properties Property to add or modify for this snapshot (repeat option to set multiple properties) +.. option:: --state <state> + + New snapshot state. + Valid values are "available", "error", "creating", + "deleting", and "error_deleting". + + *Volume version 2 only* + .. describe:: <snapshot> Snapshot to modify (name or ID) diff --git a/doc/source/command-objects/subnet-pool.rst b/doc/source/command-objects/subnet-pool.rst index 867153ef..8abf25a6 100644 --- a/doc/source/command-objects/subnet-pool.rst +++ b/doc/source/command-objects/subnet-pool.rst @@ -2,6 +2,9 @@ subnet pool =========== +A **subnet pool** contains a collection of prefixes in CIDR notation +that are available for IP address allocation. + Network v2 subnet pool create @@ -13,7 +16,6 @@ Create subnet pool .. code:: bash os subnet pool create - [--pool-prefix <pool-prefix> [...]] [--default-prefix-length <default-prefix-length>] [--min-prefix-length <min-prefix-length>] [--max-prefix-length <max-prefix-length>] @@ -21,13 +23,9 @@ Create subnet pool [--address-scope <address-scope>] [--default | --no-default] [--share | --no-share] + --pool-prefix <pool-prefix> [...] <name> -.. option:: --pool-prefix <pool-prefix> - - Set subnet pool prefixes (in CIDR notation) - (repeat option to set multiple prefixes) - .. option:: --default-prefix-length <default-prefix-length> Set subnet pool default prefix length @@ -70,6 +68,11 @@ Create subnet pool Set this subnet pool as not shared +.. describe:: --pool-prefix <pool-prefix> + + Set subnet pool prefixes (in CIDR notation) + (repeat option to set multiple prefixes) + .. _subnet_pool_create-name: .. describe:: <name> diff --git a/doc/source/command-objects/subnet.rst b/doc/source/command-objects/subnet.rst index 35134f46..ff6354e6 100644 --- a/doc/source/command-objects/subnet.rst +++ b/doc/source/command-objects/subnet.rst @@ -2,6 +2,10 @@ subnet ====== +A **subnet** is a block of IP addresses and associated configuration state. +Subnets are used to allocate IP addresses when new ports are created on a +network. + Network v2 subnet create @@ -143,6 +147,10 @@ List subnets List additional fields in output +.. option:: --ip-version {4, 6} + + List only subnets of given IP version in output + subnet set ---------- diff --git a/doc/source/command-objects/volume-service.rst b/doc/source/command-objects/volume-service.rst new file mode 100644 index 00000000..aa9fa6d2 --- /dev/null +++ b/doc/source/command-objects/volume-service.rst @@ -0,0 +1,31 @@ +============== +volume service +============== + +Volume v1, v2 + +volume service list +------------------- + +List volume service + +.. program:: volume service list +.. code:: bash + + os volume service list + [--host <host>] + [--service <service>] + [--long] + +.. _volume-service-list: +.. option:: --host <host> + + List services on specified host (name only) + +.. option:: --service <service> + + List only specified service (name only) + +.. option:: --long + + List additional fields in output diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst index d47a56dc..5cb84684 100644 --- a/doc/source/command-options.rst +++ b/doc/source/command-options.rst @@ -112,8 +112,26 @@ Some options can be repeated to build a collection of values for a property. Adding a value to the collection must be provided via the ``set`` action. Removing a value from the collection must be provided via an ``unset`` action. As a convenience, removing all values from the collection may be provided via a -``--no`` option on the ``set`` and ``unset`` actions. The ``--no`` option must -be part of a mutually exclusive group with the related property option. +``--no`` option on the ``set`` and ``unset`` actions. If both ``--no`` option +and option are specified, the values specified on the command would overwrite +the collection property instead of appending on the ``set`` action. The +``--no`` option must be part of a mutually exclusive group with the related +property option on the ``unset`` action, overwrite case don't exist in +``unset`` action. + +An example behavior for ``set`` action: + +Append: + +.. code-block:: bash + + object set --example-property xxx + +Overwrite: + +.. code-block:: bash + + object set --no-example-property --example-property xxx The example below assumes a property that contains a list of unique values. However, this example can also be applied to other collections using the @@ -129,8 +147,7 @@ An example parser declaration for `set` action: .. code-block:: python - example_property_group = parser.add_mutually_exclusive_group() - example_property_group.add_argument( + parser.add_argument( '--example-property', metavar='<example-property>', dest='example_property', @@ -138,7 +155,7 @@ An example parser declaration for `set` action: help=_('Example property for this <resource> ' '(repeat option to set multiple properties)'), ) - example_property_group.add_argument( + parser.add_argument( '--no-example-property', dest='no_example_property', action='store_true', @@ -149,10 +166,12 @@ An example handler in `take_action()` for `set` action: .. code-block:: python - if parsed_args.example_property: + if parsed_args.example_property and parsed_args.no_example_property: + kwargs['example_property'] = parsed_args.example_property + elif parsed_args.example_property: kwargs['example_property'] = \ resource_example_property + parsed_args.example_property - if parsed_args.no_example_property: + elif parsed_args.no_example_property: kwargs['example_property'] = [] An example parser declaration for `unset` action: diff --git a/doc/source/commands.rst b/doc/source/commands.rst index e9de65dc..12542d1c 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -70,6 +70,7 @@ the API resources will be merged, as in the ``quota`` object that has options referring to both Compute and Volume quotas. * ``access token``: (**Identity**) long-lived OAuth-based token +* ``address scope``: (**Network**) a scope of IPv4 or IPv6 addresses * ``aggregate``: (**Compute**) a grouping of compute hosts * ``availability zone``: (**Compute**, **Network**, **Volume**) a logical partition of hosts or block storage or network services * ``backup``: (**Volume**) a volume copy @@ -82,7 +83,7 @@ referring to both Compute and Volume quotas. * ``console url``: (**Compute**) server remote console URL * ``consumer``: (**Identity**) OAuth-based delegatee * ``container``: (**Object Storage**) a grouping of objects -* ``credentials``: (**Identity**) specific to identity providers +* ``credential``: (**Identity**) specific to identity providers * ``domain``: (**Identity**) a grouping of projects * ``ec2 credentials``: (**Identity**) AWS EC2-compatible credentials * ``endpoint``: (**Identity**) the base URL used to contact a specific service @@ -133,6 +134,7 @@ referring to both Compute and Volume quotas. * ``volume``: (**Volume**) block volumes * ``volume qos``: (**Volume**) quality-of-service (QoS) specification for volumes * ``volume type``: (**Volume**) deployment-specific types of volumes available +* ``volume service``: (**Volume**) services to manage block storage operations Plugin Objects diff --git a/doc/source/developing.rst b/doc/source/developing.rst index 9f8e55ca..2ddaeb2c 100644 --- a/doc/source/developing.rst +++ b/doc/source/developing.rst @@ -8,9 +8,9 @@ Communication Meetings ========= The OpenStackClient team meets regularly on every Thursday. For details -please refer to the `wiki`_. +please refer to the `OpenStack IRC meetings`_ page. -.. _`wiki`: https://wiki.openstack.org/wiki/Meetings/OpenStackClient +.. _`OpenStack IRC meetings`: http://eavesdrop.openstack.org/#OpenStackClient_Team_Meeting Testing ------- diff --git a/doc/source/specs/ip-availability.rst b/doc/source/specs/ip-availability.rst new file mode 100644 index 00000000..cf0c71ff --- /dev/null +++ b/doc/source/specs/ip-availability.rst @@ -0,0 +1,61 @@ +=============== +ip availability +=============== + +Network v2 + +ip availability list +-------------------- + +List IP availability for network + +This command retrieves information about IP availability. +Useful for admins who need a quick way to check the +IP availability for all associated networks. +List specifically returns total IP capacity and the +number of allocated IP addresses from that pool. + +.. program:: ip availability list +.. code:: bash + + os ip availability list + [--ip-version {4,6}] + [--project <project>] + +.. option:: --ip-version {4,6} + + List IP availability for specific version + (Default is 4) + +.. option:: --project <project> + + List IP availability for specific project + (name or ID) + +ip availability show +-------------------- + +Show network IP availability details + +This command retrieves information about IP availability. +Useful for admins who need a quick way to +check the IP availability and details for a +specific network. + +This command will return information about +IP availability for the network as a whole, and +return availability information for each individual +subnet within the network as well. + + +.. program:: ip availability show +.. code:: bash + + os ip availability show + <network> + +.. _ip_availability_show-network +.. describe:: <network> + + Show network IP availability for specific + network (name or ID) |