No documentation about token backends

[Rafael Durán Castañeda]

Documentation lacks of information about token backends: backends available, options, memcached configuration for memcached backend,...

[Dolph Mathews (dolph)]

Definitely a weak point in the docs, given that we default to KVS.

[Anne Gentle (annegentle)]

Dolph, do you intend to document both places? Seems like openstack-manuals is where that type of info belongs. You can move it over if you want.

[Dolph Mathews (dolph)]

Definitely makes more sense in openstack-manuals than in keystone's dev docs-- although there's a LOT of things in the dev docs that belong in openstack-manuals :(

[Lorin Hochstein (lorinh)]

Here's some IBM docs about configuring for memcache backend with uuid: http://pic.dhe.ibm.com/infocenter/tivihelp/v48r1/index.jsp?topic=%2Fcom.ibm.sco.doc_2.2%2Ft_memcached_keystone.html

[Lorin Hochstein (lorinh)]

Note that people have been having with their database filling up with tokens, which results in poor MySQL performance:

http://lists.openstack.org/pipermail/openstack-dev/2013-June/010279.html
http://lists.openstack.org/pipermail/openstack-dev/2013-July/011337.html
https://bugs.launchpad.net/nova-project/+bug/1191159

Jay Pipes suggested using the memcache token driver to avoid this problem:

http://lists.openstack.org/pipermail/openstack-dev/2013-June/010289.html

We really should document how to do at least this kind of token backend change to help folks work around this issue.

[Dolph Mathews (dolph)]

@Lorin: as of havana milestone 1, the following command is available to help alleviate the issue you described:

  $ keystone-manage token_flush

[Lorin Hochstein (lorinh)]

@dolph: I think it would help if we could provide operators with some guidance on how often they should call token_flush. (e.g., how often it should run in a cron job). Assuming there's no auditing requirement to keep the tokens around, what's a reasonable interval for flushing the tokens? (e.g., once a week? once a day? every hour? every five minutes?)

[Dolph Mathews (dolph)]

@Lorin: there's been some discussion around that on the openstack-dev list:

  http://lists.openstack.org/pipermail/openstack-dev/2013-July/011167.html

[Dolph Mathews (dolph)]

An update on this topic -- we're considering KVS as a deprecated backend, and are now defaulting to SQL. So, I'd prefer if the KVS driver wasn't documented at all. We're also on our way to being able to use memcache (or any other caching layer) on top of the actual token backend [1], so it may make sense to deprecate the memcache token driver in the near future as well. In that case, we'll only have the SQL token driver.

[1]: https://blueprints.launchpad.net/keystone/+spec/caching-layer-for-driver-calls

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/44181

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/44181
Committed: http://github.com/openstack/keystone/commit/ceb017071d3941de5aa9931c5a81aaf17a4797e4
Submitter: Jenkins
Branch: master

commit ceb017071d3941de5aa9931c5a81aaf17a4797e4
Author: David Stanek <email address hidden>
Date: Wed Aug 28 19:45:07 2013 -0400

    Removes KVS references from the documentation

    KVS backends are deprecated and removing references to them from the
    documentation will discourage their use.

    Change-Id: Iad2f9c39f9d92465ada5ecb6001cfc2b225cc01f
    Related-Bug: #986980

[Nermina Miller (nerminamiller)]

Can this bug be closed? It seems like it was at least partially fixed. I see that SQL driver has been documented in Configuration Reference.

[Dolph Mathews (dolph)]

AFAIK, the memcache token driver is not documented anywhere (not even keystone.sample.conf), so I think this bug is still valid for both keystone and openstack-manuals.

Using memcache/redis as a caching layer on top of the token driver is now supported and documented fairly well on the keystone side, but we haven't gone so far as deprecate the memcache token driver yet.

[Tom Fifield (fifieldt)]

Also need to add docs about dogpile.

[Felipe Alfaro Solana (felipe-alfaro-gmail)]

Is there any place where the decision to deprecate the memcache token backend can be discussed? In my opinion, the semantics of memcache are better than those of MySQL for short-lived tokens.

[Tom Fifield (fifieldt)]

Certainly Felipe - please ask in #openstack-keystone in freenode IRC, or post on the development mailing list: https://wiki.openstack.org/wiki/MailingLists

[Dolph Mathews (dolph)]

@Felipe: you'll find relevant conversations around the following blueprints:

Superseding the memcache token backend with dogpile as a generic interface to KVS backends: https://blueprints.launchpad.net/keystone/+spec/dogpile-kvs-backends

Dropping the requirement for PKI token persistence entirely: https://blueprints.launchpad.net/keystone/+spec/non-persistent-tokens

[Bernd Bausch (berndbausch)]

Is this bug still alive? Both token persistence backends and the caching layer are documented at http://docs.openstack.org/developer/keystone/configuration.html. Should the text be copied to the config reference, or a link place there?

[Lauren (laucon)]

Hey there. I'm looking for a bug to fix as a part of the outreachy internship application process. Does this issue still exist? Does the token end documentation need cleaning up?

[Lance Bragstad (lbragstad)]

I have a couple patches proposed to openstack manuals that attempt to document tokens [0] [1]. This documentation pertains to the token *providers* (e.g. uuid, fernet, pki, and pkiz) rather than the backends (e.g. mysql, kvs). I can leverage those patches to try and close this, too. Thoughts?

[0] https://review.openstack.org/#/c/244871/
[1] https://review.openstack.org/#/c/244693/

[Steve Martinelli (stevemar)]

hey lauren, the developer docs could use some cleaning up: http://docs.openstack.org/developer/keystone/configuration.html#token-provider

[Steve Martinelli (stevemar)]

I'm going to say that Dolph's token matrix closed out this bug: https://review.openstack.org/#/c/316118/