Add performance tuning documentation

Change-Id: Ia6ab8fbc0fa5c8f055ef0e913c32e4b285a2a6e2

doc/source/index.rst

@@ -49,6 +49,7 @@ Getting Started
 
     installing
     configuration
+    performance
     apache-httpd
     policy_mapping
     configuringservices

doc/source/performance.rst

@@ -0,0 +1,102 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+=======================
+Performance and scaling
+=======================
+
+Before you begin tuning Keystone for performance and scalability, you should
+first know that Keystone is just a two tier horizontally-scalable web
+application, and the most effective methods for scaling it are going to be the
+same as for any other similarly designed web application: give it more
+processes, more memory, scale horizontally, and load balance the result.
+
+With that said, there are many opportunities for tuning the performance of
+Keystone, many of which are actually trade-offs between performance and
+security that you need to judge for yourself, and tune accordingly.
+
+``keystone-manage token_flush``
+===============================
+
+If you're using a token provider that requires persistence (such as UUID, PKI,
+or PKIZ, but not Fernet), then you **MUST** periodically run ``keystone-manage
+token_flush`` to purge the database of expired tokens. If you don't, then your
+SQL server will eventually become bloated and performance will suffer.
+
+``keystone.conf``
+=================
+
+These are all of the options in ``keystone.conf`` that have a direct impact on
+performance. See the help descriptions for these options for more specific
+details on how and why you might want to tune these options for yourself.
+
+* ``[DEFAULT] crypt_strength``: Reduce this number to increase performance,
+  increase this number to make SQL managed password checking more secure.
+
+* ``[DEFAULT] max_project_tree_depth``: Reduce this number to increase
+  performance, increase this number to cater to more complicated hierarchical
+  multitenancy use cases.
+
+* ``[DEFAULT] max_password_length``: Reduce this number to increase
+  performance, increase this number to allow for more secure passwords.
+
+* ``[cache] enable``: Enable this option to increase performance, but you also
+  need to configure other options in the ``[cache]`` section to actually
+  utilize caching.
+
+* ``[token] provider``: All of our token provider options have been primarily
+  driven by performance considerations. UUID and Fernet both require online
+  validation (cacheable HTTP calls back to keystone to validate tokens),
+  whereas PKI can be validated in a distributed fashion. Fernet has the highest
+  scalability characteristics overall, but requires more work to validate, and
+  therefore enabling caching (``[cache] enable``) is absolutely critical.
+
+* ``[fernet] max_active_keys``: If you're using Fernet tokens, decrease this
+  option to improve performance, increase this option to support more advanced
+  key rotation strategies.
+
+``keystonemiddleware.auth_token``
+=================================
+
+This configuration actually lives in the Paste pipelines of services consuming
+token validation from keystone (i.e.: nova, ciner, swift, etc.).
+
+* ``cache``: When keystone's `auth_token` middleware is deployed with a
+  swift cache, use this option to have `auth_token` middleware share a caching
+  backend with swift. Otherwise, use the ``memcached_servers`` option instead.
+
+* ``memcached_servers``: Set this option to share a cache across
+  ``keystonemiddleware.auth_token`` processes.
+
+* ``token_cache_time``: Increase this option to improve performance, decrease
+  this option to respond to token revocation events more quickly (thereby
+  increasing security).
+
+* ``revocation_cache_time``: Increase this option to improve performance,
+  decrease this option to respond to token revocation events more quickly
+  (thereby increasing security).
+
+* ``memcache_security_strategy``: Do not set this option to improve
+  performance, but set it to improve security where you're sharing memcached
+  with other processes.
+
+* ``include_service_catalog``: Disable this option to improve performance, if
+  the protected service does not require a service catalog.
+
+* ``check_revocations_for_cached``: Leave this option disabled to improve
+  performance, but enable it if you're using PKI tokens.
+
+* ``hash_algorithms``: If you're using PKI tokens, then use a high performance
+  hash algorithm to improve performance, or choose a more rigorous hash
+  algorithm to improve security. This option is ignored for other token
+  formats.