README update
Change-Id: I47681e5d65bb2a0767eaf7e4dfc609fee30897f3
diff --git a/README.rst b/README.rst
index 2f82d11..bc98bf2 100644
--- a/README.rst
+++ b/README.rst
@@ -1,6 +1,6 @@
-==================
-OpenStack Keystone
-==================
+=====
+Usage
+=====
Keystone provides authentication, authorization and service discovery
mechanisms via HTTP primarily for use by projects in the OpenStack family. It
@@ -11,12 +11,11 @@
.. code-block:: bash
- +----------------------------------+-----------+--------------------------+--------------------------+---------------------------+----------------------------------+
- | id | region | publicurl | internalurl | adminurl | service_id |
- +----------------------------------+-----------+--------------------------+--------------------------+---------------------------+----------------------------------+
- | 91663a8db11c487c9253c8c456863494 | RegionOne | http://10.0.150.37:5000/ | http://10.0.150.37:5000/ | http://10.0.150.37:35357/ | 0fd2dba3153d45a1ba7f709cfc2d69c9 |
- +----------------------------------+-----------+--------------------------+--------------------------+---------------------------+----------------------------------+
-
+ +----------------+-----------+--------------------------+--------------------------+---------------------------+---------------+
+ | id | region | publicurl | internalurl | adminurl | service_id |
+ +----------------+-----------+--------------------------+--------------------------+---------------------------+---------------+
+ | 91663a8d...494 | RegionOne | http://10.0.150.37:5000/ | http://10.0.150.37:5000/ | http://10.0.150.37:35357/ | 0fd2dba...9c9 |
+ +----------------+-----------+--------------------------+--------------------------+---------------------------+---------------+
Sample pillars
==============
@@ -27,7 +26,7 @@
atabase:host), sqlalchemy will try to connect to /var/run/mysql/
mysqld.sock, may cause issues if you located your mysql socket elsewhere
-Full stacked keystone
+Full stacked Keystone:
.. code-block:: yaml
@@ -61,7 +60,7 @@
password: 'LfTno5mYdZmRfoPV'
user: 'keystone'
-Keystone public HTTPS API
+Keystone public HTTPS API:
.. code-block:: yaml
@@ -86,7 +85,10 @@
admin_address: 10.0.0.20
admin_port: 8774
-Keystone with custom policies. Keys with specified rules are created or set to this value if they already exists. Keys with no value (like our "existing_rule") are deleted from the policy file.
+Keystone with custom policies. Keys with specified rules
+are created or set to this value if they already exists.
+Keys with no value (like our ``existing_rule``) are deleted
+from the policy file:
.. code-block:: yaml
@@ -97,7 +99,7 @@
new_rule: "rule:admin_required"
existing_rule:
-Keystone memcached storage for tokens
+Keystone memcached storage for tokens:
.. code-block:: yaml
@@ -114,7 +116,7 @@
services:
...
-Keystone clustered memcached storage for tokens
+Keystone clustered memcached storage for tokens:
.. code-block:: yaml
@@ -134,7 +136,7 @@
services:
...
-Keystone client
+Keystone client:
.. code-block:: yaml
@@ -169,7 +171,7 @@
name: admin
password: password
-Keystone fernet tokens for OpenStack Kilo release
+Keystone fernet tokens for OpenStack Kilo release:
.. code-block:: yaml
@@ -181,7 +183,7 @@
max_active_keys: 3
...
-Keystone auth methods
+Keystone auth methods:
.. code-block:: yaml
@@ -195,7 +197,8 @@
- oauth1
...
-Keystone domain with LDAP backend, using SQL for role/project assignment
+Keystone domain with LDAP backend, using SQL for
+role/project assignment:
.. code-block:: yaml
@@ -214,7 +217,7 @@
uid: keystone
password: password
-Use driver aliases for drivers instead of class path's
+Use driver aliases for drivers instead of class path's:
.. code-block:: yaml
@@ -234,7 +237,7 @@
url: "ldaps://idm.domain.com"
...
-Using LDAP backend for default domain
+Using LDAP backend for default domain:
.. code-block:: yaml
@@ -250,7 +253,8 @@
uid: keystone
password: password
-Using LDAP backend for default domain with "user_enabled" field emulation
+Using LDAP backend for default domain with
+``user_enabled`` field emulation:
.. code-block:: yaml
@@ -272,7 +276,10 @@
user_enabled_emulation_dn: "cn=os-user-enabled,ou=Openstack,o=domain.com"
user_enabled_emulation_use_group_config: True
-If the members of the group objectclass are user IDs rather than DNs, set group_members_are_ids to true. This is the case when using posixGroup as the group objectclass and OpenDirectory.
+If the members of the group ``objectclass`` are user IDs
+rather than DNs, set ``group_members_are_ids`` to ``true``.
+This is the case when using ``posixGroup` as the group
+``objectclass`` and ``OpenDirectory``:
.. code-block:: yaml
@@ -289,7 +296,7 @@
password: password
group_members_are_ids: True
-Simple service endpoint definition (defaults to RegionOne)
+Simple service endpoint definition (defaults to ``RegionOne``):
.. code-block:: yaml
@@ -305,7 +312,7 @@
bind:
...
-Region-aware service endpoints definition
+Region-aware service endpoints definition:
.. code-block:: yaml
@@ -330,7 +337,7 @@
bind:
...
-Enable ceilometer notifications
+Enable Ceilometer notifications:
.. code-block:: yaml
@@ -346,7 +353,7 @@
virtual_host: '/openstack'
ha_queues: true
-Client-side RabbitMQ HA setup
+Client-side RabbitMQ HA setup:
.. code-block:: yaml
@@ -368,7 +375,8 @@
|
-By default system-wide CA certs are used. Nothing should be specified except `ssl.enabled`.
+By default system-wide CA certs are used. Nothing should be
+specified except ``ssl.enabled``.
.. code-block:: yaml
@@ -379,7 +387,8 @@
ssl:
enabled: True
-Use `cacert_file` option to specify the CA-cert file path explicitly:
+Use ``cacert_file`` option to specify the CA-cert
+file path explicitly:
.. code-block:: yaml
@@ -391,7 +400,8 @@
enabled: True
cacert_file: /etc/ssl/rabbitmq-ca.pem
-To manage content of the `cacert_file` use the `cacert` option:
+To manage content of the ``cacert_file`` use the ``cacert``
+option:
.. code-block:: yaml
@@ -409,12 +419,15 @@
cacert_file: /etc/openstack/rabbitmq-ca.pem
+.. note::
-Notice:
- * The `message_queue.port` is set to **5671** (AMQPS) by default if `ssl.enabled=True`.
- * Use `message_queue.ssl.version` if you need to specify protocol version. By default is TLSv1 for python < 2.7.9 and TLSv1_2 for version above.
+ * The ``message_queue.port`` is set to ``5671`` (AMQPS) by
+ default if ``ssl.enabled=True``.
+ * Use ``message_queue.ssl.version`` if you need to specify
+ protocol version. By default, is ``TLSv1`` for python <
+ 2.7.9 and ``TLSv1_2`` for version above.
-Enable CADF audit notification
+Enable CADF audit notification:
.. code-block:: yaml
@@ -423,7 +436,7 @@
notification: true
notification_format: cadf
-Run keystone under Apache
+Run Keystone under Apache:
.. code-block:: yaml
@@ -444,7 +457,7 @@
modules:
- wsgi
-Enable SAML2 Federated keystone
+Enable SAML2 Federated keystone:
.. code-block:: yaml
@@ -473,7 +486,7 @@
- wsgi
- shib2
-Enable OIDC Federated keystone
+Enable OIDC Federated Keystone:
.. code-block:: yaml
@@ -513,9 +526,11 @@
- wsgi
- auth_openidc
-Notes: Ubuntu Trusty repository doesn't contain libapache2-mod-auth-openidc package. Additonal repository should be added to source list.
+.. note:: Ubuntu Trusty repository doesn't contain
+ ``libapache2-mod-auth-openidc`` package. Additonal
+ repository should be added to the source list.
-Use a custom identity driver with custom options
+Use a custom identity driver with custom options:
.. code-block:: yaml
@@ -533,7 +548,7 @@
caching: true
cache_time: 600
-Enable CORS parameters
+Enable CORS parameters:
.. code-block:: yaml
@@ -547,12 +562,10 @@
allow_credentials: True
max_age: 86400
-
-
Keystone client
---------------
-Service endpoints enforcement with service token
+Service endpoints enforcement with service token:
.. code-block:: yaml
@@ -581,7 +594,7 @@
admin_port: 8773
admin_path: '/v2'
-Project, users, roles enforcement with admin user
+Project, users, roles enforcement with admin user:
.. code-block:: yaml
@@ -630,7 +643,7 @@
roles:
- custom-roles
-Multiple servers example
+Multiple servers example:
.. code-block:: yaml
@@ -656,8 +669,7 @@
password: 'workshop'
region_name: RegionOne
-
-Tenant quotas
+Tenant quotas:
.. code-block:: yaml
@@ -696,7 +708,8 @@
server_groups: 20
server_group_members: 20
-Extra config params in keystone.conf (since Mitaka release)
+Extra config params in ``keystone.conf``
+(since Mitaka release):
.. code-block:: yaml
@@ -712,18 +725,17 @@
param2: value
....
-Configuration of policy.json file
+Configuration of ``policy.json`` file:
.. code-block:: yaml
-
keystone:
server:
....
policy:
admin_or_token_subject: 'rule:admin_required or rule:token_subject'
-Manage os-cloud-config yml with keystone.client
+Manage ``os-cloud-config`` yml with ``keystone.client``:
.. code-block:: yaml
@@ -746,11 +758,10 @@
project_domain_name: Default
auth_url: "http://1.2.3.4:5000"
-Setting up default admin project name and domain
+Setting up default admin project name and domain:
.. code-block:: yaml
-
keystone:
server:
....
@@ -764,13 +775,20 @@
By default logging.conf is disabled.
That is possible to enable per-binary logging.conf with new variables:
- * openstack_log_appender - set it to true to enable log_config_append for all OpenStack services;
- * openstack_fluentd_handler_enabled - set to true to enable FluentHandler for all Openstack services.
- * openstack_ossyslog_handler_enabled - set to true to enable OSSysLogHandler for all Openstack services.
-Only WatchedFileHandler, OSSysLogHandler and FluentHandler are available.
+* ``openstack_log_appender``
+ Set to true to enable ``log_config_append`` for all OpenStack services
-Also it is possible to configure this with pillar:
+* ``openstack_fluentd_handler_enabled``
+ Set to true to enable ``FluentHandler`` for all Openstack services
+
+* ``openstack_ossyslog_handler_enabled``
+ Set to true to enable ``OSSysLogHandler`` for all Openstack services
+
+Only ``WatchedFileHandler``, ``OSSysLogHandler``, and ``FluentHandler``
+are available.
+
+Also, it is possible to configure this with pillar:
.. code-block:: yaml
@@ -789,7 +807,8 @@
Usage
=====
-Apply state `keystone.client.service` first and then `keystone.client` state.
+#. Apply the :command:`keystone.client.service` state.
+#. Apply the :command:`keystone.client` state.
Documentation and Bugs
@@ -821,32 +840,26 @@
Documentation and Bugs
======================
-To learn how to install and update salt-formulas, consult the documentation
-available online at:
+* http://salt-formulas.readthedocs.io/
+ Learn how to install and update salt-formulas
- http://salt-formulas.readthedocs.io/
+* https://github.com/salt-formulas/salt-formula-keystone/issues
+ In the unfortunate event that bugs are discovered, report the issue to the
+ appropriate issue tracker. Use the Github issue tracker for a specific salt
+ formula
-In the unfortunate event that bugs are discovered, they should be reported to
-the appropriate issue tracker. Use Github issue tracker for specific salt
-formula:
+* https://launchpad.net/salt-formulas
+ For feature requests, bug reports, or blueprints affecting the entire
+ ecosystem, use the Launchpad salt-formulas project
- https://github.com/salt-formulas/salt-formula-keystone/issues
+* https://launchpad.net/~salt-formulas-users
+ Join the salt-formulas-users team and subscribe to mailing list if required
-For feature requests, bug reports or blueprints affecting entire ecosystem,
-use Launchpad salt-formulas project:
+* https://github.com/salt-formulas/salt-formula-keystone
+ Develop the salt-formulas projects in the master branch and then submit pull
+ requests against a specific formula
- https://launchpad.net/salt-formulas
+* #salt-formulas @ irc.freenode.net
+ Use this IRC channel in case of any questions or feedback which is always
+ welcome
-You can also join salt-formulas-users team and subscribe to mailing list:
-
- https://launchpad.net/~salt-formulas-users
-
-Developers wishing to work on the salt-formulas projects should always base
-their work on master branch and submit pull request against specific formula.
-
- https://github.com/salt-formulas/salt-formula-keystone
-
-Any questions or feedback is always welcome so feel free to join our IRC
-channel:
-
- #salt-formulas @ irc.freenode.net