From 957f3feee8b8b0a828dbf56252c19aa79a51cde9 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Wed, 25 Apr 2018 20:32:10 +0000 Subject: [PATCH] Update documentation to include usage for new projects The oslo.policy bits to generate documentation and use the oslo.policy CLI scripts is usually copy/pasted from other services that have already done that work. This commit attempts to pull that information into the usage section of oslo.policy, complete with examples, instead of making OpenStack developers hunt through projects to find examples they can use. Or wonder why or how this tooling works. Change-Id: Ie74888b09bb836c192a88c5beddd86297c8bceda Closes-Bug: 1766953 --- doc/source/user/usage.rst | 71 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index f288128f..3c22107d 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -14,6 +14,77 @@ Applications using the incubated version of the policy code from Oslo aside from changing the way the library is imported, may need to make some extra changes. +Incorporating oslo.policy tooling +--------------------------------- + +The ``oslo.policy`` library offers a generator that projects can use to render +sample policy files, check for redundant rules or policies, among other things. +This is a useful tool not only for operators managing policies, but also +developers looking to automate documentation describing the projects default +policies. + +This part of the document describes how you can incorporate these features into +your project. Let's assume we're working on an OpenStack-like project called +``foo``. Policies for this service are registered in code in a common module of +the project. + +First, you'll need to expose a couple of entry points in the project's +``setup.cfg``:: + + [entry_points] + oslo.policy.policies = + foo = foo.common.policies:list_rules + + oslo.policy.enforcer = + foo = foo.common.policy:get_enforcer + +The ``oslo.policy`` library uses the project namespace to call ``list_rules``, +which should return a list of ``oslo.policy`` objects, either instances of +``RuleDefault`` or ``DocumentedRuleDefault``. + +The second entry point allows ``oslo.policy`` to generate complete policy from +overrides supplied by an existing policy file on disk. This is useful for +operators looking to supply a policy file to Horizon or for security compliance +complete with overrides important to that deployment. The ``get_enforcer`` +method should return an instance of ``oslo.policy.policy:Enforcer``. The +information passed into the constructor of ``Enforcer`` should resolve any +overrides on disk. An example for project ``foo`` might look like the +following:: + + from oslo_config import cfg + from oslo_policy import policy + + from foo.common import policies + + CONF = cfg.CONF + _ENFORCER = None + + def get_enforcer(): + CONF([], project='foo') + global _ENFORCER + if not _ENFORCER: + _ENFORCER = policy.Enforcer(CONF) + _ENFORCER.register_defaults(policies.list_rules()) + return _ENFORCER + +Please note that if you're incorporating this into a project that already uses +``oslo.policy`` in some form or fashion, this might need to be changed to fit +that project's structure accordingly. + +Next, you can create a configuration file for generating policies specifically +for project ``foo``. This file could be called ``foo-policy-generator.conf`` +and it can be kept under version control within the project:: + + [DEFAULT] + output_file = etc/foo/policy.yaml.sample + namespace = foo + +If project ``foo`` uses tox, this makes it easier to create a specific tox +environment for generating sample configuration files in ``tox.ini``:: + + [testenv:genpolicy] + commands = oslopolicy-sample-generator --config-file etc/foo/policy.yaml.sample + Changes to Enforcer Initialization ----------------------------------