[docs] Update description of Glance-Swift conf options

This patch:

1. Updates the description of 4 deprecated options:
   * swift_store_auth_version
   * swift_store_auth_address
   * swift_store_user
   * swift_store_key
2. Adds a new sub-section: Configuring Swift configuration file.

Co-Authored-By: Mike Fedosin <mfedosin@mirantis.com>
Co-Authored-By: Olena Logvinova <ologvinova@mirantis.com>

Change-Id: I41baa2343cf92d819a4a64a2e269e1cb2e3be3f4
Closes-Bug: #1426813
Closes-Bug: #1509349

doc/source/configuring.rst

@@ -518,6 +518,8 @@ Required when using the Swift storage backend.
 
 Can only be specified in configuration files.
 
+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
@@ -536,6 +538,8 @@ Required when using the Swift storage backend.
 
 Can only be specified in configuration files.
 
+Deprecated. Use ``user`` in the Swift back-end configuration file instead.
+
 `This option is specific to the Swift storage backend.`
 
 Sets the user to authenticate against the ``swift_store_auth_address`` with.
@@ -546,6 +550,8 @@ Required when using the Swift storage backend.
 
 Can only be specified in configuration files.
 
+Deprecated. Use ``key`` in the Swift back-end configuration file instead.
+
 `This option is specific to the Swift storage backend.`
 
 Sets the authentication key to authenticate against the
@@ -667,6 +673,9 @@ example: swift_store_admin_tenants = service:glance,*:admin
 
 Can only be specified in configuration files.
 
+Deprecated. Use ``auth_version`` in the Swift back-end configuration
+file instead.
+
 `This option is specific to the Swift storage backend.`
 
 Optional. Default: ``2``
@@ -775,6 +784,105 @@ Can only be specified in configuration files.
 
 Optional. Default: ``False``
 
+Configuring Swift configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``swift_store_config_file`` is set, Glance will use information
+from the file specified under this parameter.
+
+.. note::
+   The ``swift_store_config_file`` is currently used only for single-tenant
+   Swift store configurations. If you configure a multi-tenant Swift store
+   back end (``swift_store_multi_tenant=True``), ensure that both
+   ``swift_store_config_file`` and ``default_swift_reference`` are *not* set.
+
+The file contains a set of references like:
+
+.. code-block:: ini
+
+    [ref1]
+    user = tenant:user1
+    key = key1
+    auth_version = 2
+    auth_address = http://localhost:5000/v2.0
+
+    [ref2]
+    user = project_name:user_name2
+    key = key2
+    user_domain_id = default
+    project_domain_id = default
+    auth_version = 3
+    auth_address = http://localhost:5000/v3
+
+A default reference must be configured. Its parameters will be used when
+creating new images. For example, to specify ``ref2`` as the default
+reference, add the following value to the [glance_store] section of
+:file:`glance-api.conf` file:
+
+.. code-block:: ini
+
+    default_swift_reference = ref2
+
+In the reference, a user can specify the following parameters:
+
+* ``user``
+
+  A *project_name user_name* pair in the ``project_name:user_name`` format
+  to authenticate against the Swift authentication service.
+
+* ``key``
+
+  An authentication key for a user authenticating against the Swift
+  authentication service.
+
+* ``auth_address``
+
+  An address where the Swift authentication service is located.
+
+* ``auth_version``
+
+  A version of the authentication service to use.
+  Valid versions are ``2`` and ``3`` for Keystone and ``1``
+  (deprecated) for Swauth and Rackspace.
+
+  Optional. Default: ``2``
+
+* ``project_domain_id``
+
+  A domain ID of the project which is the requested project-level
+  authorization scope.
+
+  Optional. Default: ``None``
+
+  `This option can be specified if ``auth_version`` is ``3`` .`
+
+* ``project_domain_name``
+
+  A domain name of the project which is the requested project-level
+  authorization scope.
+
+  Optional. Default: ``None``
+
+  `This option can be specified if ``auth_version`` is ``3`` .`
+
+* ``user_domain_id``
+
+  A domain ID of the user which is the requested domain-level
+  authorization scope.
+
+  Optional. Default: ``None``
+
+  `This option can be specified if ``auth_version`` is ``3`` .`
+
+* ``user_domain_name``
+
+  A domain name of the user which is the requested domain-level
+  authorization scope.
+
+  Optional. Default: ``None``
+
+  `This option can be specified if ``auth_version`` is ``3``. `
+
 Configuring the S3 Storage Backend
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

etc/glance-swift.conf.sample

@@ -13,9 +13,13 @@
 [ref1]
 user = tenant:user1
 key = key1
-auth_address = auth123@example.com
+auth_version = 2
+auth_address = http://localhost:5000/v2.0
 
 [ref2]
-user = user2
+user = project_name:user_name2
 key = key2
-auth_address = http://auth345@example.com
+user_domain_id = default
+project_domain_id = default
+auth_version = 3
+auth_address = http://localhost:5000/v3