diff --git a/HACKING.rst b/HACKING.rst index d6b25c7523..86be947087 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -12,12 +12,13 @@ glance Specific Commandments assertIsInstance(A, B) - [G317] Change assertEqual(type(A), B) by optimal assert like assertIsInstance(A, B) -- [G318] Change assertEqual(A, None) or assertEqual(None, A) by optimal assert like - assertIsNone(A) +- [G318] Change assertEqual(A, None) or assertEqual(None, A) by optimal assert + like assertIsNone(A) - [G319] Validate that debug level logs are not translated - [G320] For python 3 compatibility, use six.text_type() instead of unicode() - [G327] Prevent use of deprecated contextlib.nested -- [G328] Must use a dict comprehension instead of a dict constructor with a sequence of key-value pairs +- [G328] Must use a dict comprehension instead of a dict constructor with + a sequence of key-value pairs - [G329] Python 3: Do not use xrange. - [G330] Python 3: do not use dict.iteritems. - [G331] Python 3: do not use dict.iterkeys. diff --git a/doc/source/admin/controllingservers.rst b/doc/source/admin/controllingservers.rst index 63eaa1adde..0c57e15f73 100644 --- a/doc/source/admin/controllingservers.rst +++ b/doc/source/admin/controllingservers.rst @@ -69,7 +69,8 @@ If no configuration file is found, you will see an error, like:: $> glance-api ERROR: Unable to locate any configuration file. Cannot load application glance-api -Here is an example showing how you can manually start the ``glance-api`` server and ``glance-registry`` in a shell.:: +Here is an example showing how you can manually start the ``glance-api`` server +and ``glance-registry`` in a shell.:: $ sudo glance-api --config-file glance-api.conf --debug & jsuh@mc-ats1:~$ 2011-04-13 14:50:12 DEBUG [glance-api] ******************************************************************************** @@ -120,9 +121,9 @@ Here is an example showing how you can manually start the ``glance-api`` server root 20012 2.0 0.1 25188 13356 pts/1 S 12:47 0:00 /usr/bin/python /usr/bin/glance-registry glance-registry.conf jsuh 20017 0.0 0.0 3368 744 pts/1 S+ 12:47 0:00 grep glance -Simply supply the configuration file as the parameter to the ``--config-file`` option -(the ``etc/glance-api.conf`` and ``etc/glance-registry.conf`` sample configuration -files were used in the above example) and then any other options +Simply supply the configuration file as the parameter to the ``--config-file`` +option (the ``etc/glance-api.conf`` and ``etc/glance-registry.conf`` sample +configuration files were used in the above example) and then any other options you want to use. (``--debug`` was used above to show some of the debugging output that the server shows when starting up. Call the server program with ``--help`` to see all available options you can specify on the @@ -133,9 +134,10 @@ configuration files, see the section entitled :ref:`Configuring Glance servers ` Note that the server `daemonizes` itself by using the standard -shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend -using the ``glance-control`` server daemon wrapper for daemonizing. See below -for more details on daemonization with ``glance-control``. +shell backgrounding indicator, ``&``, in the previous example. +For most use cases, we recommend using the ``glance-control`` server daemon +wrapper for daemonizing. See below for more details on daemonization +with ``glance-control``. Using the ``glance-control`` program to start the server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,8 +152,8 @@ meaning that the server program process runs in the background. To start a Glance server with ``glance-control``, simply call ``glance-control`` with a server and the word "start", followed by -any command-line options you wish to provide. Start the server with ``glance-control`` -in the following way:: +any command-line options you wish to provide. Start the server +with ``glance-control`` in the following way:: $> sudo glance-control [OPTIONS] start [CONFPATH] @@ -188,13 +190,15 @@ and respawned if necessary, use the following option:: $ sudo glance-control [service] start --respawn ... -Note that this will cause ``glance-control`` itself to remain running. Also note -that deliberately stopped services are not respawned, neither are rapidly bouncing -services (where process death occurred within one second of the last launch). +Note that this will cause ``glance-control`` itself to remain running. +Also note that deliberately stopped services are not respawned, +neither are rapidly bouncing services (where process death occurred within +one second of the last launch). -By default, output from glance services is discarded when launched with ``glance-control``. -In order to capture such output via syslog, use the following option:: +By default, output from glance services is discarded when launched +with ``glance-control``. In order to capture such output via syslog, +use the following option:: $ sudo glance-control --capture-output ... @@ -236,6 +240,6 @@ here:: $> sudo glance-control api reload Reloading glance-api (pid 18506) with signal(1) -A reload sends a SIGHUP signal to the master process and causes new configuration -settings to be picked up without any interruption to the running service (provided -neither bind_host or bind_port has changed). +A reload sends a SIGHUP signal to the master process and causes new +configuration settings to be picked up without any interruption to the +running service (provided neither bind_host or bind_port has changed). diff --git a/doc/source/admin/db-sqlalchemy-migrate.rst b/doc/source/admin/db-sqlalchemy-migrate.rst index c167f0f89d..db94ff1385 100644 --- a/doc/source/admin/db-sqlalchemy-migrate.rst +++ b/doc/source/admin/db-sqlalchemy-migrate.rst @@ -38,7 +38,8 @@ Sync the Database glance-manage db sync -Place a database under migration control and upgrade, creating it first if necessary. +Place a database under migration control and upgrade, +creating it first if necessary. Determining the Database Version diff --git a/doc/source/admin/interoperable-image-import.rst b/doc/source/admin/interoperable-image-import.rst index 424f527024..bcaa799f78 100644 --- a/doc/source/admin/interoperable-image-import.rst +++ b/doc/source/admin/interoperable-image-import.rst @@ -59,7 +59,7 @@ task policies unrestricted while not exposing the Tasks API to end users. Thus, the following is the recommended configuration for the task-related policies: -.. code-block:: none +.. code-block:: ini "get_task": "", "get_tasks": "", diff --git a/doc/source/admin/property-protections.rst b/doc/source/admin/property-protections.rst index 790fdb70e6..58eb7fc552 100644 --- a/doc/source/admin/property-protections.rst +++ b/doc/source/admin/property-protections.rst @@ -44,15 +44,15 @@ expression matching a set of properties to be protected. .. note:: - Section headers must compile to a valid regular expression, otherwise + Section headers must compile to a valid regular expression, otherwise glance api service will not start. Regular expressions will be handled by python's re module which is PERL like. Each section describes four key-value pairs, where the key is one of ``create/read/update/delete``, and the value is a comma separated list of user -roles that are permitted to perform that operation in the Glance API. **If any of -the keys are not specified, then the glance api service will not start -successfully.** +roles that are permitted to perform that operation in the Glance API. +**If any of the keys are not specified, then the glance api service will +not start successfully.** In the list of user roles, ``@`` means all roles and ``!`` means no role. **If both @ and ! are specified for the same rule then the glance api service @@ -93,7 +93,8 @@ disabled for all roles. If an operation is misspelled or omitted, that operation will be disabled for all roles. -Disallowing ``read`` operations will also disallow ``update/delete`` operations. +Disallowing ``read`` operations will also disallow ``update/delete`` +operations. A successful HTTP request will return status ``200 OK``. If the user is not permitted to perform the requested action, ``403 Forbidden`` will be returned. diff --git a/doc/source/admin/tasks.rst b/doc/source/admin/tasks.rst index f08ef72775..5659c2213a 100644 --- a/doc/source/admin/tasks.rst +++ b/doc/source/admin/tasks.rst @@ -120,8 +120,8 @@ the endpoint to which it belongs. The id is used as a token in request URIs to interact with that specific task. In addition to the usual properties you'd expect (for example, ``created_at``, -``self``, ``type``, ``status``, ``updated_at``, etc.), tasks have these properties of -interest: +``self``, ``type``, ``status``, ``updated_at``, etc.), +tasks have these properties of interest: * ``input``: this is defined to be a JSON blob, the exact content of which will depend upon the requirements set by the specific cloud deployer. The intent diff --git a/doc/source/configuration/configuring.rst b/doc/source/configuration/configuring.rst index 09a6e7bb74..6a664b0fbc 100644 --- a/doc/source/configuration/configuring.rst +++ b/doc/source/configuration/configuring.rst @@ -29,9 +29,10 @@ Most configuration is done via configuration files, with the Glance API server and Glance Registry server using separate configuration files. When starting up a Glance server, you can specify the configuration file to -use (see :ref:`the documentation on controller Glance servers `). -If you do **not** specify a configuration file, Glance will look in the following -directories for a configuration file, in order: +use (see :ref:`the documentation on controller Glance servers +`). If you do **not** specify a configuration file, +Glance will look in the following directories for a configuration file, +in order: * ``~/.glance`` * ``~/`` @@ -87,9 +88,9 @@ Glance has a few command-line options that are common to all Glance programs: Takes a path to a configuration file to use when running the program. If this CLI option is not specified, then we check to see if the first argument is a - file. If it is, then we try to use that as the configuration file. If there is - no file or there were no arguments, we search for a configuration file in the - following order: + file. If it is, then we try to use that as the configuration file. + If there is no file or there were no arguments, we search for a configuration + file in the following order: * ``~/.glance`` * ``~/`` @@ -106,10 +107,10 @@ Glance has a few command-line options that are common to all Glance programs: Specified on the command line only. Takes a path to a configuration directory from which all \*.conf fragments - are loaded. This provides an alternative to multiple ``--config-file`` options - when it is inconvenient to explicitly enumerate all the configuration files, - for example when an unknown number of config fragments are being generated - by a deployment framework. + are loaded. This provides an alternative to multiple ``--config-file`` + options when it is inconvenient to explicitly enumerate all the + configuration files, for example when an unknown number of config fragments + are being generated by a deployment framework. If ``--config-dir`` is set, then ``--config-file`` is ignored. @@ -134,7 +135,8 @@ Glance has a few command-line options that are common to all Glance programs: * ``glance-manage.conf`` By default ``glance-manage.conf`` only specifies a custom logging file but - other configuration options for ``glance-manage`` should be migrated in there. + other configuration options for ``glance-manage`` should be migrated + in there. **Warning**: Options set in ``glance-manage.conf`` will override options of the same section and name set in the other two. Similarly, options in ``glance-api.conf`` will override options set in ``glance-registry.conf``. @@ -158,7 +160,8 @@ startup and binding behaviour for the API and registry servers, respectively. ``bind_port=PORT`` The port the server should bind to. - Optional. Default: ``9191`` for the registry server, ``9292`` for the API server + Optional. Default: ``9191`` for the registry server, ``9292`` for + the API server ``backlog=REQUESTS`` Number of backlog requests to configure the socket with. @@ -184,8 +187,8 @@ startup and binding behaviour for the API and registry servers, respectively. performance (especially if using SSL with compression enabled). Typically it is recommended to have one worker process per CPU. The value `0` will prevent any new worker processes from being created. When ``data_api`` - is set to ``glance.db.simple.api``, ``workers`` MUST be set to either ``0`` or - ``1``. + is set to ``glance.db.simple.api``, ``workers`` MUST be set to either ``0`` + or ``1``. Optional. Default: The number of CPUs available will be used by default. @@ -249,8 +252,8 @@ the API server accesses the registry server. ``registry_client_ca_file=PATH`` Optional. Default: Not set. - The path to a Certifying Authority's cert file to use in SSL connections to the - registry server, if any. Alternately, you may set the + The path to a Certifying Authority's cert file to use in SSL connections + to the registry server, if any. Alternately, you may set the ``GLANCE_CLIENT_CA_FILE`` environ variable to a filepath of the CA cert file ``registry_client_insecure=False`` @@ -352,29 +355,32 @@ servers log messages. Logging Options Available Only in Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You will want to place the different logging options in the **[DEFAULT]** section -in your application configuration file. As an example, you might do the following -for the API server, in a configuration file called ``etc/glance-api.conf``:: +You will want to place the different logging options in the **[DEFAULT]** +section in your application configuration file. As an example, you might +do the following for the API server, in a configuration file called +``etc/glance-api.conf``:: [DEFAULT] log_file = /var/log/glance/api.log ``log_file`` - The filepath of the file to use for logging messages from Glance's servers. If - missing, the default is to output messages to ``stdout``, so if you are running - Glance servers in a daemon mode (using ``glance-control``) you should make - sure that the ``log_file`` option is set appropriately. + The filepath of the file to use for logging messages from Glance's servers. + If missing, the default is to output messages to ``stdout``, + so if you are running Glance servers in a daemon mode + (using ``glance-control``) you should make sure that the ``log_file`` + option is set appropriately. ``log_dir`` - The filepath of the directory to use for log files. If not specified (the default) - the ``log_file`` is used as an absolute filepath. + The filepath of the directory to use for log files. + If not specified (the default) the ``log_file`` is used as + an absolute filepath. ``log_date_format`` The format string for timestamps in the log output. Defaults to ``%Y-%m-%d %H:%M:%S``. See the - `logging module `_ documentation for - more information on setting this format string. + `logging module `_ + documentation for more information on setting this format string. ``log_use_syslog`` Use syslog logging functionality. @@ -415,10 +421,10 @@ Configuring the Filesystem Storage Backend `This option is specific to the filesystem storage backend.` - Sets the path where the filesystem storage backend write disk images. Note that - the filesystem storage backend will attempt to create this directory if it does - not exist. Ensure that the user that ``glance-api`` runs under has write - permissions to this directory. + Sets the path where the filesystem storage backend write disk images. + Note that the filesystem storage backend will attempt to create this + directory if it does not exist. Ensure that the user that ``glance-api`` + runs under has write permissions to this directory. ``filesystem_store_file_perm=PERM_MODE`` Optional. Default: ``0`` @@ -427,14 +433,16 @@ Configuring the Filesystem Storage Backend `This option is specific to the filesystem storage backend.` - The required permission value, in octal representation, for the created image file. - You can use this value to specify the user of the consuming service (such as Nova) as - the only member of the group that owns the created files. To keep the default value, - assign a permission value that is less than or equal to 0. Note that the file owner - must maintain read permission; if this value removes that permission an error message - will be logged and the BadStoreConfiguration exception will be raised. If the Glance - service has insufficient privileges to change file access permissions, a file will still - be saved, but a warning message will appear in the Glance log. + The required permission value, in octal representation, for the created + image file. You can use this value to specify the user of the consuming + service (such as Nova) as the only member of the group that owns + the created files. To keep the default value, assign a permission value that + is less than or equal to 0. Note that the file owner must maintain read + permission; if this value removes that permission an error message + will be logged and the BadStoreConfiguration exception will be raised. + If the Glance service has insufficient privileges to change file access + permissions, a file will still be saved, but a warning message + will appear in the Glance log. Configuring the Filesystem Storage Backend with multiple stores ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -452,8 +460,8 @@ Configuring the Filesystem Storage Backend with multiple stores to the filesystem storage backend only. filesystem_store_datadirs option allows administrators to configure - multiple store directories to save glance image in filesystem storage backend. - Each directory can be coupled with its priority. + multiple store directories to save glance image in filesystem storage + backend. Each directory can be coupled with its priority. **NOTE**: @@ -475,18 +483,21 @@ Configuring the Swift Storage Backend Can only be specified in configuration files. - Deprecated. Use ``auth_address`` in the Swift back-end configuration file instead. + Deprecated. Use ``auth_address`` in the Swift back-end configuration + file instead. `This option is specific to the Swift storage backend.` - Sets the authentication URL supplied to Swift when making calls to its storage - system. For more information about the Swift authentication system, please - see the `Swift auth `_ + Sets the authentication URL supplied to Swift when making calls to its + storage system. For more information about the Swift authentication system, + please see the + `Swift auth `_ documentation. **IMPORTANT NOTE**: Swift authentication addresses use HTTPS by default. This means that if you are running Swift with authentication over HTTP, you need - to set your ``swift_store_auth_address`` to the full URL, including the ``http://``. + to set your ``swift_store_auth_address`` to the full URL, + including the ``http://``. ``swift_store_user=USER`` Required when using the Swift storage backend. @@ -527,8 +538,8 @@ Configuring the Swift Storage Backend `This option is specific to the Swift storage backend.` - If true, Glance will attempt to create the container ``swift_store_container`` - if it does not exist. + If true, Glance will attempt to create the container + ``swift_store_container`` if it does not exist. ``swift_store_large_object_size=SIZE_IN_MB`` Optional. Default: ``5120`` @@ -573,16 +584,16 @@ Configuring the Swift Storage Backend images. When set to an integer value between 1 and 32, a single-tenant store will use multiple containers to store images, and this value will determine how many characters from an image UUID are checked when determining what - container to place the image in. The maximum number of containers that will be - created is approximately equal to 16^N. This setting is used only when + container to place the image in. The maximum number of containers that will + be created is approximately equal to 16^N. This setting is used only when swift_store_multi_tenant is disabled. Example: if this config option is set to 3 and swift_store_container = 'glance', then an image with UUID 'fdae39a1-bac5-4238-aba4-69bcc726e848' would be placed in the container 'glance_fda'. All dashes in the UUID are included when creating the container - name but do not count toward the character limit, so in this example with N=10 - the container name would be 'glance_fdae39a1-ba'. + name but do not count toward the character limit, so in this example + with N=10 the container name would be 'glance_fdae39a1-ba'. When choosing the value for swift_store_multiple_containers_seed, deployers should discuss a suitable value with their swift operations team. The authors @@ -590,11 +601,11 @@ Configuring the Swift Storage Backend which will create a maximum of ~256 containers. Choosing a higher number than this, even in extremely large scale deployments, may not have any positive impact on performance and could lead to a large number of empty, unused - containers. The largest of deployments could notice an increase in performance - if swift rate limits are throttling on single container. Note: If dynamic - container creation is turned off, any value for this configuration option - higher than '1' may be unreasonable as the deployer would have to manually - create each container. + containers. The largest of deployments could notice an increase in + performance if swift rate limits are throttling on single container. + Note: If dynamic container creation is turned off, any value for this + configuration option higher than '1' may be unreasonable as the deployer + would have to manually create each container. ``swift_store_admin_tenants`` Can only be specified in configuration files. @@ -870,7 +881,8 @@ Debian-based distributions. Sets the RADOS user to authenticate as. This is only needed when `RADOS authentication `_ - is `enabled. `_ + is `enabled. + `_ A keyring must be set for this user in the Ceph configuration file, e.g. with a user ``glance``:: @@ -878,8 +890,8 @@ configuration file, e.g. with a user ``glance``:: [client.glance] keyring=/etc/glance/rbd.keyring -To set up a user named ``glance`` with minimal permissions, using a pool called -``images``, run:: +To set up a user named ``glance`` with minimal permissions, +using a pool called ``images``, run:: rados mkpool images ceph-authtool --create-keyring /etc/glance/rbd.keyring @@ -938,7 +950,8 @@ documentation for more information. `This option is specific to the Cinder storage backend.` Sets the info to match when looking for cinder in the service catalog. - Format is : separated values of the form: :: + Format is : + separated values of the form: :: ``cinder_endpoint_template=http://ADDR:PORT/VERSION/%(tenant)s`` Optional. Default: ``None`` @@ -1103,7 +1116,8 @@ Configuring the VMware Storage Backend option is: ::. where datacenter_path is the inventory path to the datacenter where the - datastore is located. An optional weight can be given to specify the priority. + datastore is located. An optional weight can be given to specify the + priority. Example:: @@ -1143,7 +1157,8 @@ Configuring the VMware Storage Backend Can only be specified in configuration files. - The path to access the folder where the images will be stored in the datastore. + The path to access the folder where the images will be stored + in the datastore. ``vmware_api_insecure=ON_OFF`` Optional. Default: ``False`` @@ -1174,10 +1189,11 @@ The following configuration option is specified in the ``image_size_cap=SIZE`` Optional. Default: ``1099511627776`` (1 TB) - Maximum image size, in bytes, which can be uploaded through the Glance API server. + Maximum image size, in bytes, which can be uploaded through + the Glance API server. - **IMPORTANT NOTE**: this value should only be increased after careful consideration - and must be set to a value under 8 EB (9223372036854775808). + **IMPORTANT NOTE**: this value should only be increased after careful + consideration and must be set to a value under 8 EB (9223372036854775808). Configuring Glance User Storage Quota ------------------------------------- @@ -1296,12 +1312,12 @@ One main configuration file option affects the image cache. Default: ``10737418240`` (10 GB) Size, in bytes, that the image cache should be constrained to. Images files - are cached automatically in the local image cache, even if the writing of that - image file would put the total cache size over this size. The + are cached automatically in the local image cache, even if the writing of + that image file would put the total cache size over this size. The ``glance-cache-pruner`` executable is what prunes the image cache to be equal - to or less than this value. The ``glance-cache-pruner`` executable is designed - to be run via cron on a regular basis. See more about this executable in - :ref:`Controlling the Growth of the Image Cache ` + to or less than this value. The ``glance-cache-pruner`` executable is + designed to be run via cron on a regular basis. See more about this + executable in :ref:`Controlling the Growth of the Image Cache ` .. _configuring-the-glance-registry: @@ -1346,11 +1362,12 @@ on command line) .. include:: ../deprecate-registry.inc Defines which version(s) of the Registry API will be enabled. - If the Glance API server parameter ``enable_v1_api`` has been set to ``True`` the - ``enable_v1_registry`` has to be ``True`` as well. + If the Glance API server parameter ``enable_v1_api`` has been set to ``True`` + the ``enable_v1_registry`` has to be ``True`` as well. If the Glance API server parameter ``enable_v2_api`` has been set to ``True`` and the parameter ``data_api`` has been set to - ``glance.db.registry.api`` the ``enable_v2_registry`` has to be set to ``True`` + ``glance.db.registry.api`` the ``enable_v2_registry`` has to be + set to ``True`` Configuring Notifications ------------------------- @@ -1366,8 +1383,8 @@ configuration file. ``messaging``, ``messagingv2``, ``log`` and ``routing``. **NOTE** - In M release, the``[DEFAULT]/notification_driver`` option has been deprecated in favor - of ``[oslo_messaging_notifications]/driver``. + In M release, the``[DEFAULT]/notification_driver`` option has been + deprecated in favor of ``[oslo_messaging_notifications]/driver``. For more information see :ref:`Glance notifications ` and `oslo.messaging `_. @@ -1376,12 +1393,13 @@ configuration file. Optional. Default: ``[]`` List of disabled notifications. A notification can be given either as a - notification type to disable a single event, or as a notification group prefix - to disable all events within a group. + notification type to disable a single event, or as a notification group + prefix to disable all events within a group. - Example: if this config option is set to ["image.create", "metadef_namespace"], - then "image.create" notification will not be sent after image is created and - none of the notifications for metadefinition namespaces will be sent. + Example: if this config option is set to + ["image.create", "metadef_namespace"], then "image.create" notification will + not be sent after image is created and none of the notifications + for metadefinition namespaces will be sent. Configuring Glance Property Protections --------------------------------------- @@ -1472,21 +1490,21 @@ profiling feature for glance-api and glance-registry service. ``hmac_keys=`` Optional. Default: ``SECRET_KEY`` - **IMPORTANT NOTE**: in order to make profiling work as designed operator needs - to make those values of HMAC key be consistent for all services in their - deployment. Without HMAC key the profiling will not be triggered even profiling - feature is enabled. + **IMPORTANT NOTE**: in order to make profiling work as designed operator + needs to make those values of HMAC key be consistent for all services + in their deployment. Without HMAC key the profiling will not be triggered + even profiling feature is enabled. **IMPORTANT NOTE**: previously HMAC keys (as well as enabled parameter) were - placed at `/etc/glance/api-paste.ini` and `/etc/glance/registry-paste.ini` files - for Glance API and Glance Registry services respectively. Starting with + placed at `/etc/glance/api-paste.ini` and `/etc/glance/registry-paste.ini` + files for Glance API and Glance Registry services respectively. Starting with osprofiler 0.3.1 release there is no need to set these arguments in the `*-paste.ini` files. This functionality is still supported, although the config values are having larger priority. - The config value ``trace_sqlalchemy`` is used to determine whether fully enable - sqlalchemy engine based SQL execution profiling feature for glance-api and - glance-registry services. + The config value ``trace_sqlalchemy`` is used to determine whether fully + enable sqlalchemy engine based SQL execution profiling feature for glance-api + and glance-registry services. ``trace_sqlalchemy=`` Optional. Default: ``False`` diff --git a/doc/source/contributor/domain_implementation.rst b/doc/source/contributor/domain_implementation.rst index 5b04a37214..f2b7ad26c7 100644 --- a/doc/source/contributor/domain_implementation.rst +++ b/doc/source/contributor/domain_implementation.rst @@ -45,7 +45,7 @@ their locations: implementation. Further, the Client block calls the Router; the Location block calls the Glance Store, and the Data Access layer calls the DBMS. - Additional information conveyed in the image is the location in + Additional information conveyed in the image is the location in the Glance code of the various components: Router: api/v2/router.py REST API: api/v2/* diff --git a/doc/source/contributor/modules.rst b/doc/source/contributor/modules.rst index 312a68ca49..77cef6d4be 100644 --- a/doc/source/contributor/modules.rst +++ b/doc/source/contributor/modules.rst @@ -17,4 +17,4 @@ Module Reference .. toctree:: :maxdepth: 1 - api/autoindex \ No newline at end of file + api/autoindex diff --git a/doc/source/contributor/release-cpl.rst b/doc/source/contributor/release-cpl.rst index f17a87c3d0..91512fbc66 100644 --- a/doc/source/contributor/release-cpl.rst +++ b/doc/source/contributor/release-cpl.rst @@ -224,9 +224,10 @@ following: - Write `release notes`_ - Announce that any non-release-critical changes won't be accepted from this - point onwards until the final Glance release is made. Consider adding -2 on such - reviews with good description to prevent further updates. This also helps in - keeping the gate relatively free to process the release-critical changes. + point onwards until the final Glance release is made. Consider adding -2 on + such reviews with good description to prevent further updates. + This also helps in keeping the gate relatively free to process + the release-critical changes. Final Releases @@ -238,9 +239,9 @@ things in Glance need to be updated immediately. - Right after cutting the stable branch, Glance release version (not the API version) must be bumped so that all further development is attributed to the - next release version. This could be done by adding an empty commit with commit - message containing the flag ``Sem-Ver: api-break`` to indicate a version. Here - is a sample commit attempting to `bump the release version`_. + next release version. This could be done by adding an empty commit with + commit message containing the flag ``Sem-Ver: api-break`` to indicate + a version. Here is a sample commit attempting to `bump the release version`_. - The migration tooling that Glance uses relies on some constants defined in `glance/db/migration.py`_. Post final release, those need *immediate* updating. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 75a1aaec5a..519df884c4 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -27,7 +27,8 @@ Ocata ~~~~~ -To install Glance, see the Ocata Image service install guide for each distribution: +To install Glance, see the Ocata Image service install guide for +each distribution: - `Ubuntu `__ - `CentOS and RHEL `__ @@ -36,7 +37,8 @@ To install Glance, see the Ocata Image service install guide for each distributi Newton ~~~~~~ -To install Glance, see the Newton Image service install guide for each distribution: +To install Glance, see the Newton Image service install guide for +each distribution: - `Ubuntu `__ - `CentOS and RHEL `__ diff --git a/doc/source/user/glanceapi.rst b/doc/source/user/glanceapi.rst index ea231c4031..5a9e65ef15 100644 --- a/doc/source/user/glanceapi.rst +++ b/doc/source/user/glanceapi.rst @@ -265,7 +265,8 @@ These two resources also accept additional query parameters: * ``limit=LIMIT`` - When present, the maximum number of results returned will not exceed ``LIMIT``. + When present, the maximum number of results returned will not + exceed ``LIMIT``. .. note:: @@ -277,12 +278,13 @@ These two resources also accept additional query parameters: An admin user may use the `is_public` parameter to control which results are returned. - When the `is_public` parameter is absent or set to `True` the following images - will be listed: Images whose `is_public` field is `True`, owned images and - shared images. + When the `is_public` parameter is absent or set to `True` the following + images will be listed: Images whose `is_public` field is `True`, + owned images and shared images. - When the `is_public` parameter is set to `False` the following images will be - listed: Images (owned, shared, or non-owned) whose `is_public` field is `False`. + When the `is_public` parameter is set to `False` the following images will + be listed: Images (owned, shared, or non-owned) whose `is_public` + field is `False`. When the `is_public` parameter is set to `None` all images will be listed irrespective of owner, shared status or the `is_public` field. @@ -507,8 +509,8 @@ The list of metadata headers that Glance accepts are listed below. does not support the backing store, Glance will return a **400 Bad Request**. When not present, Glance will store the disk image data in the backing - store that is marked as default. See the configuration option ``default_store`` - for more information. + store that is marked as default. See the configuration option + ``default_store`` for more information. * ``x-image-meta-disk_format`` @@ -550,8 +552,8 @@ The list of metadata headers that Glance accepts are listed below. This header is optional. - When Glance finds the string "true" (case-insensitive), the image is marked as - a public one, meaning that any user may view its metadata and may read + When Glance finds the string "true" (case-insensitive), the image is marked + as a public one, meaning that any user may view its metadata and may read the disk image from Glance. When not present, the image is assumed to be *not public* and owned by @@ -562,7 +564,8 @@ The list of metadata headers that Glance accepts are listed below. This header is optional. When present, it specifies the minimum amount of RAM in megabytes required to run this image on a server. - When not present, the image is assumed to have a minimum RAM requirement of 0. + When not present, the image is assumed to have a minimum RAM + requirement of 0. * ``x-image-meta-min_disk`` @@ -587,8 +590,8 @@ The list of metadata headers that Glance accepts are listed below. When Glance receives any HTTP header whose key begins with the string prefix ``x-image-meta-property-``, Glance adds the key and value to a set of custom, free-form image properties stored with the image. The key is a - lower-cased string following the prefix ``x-image-meta-property-`` with dashes - and punctuation replaced with underscores. + lower-cased string following the prefix ``x-image-meta-property-`` with + dashes and punctuation replaced with underscores. For example, if the following HTTP header were sent:: diff --git a/doc/source/user/glancemetadefcatalogapi.rst b/doc/source/user/glancemetadefcatalogapi.rst index cf3eaab855..11ccab8426 100644 --- a/doc/source/user/glancemetadefcatalogapi.rst +++ b/doc/source/user/glancemetadefcatalogapi.rst @@ -142,7 +142,8 @@ GET resource also accepts additional query parameters: * ``limit=LIMIT`` - When present the maximum number of results returned will not exceed ``LIMIT``. + When present the maximum number of results returned will not + exceed ``LIMIT``. .. note:: diff --git a/doc/source/user/signature.rst b/doc/source/user/signature.rst index 7ba723f2c4..69779522d0 100644 --- a/doc/source/user/signature.rst +++ b/doc/source/user/signature.rst @@ -51,9 +51,10 @@ Then replace http://localhost:5000/v3 with the URL of keystone, also adding /v3 to the end of it. For example, 'https://192.168.245.9:5000/v3'. -Another option in etc/glance-api.conf which can be configured is which key manager -to use. By default Glance will use the default key manager defined by the Castellan -key manager interface, which is currently the Barbican key manager. +Another option in etc/glance-api.conf which can be configured is which key +manager to use. By default Glance will use the default key manager defined by +the Castellan key manager interface, which is currently the Barbican +key manager. In glance-api.conf find the following lines:: @@ -148,7 +149,9 @@ Follow these instructions to create your keys:: Getting Private key Upload your certificate. This only has to be done once as you can use -the same ``Secret href`` for many images until it expires:: +the same ``Secret href`` for many images until it expires. + +.. code-block:: console $ openstack secret store --name test --algorithm RSA --expiration 2016-06-29 --secret-type certificate --payload-content-type "application/octet-stream" --payload-content-encoding base64 --payload "$(base64 new_cert.crt)" +---------------+-----------------------------------------------------------------------+ diff --git a/doc/source/user/statuses.rst b/doc/source/user/statuses.rst index 9f07cc1640..64a502c465 100644 --- a/doc/source/user/statuses.rst +++ b/doc/source/user/statuses.rst @@ -40,8 +40,8 @@ Images in Glance can be in one of the following statuses: Denotes that an import data-put call has been made. While in this status, a call to `PUT /file` is disallowed. (Note that a call to `PUT /file` on a queued image puts the image into saving status. Calls to `PUT /stage` are - disallowed while an image is in saving status. Thus it’s not possible to use - both upload methods on the same image.) + disallowed while an image is in saving status. Thus it’s not possible to + use both upload methods on the same image.) * ``importing`` diff --git a/rally-jobs/plugins/README.rst b/rally-jobs/plugins/README.rst index 9b98924069..3aa58df22c 100644 --- a/rally-jobs/plugins/README.rst +++ b/rally-jobs/plugins/README.rst @@ -1,9 +1,9 @@ Rally plugins ============= -All *.py modules from this directory will be auto-loaded by Rally and all +All ``*.py`` modules from this directory will be auto-loaded by Rally and all plugins will be discoverable. There is no need of any extra configuration and there is no difference between writing them here and in rally code base. Note that it is better to push all interesting and useful benchmarks to Rally -code base, this simplifies administration for Operators. \ No newline at end of file +code base, this simplifies administration for Operators. diff --git a/test-requirements.txt b/test-requirements.txt index d7a4d588e2..6254dbeff9 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -23,6 +23,7 @@ testtools>=2.2.0 # MIT psutil>=3.2.2 # BSD oslotest>=3.2.0 # Apache-2.0 os-testr>=1.0.0 # Apache-2.0 +doc8>=0.6.0 # Apache-2.0 # Optional packages that should be installed when testing PyMySQL>=0.7.6 # MIT License diff --git a/tox.ini b/tox.ini index 9e51243866..9aa8f5e7c5 100644 --- a/tox.ini +++ b/tox.ini @@ -59,6 +59,7 @@ commands = bandit -c bandit.yaml -r glance -n5 -p gate # Check that .po and .pot files are valid: bash -c "find glance -type f -regex '.*\.pot?' -print0|xargs -0 -n 1 msgfmt --check-format -o /dev/null" + doc8 {posargs} [testenv:genconfig] commands = @@ -89,6 +90,9 @@ deps = bindep commands = bindep test usedevelop = False +[doc8] +ignore-path = .venv,.git,.tox,*glance/locale*,*lib/python*,glance.egg*,api-ref/build,doc/build,doc/source/contributor/api + [flake8] # TODO(dmllr): Analyze or fix the warnings blacklisted below # E711 comparison to None should be 'if cond is not None:'