From 21d93118f0bab4c705ce17c3ae0ee291a1d6c7a8 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Fri, 12 Jun 2015 15:24:12 +0200 Subject: [PATCH] Avoid really overlooooooooong lines in RST We aim to have no lines longer than 79 characters, enable the line checking niceness check but set it to 100 as current maximum. Convert files that fail this line length. Convert one table to a definition list, convert two tables to use list-table directive. Change-Id: I8d0a95cc1c8e72965b3e0e69445e7b2bc6d77f0f --- .../source/identity_management.rst | 6 +- doc/admin-guide-cloud-rst/source/index.rst | 3 +- doc/common-rst/cli_manage_images.rst | 97 +++++++++------ doc/common-rst/dashboard_customizing.rst | 6 +- .../source/intro_basic_networking.rst | 57 +++++---- .../source/intro_os_networking_service.rst | 11 +- .../source/cli_set_compute_quotas.rst | 14 ++- .../source/dashboard_manage_volumes.rst | 3 +- .../source/cli_create_and_manage_stacks.rst | 5 +- .../source/cli_manage_ip_addresses.rst | 8 +- ...onfigure_access_security_for_instances.rst | 5 +- .../cli_nova_launch_instance_from_volume.rst | 40 ++++-- .../cli_swift_large_object_creation.rst | 116 ++++++++++-------- .../sdk_schedule_objects_for_deletion.rst | 3 +- tox.ini | 8 +- 15 files changed, 231 insertions(+), 151 deletions(-) diff --git a/doc/admin-guide-cloud-rst/source/identity_management.rst b/doc/admin-guide-cloud-rst/source/identity_management.rst index 1db04801c9..4abec1c457 100644 --- a/doc/admin-guide-cloud-rst/source/identity_management.rst +++ b/doc/admin-guide-cloud-rst/source/identity_management.rst @@ -122,7 +122,8 @@ in a tenant. To restrict users from performing operations in, for example, the Compute service, you need to create a role in the Identity service and -then modify the :file:`/etc/nova/policy.json` file so that this role is required for Compute operations. +then modify the :file:`/etc/nova/policy.json` file so that this role +is required for Compute operations. For example, the following line in the :file:`/etc/nova/policy.json` file specifies that there are no restrictions on which users can create volumes: @@ -384,7 +385,8 @@ To start the services for Identity, run the following command: This command starts two wsgi.Server instances configured by the :file:`keystone.conf` file as described previously. One of these wsgi -servers is :code:`admin` (the administration API) and the other is :code:`main` (the primary/public API interface). Both run in a single +servers is :code:`admin` (the administration API) and the other is +:code:`main` (the primary/public API interface). Both run in a single process. Example usage diff --git a/doc/admin-guide-cloud-rst/source/index.rst b/doc/admin-guide-cloud-rst/source/index.rst index 17260f41f7..37fd59f554 100644 --- a/doc/admin-guide-cloud-rst/source/index.rst +++ b/doc/admin-guide-cloud-rst/source/index.rst @@ -5,7 +5,8 @@ OpenStack Cloud Administrator Guide Abstract ~~~~~~~~ -OpenStack offers open source software for cloud administrators to manage and troubleshoot an OpenStack cloud. +OpenStack offers open source software for cloud administrators to +manage and troubleshoot an OpenStack cloud. This guide documents OpenStack Kilo, OpenStack Juno, and OpenStack Icehouse releases. diff --git a/doc/common-rst/cli_manage_images.rst b/doc/common-rst/cli_manage_images.rst index 61922e8f08..d9a6407654 100644 --- a/doc/common-rst/cli_manage_images.rst +++ b/doc/common-rst/cli_manage_images.rst @@ -125,45 +125,71 @@ To update an image by name or ID, use ``glance image-update``: $ glance image-update imageName -The following table lists the optional arguments that you can use with +The following list explains the optional arguments that you can use with the ``create`` and ``update`` commands to modify image properties. For more information, refer to Image service chapter in the `OpenStack Command-Line Interface Reference `__. -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--name NAME`` | The name of the image. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--disk-format DISK_FORMAT`` | The disk format of the image. Acceptable formats are ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--container-format CONTAINER_FORMAT`` | The container format of the image. Acceptable formats are ami, ari, aki, bare, and ovf. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--owner TENANT_ID`` | The tenant who should own the image. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--size SIZE`` | The size of image data, in bytes. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--min-disk DISK_GB`` | The minimum size of the disk needed to boot the image, in gigabytes. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--min-ram DISK_RAM`` | The minimum amount of RAM needed to boot the image, in megabytes. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--location IMAGE_URL`` | The URL where the data for this image resides. For example, if the image data is stored in swift, you could specify ``swift://account:key@example.com/container/obj``. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--file FILE`` | Local file that contains the disk image to be uploaded during the update. Alternatively, you can pass images to the client through stdin. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--checksum CHECKSUM`` | Hash of image data to use for verification. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--copy-from IMAGE_URL`` | Similar to ``--location`` in usage, but indicates that the image server should immediately copy the data and store it in its configured image store. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--is-public [True|False]`` | Makes an image accessible for all the tenants (admin-only by default). | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--is-protected [True|False]`` | Prevents an image from being deleted. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--property KEY=VALUE`` | Arbitrary property to associate with image. This option can be used multiple times. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--purge-props`` | Deletes all image properties that are not explicitly set in the update request. Otherwise, those properties not referenced are preserved. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--human-readable`` | Prints the image size in a human-friendly format. | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``--name NAME`` + The name of the image. + +``--disk-format DISK_FORMAT`` + The disk format of the image. Acceptable formats are ami, ari, aki, + vhd, vmdk, raw, qcow2, vdi, and iso. + +``--container-format CONTAINER_FORMAT`` + The container format of the image. Acceptable formats are ami, ari, + aki, bare, and ovf. + +``--owner TENANT_ID --size SIZE`` + The tenant who should own the image. The size of image data, in + bytes. + +``--min-disk DISK_GB`` + The minimum size of the disk needed to boot the image, in + gigabytes. + +``--min-ram DISK_RAM`` + The minimum amount of RAM needed to boot the image, in megabytes. + +``--location IMAGE_URL`` + The URL where the data for this image resides. For example, if the + image data is stored in swift, you could specify + ``swift://account:key@example.com/container/obj``. + +``--file FILE`` + Local file that contains the disk image to be uploaded during the + update. Alternatively, you can pass images to the client through + stdin. + +``--checksum CHECKSUM`` + Hash of image data to use for verification. + +``--copy-from IMAGE_URL`` + Similar to ``--location`` in usage, but indicates that the image + server should immediately copy the data and store it in its + configured image store. + +``--is-public [True|False]`` + Makes an image accessible for all the tenants (admin-only by + default). + +``--is-protected [True|False]`` + Prevents an image from being deleted. + +``--property KEY=VALUE`` + Arbitrary property to associate with image. This option can be used + multiple times. + +``--purge-props`` + Deletes all image properties that are not explicitly set in the + update request. Otherwise, those properties not referenced are + preserved. + +``--human-readable`` + Prints the image size in a human-friendly format. + The following example shows the command that you would use to upload a CentOS 6.3 image in qcow2 format and configure it for public access: @@ -193,7 +219,8 @@ performance, libvirt defaults to using virtio for both disk and VIF possible to run operating systems that lack virtio drivers, for example, BSD, Solaris, and older versions of Linux and Windows. -If you specify a disk or CD-ROM bus model that is not supported, see the Disk_and_CD-ROM_bus_model_values_table_. +If you specify a disk or CD-ROM bus model that is not supported, see +the Disk_and_CD-ROM_bus_model_values_table_. If you specify a VIF model that is not supported, the instance fails to launch. See the VIF_model_values_table_. diff --git a/doc/common-rst/dashboard_customizing.rst b/doc/common-rst/dashboard_customizing.rst index 70675127f2..c4ad809c1d 100644 --- a/doc/common-rst/dashboard_customizing.rst +++ b/doc/common-rst/dashboard_customizing.rst @@ -34,9 +34,11 @@ Logo and site colors - Login screen: 365 x 50 - Logged in banner: 216 x 35 -#. Upload your new images to :file:`/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/img/`. +#. Upload your new images to + :file:`/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/img/`. -#. Create a CSS style sheet in :file:`/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/css/`. +#. Create a CSS style sheet in + :file:`/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/css/`. #. Change the colors and image file names as appropriate, though the relative directory paths should be the same. The following example file diff --git a/doc/networking-guide/source/intro_basic_networking.rst b/doc/networking-guide/source/intro_basic_networking.rst index ddb8ffb7c6..25a819b41d 100644 --- a/doc/networking-guide/source/intro_basic_networking.rst +++ b/doc/networking-guide/source/intro_basic_networking.rst @@ -145,15 +145,17 @@ There are two syntaxes for expressing a netmask: * dotted quad * classless inter-domain routing (CIDR) -Consider an IP address of 192.168.1.5, where the first 24 bits of the address -are the network number. In dotted quad notation, the netmask would be written as -``255.255.255.0``. CIDR notation includes both the IP address and netmask, -and this example would be written as ``192.168.1.5/24``. +Consider an IP address of 192.168.1.5, where the first 24 bits of the +address are the network number. In dotted quad notation, the netmask +would be written as ``255.255.255.0``. CIDR notation includes both the +IP address and netmask, and this example would be written as +``192.168.1.5/24``. -Sometimes we want to refer to a subnet, but not any particular IP address on -the subnet. A common convention is to set the host identifier to all zeros to make -reference to a subnet. For example, if a host's IP address is ``10.10.53.24/16``, then -we would say the subnet is ``10.10.0.0/16``. +Sometimes we want to refer to a subnet, but not any particular IP +address on the subnet. A common convention is to set the host +identifier to all zeros to make reference to a subnet. For example, if +a host's IP address is ``10.10.53.24/16``, then we would say the +subnet is ``10.10.0.0/16``. To understand how ARP translates IP addresses to MAC addresses, consider the following example. Assume host *A* has an IP address of ``192.168.1.5/24`` and a @@ -161,15 +163,18 @@ MAC address of ``fc:99:47:49:d4:a0``, and wants to send a packet to host *B* with an IP address of ``192.168.1.7``. Note that the network number is the same for both hosts, so host *A* is able to send frames directly to host *B*. -The first time host *A* attempts to communicate with host *B*, the destination MAC -address is not known. Host *A* makes an ARP request to the local network. -The request is a broadcast with a message like this: +The first time host *A* attempts to communicate with host *B*, the +destination MAC address is not known. Host *A* makes an ARP request to +the local network. The request is a broadcast with a message like +this: -*To: everybody (ff:ff:ff:ff:ff:ff). I am looking for the computer who has IP address 192.168.1.7. Signed: MAC address fc:99:47:49:d4:a0*. +*To: everybody (ff:ff:ff:ff:ff:ff). I am looking for the computer who +has IP address 192.168.1.7. Signed: MAC address fc:99:47:49:d4:a0*. Host *B* responds with a response like this: -*To: fc:99:47:49:d4:a0. I have IP address 192.168.1.7. Signed: MAC address 54:78:1a:86:00:a5.* +*To: fc:99:47:49:d4:a0. I have IP address 192.168.1.7. Signed: MAC +address 54:78:1a:86:00:a5.* Host *A* then sends Ethernet frames to host *B*. @@ -198,9 +203,10 @@ you can view the contents of the ARP cache by using the *arp* command:: DHCP ~~~~ -Hosts connected to a network use the Dynamic Host Configuration Protocol (:term:`DHCP`) -to dynamically obtain IP addresses. A DHCP server hands out the IP addresses to -network hosts, which are the DHCP clients. +Hosts connected to a network use the Dynamic Host Configuration +Protocol (:term:`DHCP`) to dynamically obtain IP addresses. A DHCP +server hands out the IP addresses to network hosts, which are the DHCP +clients. DHCP clients locate the DHCP server by sending a UDP_ packet from port 68 to address ``255.255.255.255`` on port 67. Address ``255.255.255.255`` is the local @@ -211,15 +217,20 @@ as the client, or the server will not receive the broadcast. The DHCP server responds by sending a UDP packet from port 67 to port 68 on the client. The exchange looks like this: -1. The client sends a discover ("I’m a client at MAC address ``08:00:27:b9:88:74``, I need an IP address") -2. The server sends an offer ("OK ``08:00:27:b9:88:74``, I’m offering IP address ``10.10.0.112``") -3. The client sends a request ("Server ``10.10.0.131``, I would like to have IP ``10.10.0.112``") -4. The server sends an acknowledgement ("OK ``08:00:27:b9:88:74``, IP ``10.10.0.112`` is yours") +1. The client sends a discover ("I’m a client at MAC address + ``08:00:27:b9:88:74``, I need an IP address") +2. The server sends an offer ("OK ``08:00:27:b9:88:74``, I’m offering + IP address ``10.10.0.112``") +3. The client sends a request ("Server ``10.10.0.131``, I would like + to have IP ``10.10.0.112``") +4. The server sends an acknowledgement ("OK ``08:00:27:b9:88:74``, IP + ``10.10.0.112`` is yours") -OpenStack uses a third-party program called dnsmasq_ to implement the DHCP server. -Dnsmasq writes to the syslog (normally found at /var/log/syslog), where you can observe the DHCP -request and replies:: +OpenStack uses a third-party program called dnsmasq_ to implement the +DHCP server. +Dnsmasq writes to the syslog (normally found at /var/log/syslog), +where you can observe the DHCP request and replies:: Apr 23 15:53:46 c100-1 dhcpd: DHCPDISCOVER from 08:00:27:b9:88:74 via eth2 Apr 23 15:53:46 c100-1 dhcpd: DHCPOFFER on 10.10.0.112 to 08:00:27:b9:88:74 via eth2 diff --git a/doc/networking-guide/source/intro_os_networking_service.rst b/doc/networking-guide/source/intro_os_networking_service.rst index 82c0ac654a..d7923044b3 100644 --- a/doc/networking-guide/source/intro_os_networking_service.rst +++ b/doc/networking-guide/source/intro_os_networking_service.rst @@ -68,14 +68,19 @@ Routing services VPNaaS ------ -The Virtual Private Network as a Service (VPNaaS) is a neutron extension that introduces the VPN feature set. +The Virtual Private Network as a Service (VPNaaS) is a neutron +extension that introduces the VPN feature set. LbaaS ----- -The Load-Balancer-as-a-Service (LBaaS) API provisions and configures load balancers. The reference implementation is based on the HAProxy software load balancer. +The Load-Balancer-as-a-Service (LBaaS) API provisions and configures +load balancers. The reference implementation is based on the HAProxy +software load balancer. FwaaS ----- -The Firewall-as-a-Service (FWaaS) API is an experimental API that enables early adopters and vendors to test their networking implementations. +The Firewall-as-a-Service (FWaaS) API is an experimental API that +enables early adopters and vendors to test their networking +implementations. diff --git a/doc/user-guide-admin/source/cli_set_compute_quotas.rst b/doc/user-guide-admin/source/cli_set_compute_quotas.rst index b711068fa6..44dc85691c 100644 --- a/doc/user-guide-admin/source/cli_set_compute_quotas.rst +++ b/doc/user-guide-admin/source/cli_set_compute_quotas.rst @@ -9,12 +9,14 @@ tenant user, as well as update the quota defaults for a new tenant. **Compute quota descriptions** -=============================== =================================================================== +=============================== ======================================================== Quota name Description -=============================== =================================================================== - cores Number of instance cores (VCPUs) allowed per tenant. - fixed-ips Number of fixed IP addresses allowed per tenant. This number must - be equal to or greater than the number of allowed instances. +=============================== ======================================================== + cores Number of instance cores (VCPUs) + allowed per tenant. + fixed-ips Number of fixed IP addresses allowed per tenant. + This number must be equal to or + greater than the number of allowed instances. floating-ips Number of floating IP addresses allowed per tenant. injected-file-content-bytes Number of content bytes allowed per injected file. injected-file-path-bytes Length of injected file path. @@ -25,7 +27,7 @@ tenant user, as well as update the quota defaults for a new tenant. ram Megabytes of instance ram allowed per tenant. security-groups Number of security groups per tenant. security-group-rules Number of rules per security group. -=============================== =================================================================== +=============================== ======================================================== View and update Compute quotas for a tenant (project) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/user-guide-admin/source/dashboard_manage_volumes.rst b/doc/user-guide-admin/source/dashboard_manage_volumes.rst index 7397e91589..6c8f20e506 100644 --- a/doc/user-guide-admin/source/dashboard_manage_volumes.rst +++ b/doc/user-guide-admin/source/dashboard_manage_volumes.rst @@ -39,7 +39,8 @@ Create an encrypted volume type #. Click :guilabel:`Create Encryption` in the Actions column of the newly created volume type. -#. Configure the encrypted volume by setting the parameters below from available options (see table): +#. Configure the encrypted volume by setting the parameters below from + available options (see table): Provider Specifies the class responsible for configuring the encryption. diff --git a/doc/user-guide/source/cli_create_and_manage_stacks.rst b/doc/user-guide/source/cli_create_and_manage_stacks.rst index 90f486a11a..ad9a6e737c 100644 --- a/doc/user-guide/source/cli_create_and_manage_stacks.rst +++ b/doc/user-guide/source/cli_create_and_manage_stacks.rst @@ -122,8 +122,9 @@ Update a stack To update an existing stack from a modified template file, run a command like the following command:: - $ heat stack-update mystack --template-file /path/to/heat/templates/WordPress_Single_Instance_v2.template - --parameters "InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17" + $ heat stack-update mystack --template-file \ + /path/to/heat/templates/WordPress_Single_Instance_v2.template \ + --parameters "InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17" +--------------------------------------+---------------+-----------------+----------------------+ | id | stack_name | stack_status | creation_time | +--------------------------------------+---------------+-----------------+----------------------+ diff --git a/doc/user-guide/source/cli_manage_ip_addresses.rst b/doc/user-guide/source/cli_manage_ip_addresses.rst index 15aa001528..fa9c257248 100644 --- a/doc/user-guide/source/cli_manage_ip_addresses.rst +++ b/doc/user-guide/source/cli_manage_ip_addresses.rst @@ -54,9 +54,11 @@ run:: | 172.24.4.226 | None | None | public | +--------------+--------------------------------------+----------+--------+ -For each floating IP address that is allocated to the current project, the -command outputs the floating IP address, the ID for the instance to which -the floating IP address is assigned, the associated fixed IP address, and the pool from which the floating IP address was allocated. +For each floating IP address that is allocated to the current project, +the command outputs the floating IP address, the ID for the instance +to which the floating IP address is assigned, the associated fixed IP +address, and the pool from which the floating IP address was +allocated. Associate floating IP addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/user-guide/source/cli_nova_configure_access_security_for_instances.rst b/doc/user-guide/source/cli_nova_configure_access_security_for_instances.rst index c155d6cb3a..a341ec43e3 100644 --- a/doc/user-guide/source/cli_nova_configure_access_security_for_instances.rst +++ b/doc/user-guide/source/cli_nova_configure_access_security_for_instances.rst @@ -118,8 +118,9 @@ Create and manage security groups Create and manage security group rules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Modify security group rules with the :command:`nova secgroup-*-rule` commands. -Before you begin, source the OpenStack RC file. For details, see :doc:`../common/cli_set_environment_variables_using_openstack_rc`. +Modify security group rules with the :command:`nova secgroup-*-rule` +commands. Before you begin, source the OpenStack RC file. For details, +see :doc:`../common/cli_set_environment_variables_using_openstack_rc`. #. To list the rules for a security group, run the following command:: diff --git a/doc/user-guide/source/cli_nova_launch_instance_from_volume.rst b/doc/user-guide/source/cli_nova_launch_instance_from_volume.rst index 8714685301..0bca4d3bf0 100644 --- a/doc/user-guide/source/cli_nova_launch_instance_from_volume.rst +++ b/doc/user-guide/source/cli_nova_launch_instance_from_volume.rst @@ -7,19 +7,33 @@ You can boot instances from a volume instead of an image. To complete these tasks, use these parameters on the nova :command:`boot` command: -+------------------------------------------------------------------------+-----------------------+-------------------------------------------------------------------+ -| Task | nova boot parameter | Information | -+========================================================================+=======================+===================================================================+ -| Boot an instance from an image and attach a non-bootable volume. | ``--block-device`` | :ref:`Boot_instance_from_image_and_attach_non-bootable_volume` | -+------------------------------------------------------------------------+-----------------------+-------------------------------------------------------------------+ -| Create a volume from an image and boot an instance from that volume. | ``--block-device`` | :ref:`Create_volume_from_image_and_boot_instance` | -+------------------------------------------------------------------------+-----------------------+-------------------------------------------------------------------+ -| Boot from an existing source image, volume, or snapshot. | ``--block-device`` | :ref:`Create_volume_from_image_and_boot_instance` | -+------------------------------------------------------------------------+-----------------------+-------------------------------------------------------------------+ -| Attach a swap disk to an instance. | ``--swap`` | :ref:`Attach_swap_or_ephemeral_disk_to_an_instance` | -+------------------------------------------------------------------------+-----------------------+-------------------------------------------------------------------+ -| Attach an ephemeral disk to an instance. | ``--ephemeral`` | :ref:`Attach_swap_or_ephemeral_disk_to_an_instance` | -+------------------------------------------------------------------------+-----------------------+-------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 30 10 30 + + * - Task + - nova boot parameter + - Information + * - Boot an instance from an image and attach a non-bootable + volume. + - ``--block-device`` + - :ref:`Boot_instance_from_image_and_attach_non-bootable_volume` + * - Attach a swap disk to an instance. + - ``--swap`` + - :ref:`Attach_swap_or_ephemeral_disk_to_an_instance` + * - Create a volume from an image and boot an instance from that + volume. + - ``--block-device`` + - :ref:`Create_volume_from_image_and_boot_instance` + * - Boot from an existing source image, volume, or snapshot. + - ``--block-device`` + - :ref:`Create_volume_from_image_and_boot_instance` + * - Attach a swap disk to an instance. + - ``--swap`` + - :ref:`Attach_swap_or_ephemeral_disk_to_an_instance` + * - Attach an ephemeral disk to an instance. + - ``--ephemeral`` + - :ref:`Attach_swap_or_ephemeral_disk_to_an_instance` .. note:: diff --git a/doc/user-guide/source/cli_swift_large_object_creation.rst b/doc/user-guide/source/cli_swift_large_object_creation.rst index c0bba12855..d93327d43c 100644 --- a/doc/user-guide/source/cli_swift_large_object_creation.rst +++ b/doc/user-guide/source/cli_swift_large_object_creation.rst @@ -250,57 +250,65 @@ Comparison of static and dynamic large objects While static and dynamic objects have similar behavior, this table describes their differences: -+-------------------------+-----------------------------------------+-------------------------------------------+ -| | Static large object | Dynamic large object | -+=========================+=========================================+===========================================+ -| **End-to-end | Assured. The list of segments | Not guaranteed. The eventual consistency | -| integrity** | includes the MD5 checksum (``ETag``) of | model means that although you | -| | each segment. You cannot upload the | have uploaded a segment object, it | -| | the manifest object if the ``ETag`` in | might not appear in the container | -| | the list differs from the uploaded | listing until later. If you download | -| | segment object. If a segment is | the manifest before it appears in | -| | somehow lost, an attempt to download | the container, it does not form part | -| | the manifest object results in an | of the content returned in response | -| | error. | to a ``GET`` request. | -+-------------------------+-----------------------------------------+-------------------------------------------+ -| **Upload order** | You must upload the segment objects | You can upload manifest and segment | -| | before upload the manifest object. | objects in any order. You are recommended | -| | | to upload the manifest object after the | -| | | segments in case a premature download of | -| | | the manifest occurs. However, this is not | -| | | enforced. | -+-------------------------+-----------------------------------------+-------------------------------------------+ -| **Removal or addition | You cannot add or remove segment | You can upload new segment objects or | -| of segment objects** | objects from the manifest. However, you | remove existing segments. The names | -| | can create a completely new manifest | must simply match the ``PREFIX`` | -| | object of the same name with a | supplied in ``X-Object-Manifest``. | -| | different manifest list. | | -+-------------------------+-----------------------------------------+-------------------------------------------+ -| **Segment object | Segment objects must be at least 1 MB | Segment objects can be any size. | -| size and number** | in size (by default). The final segment | | -| | object can be any size. At most, 1000 | | -| | segments are supported (by default). | | -| | | | -+-------------------------+-----------------------------------------+-------------------------------------------+ -| **Segment object | The manifest list includes the | All segment objects must be in the | -| container name** | container name of each object. Segment | same container. | -| | objects can be in different containers. | | -| | | | -+-------------------------+-----------------------------------------+-------------------------------------------+ -| **Manifest object | The object has ``X-Static-Large-Object``| The ``X-Object-Manifest`` value is the | -| metadata** | set to ``true``. You do not set this | ``CONTAINER/PREFIX``, which indicates | -| | metadata directly. Instead the system | where the segment objects are located. | -| | sets it when you ``PUT`` a static | You supply this request header in the | -| | manifest object. | ``PUT`` operation. | -+-------------------------+-----------------------------------------+-------------------------------------------+ -| **Copying the manifest | Include the ``?multipart-manifest=get`` | The ``COPY`` operation does not create | -| object** | query string in the ``COPY`` request. | a manifest object. To duplicate a | -| | The new object contains the same | manifest object, use the ``GET`` | -| | manifest as the original. The segment | operation to read the value of | -| | objects are not copied. Instead,both | ``X-Object-Manifest`` and use this value | -| | the original and new manifest objects | in the ``X-Object-Manifest`` request | -| | share the same set of segment objects. | header in a ``PUT`` operation. This | -| | | creates a new manifest object that shares | -| | | the same set of segment objects as the | -| | | original manifest object. | -+-------------------------+-----------------------------------------+-------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 30 10 30 + :stub-columns: 1 + + * - Description + - Static large object + - Dynamic large object + * - End-to-end integrity + - Assured. The list of segments includes the MD5 checksum + (``ETag``) of each segment. You cannot upload the the manifest + object if the ``ETag`` in the list differs from the uploaded + segment object. If a segment is somehow lost, an attempt to + download the manifest object results in an error. + - Not guaranteed. The eventual consistency model means that + although you have uploaded a segment object, it might not + appear in the container listing until later. If you download + the manifest before it appears in the container, it does not + form part of the content returned in response to a ``GET`` + request. + * - Upload order + - You must upload the segment objects before upload the manifest + object. + - You can upload manifest and segment objects in any order. You + are recommended to upload the manifest object after the + segments in case a premature download of the manifest occurs. + However, this is not enforced. + * - Removal or addition of segment objects + - You cannot add or remove segment objects from the manifest. + However, you can create a completely new manifest object of the + same name with a different manifest list. + - You can upload new segment objects or remove existing segments. + The names must simply match the ``PREFIX`` supplied in + ``X-Object-Manifest``. + * - Segment object size and number + - Segment objects must be at least 1 MB in size (by default). The + final segment object can be any size. At most, 1000 segments + are supported (by default). + - Segment objects can be any size. + * - Segment object container name + - The manifest list includes the container name of each object. + Segment objects can be in different containers. + - All segment objects must be in the same container. + * - Manfiest object metadata + - The object has ``X-Static-Large-Object`` set to ``true``. You + do not set this metadata directly. Instead the system sets it + when you ``PUT`` a static manifest object. + - The ``X-Object-Manifest`` value is the ``CONTAINER/PREFIX``, + which indicates where the segment objects are located. You + supply this request header in the ``PUT`` operation. + * - Copying the manifest object + - Include the ``?multipart-manifest=get`` query string in the + ``COPY`` request. The new object contains the same manifest as + the original. The segment objects are not copied. Instead, both + the original and new manifest objects share the same set of + segment objects. + - The ``COPY`` operation does not create a manifest object. To + duplicate a manifest object, use the ``GET`` operation to read + the value of ``X-Object-Manifest`` and use this value in the + ``X-Object-Manifest`` request header in a ``PUT`` operation. + This creates a new manifest object that shares the same set of + segment objects as the original manifest object. diff --git a/doc/user-guide/source/sdk_schedule_objects_for_deletion.rst b/doc/user-guide/source/sdk_schedule_objects_for_deletion.rst index cd20f52026..75b6cd5485 100644 --- a/doc/user-guide/source/sdk_schedule_objects_for_deletion.rst +++ b/doc/user-guide/source/sdk_schedule_objects_for_deletion.rst @@ -3,7 +3,8 @@ Schedule objects for deletion ============================= To determine whether your Object Storage system supports this feature, -see :doc:`managing-openstack-object-storage-with-swift-cli`. Alternatively, check with your service provider. +see :doc:`managing-openstack-object-storage-with-swift-cli`. +Alternatively, check with your service provider. Scheduling an object for deletion is helpful for managing objects that you do not want to permanently store, such as log files, recurring full diff --git a/tox.ini b/tox.ini index 7b5d8253db..aef1e18581 100644 --- a/tox.ini +++ b/tox.ini @@ -90,13 +90,15 @@ commands = {toxinidir}/tools/generatepot-rst.sh {posargs} [doc8] # Settings for doc8: # Ignore target directories -ignore-path = doc/*/target,doc/*/build +ignore-path = doc/*/target,doc/*/build,doc/common-rst/glossary.rst # File extensions to use extensions = .rst,.txt +# Maximal line length should be 79 but we have some overlong lines. +# Let's not get far more in. +max-line-length = 100 # Disable some doc8 checks: # D000: Check RST validity (cannot handle lineos directive) -# D001: Ignore lines longer than 79 chars -ignore = D000, D001 +ignore = D000 [flake8] show-source = True