Browse Source

Merge "Add a full listing of all auth plugins and there options"

Jenkins 2 years ago
parent
commit
06e0aeb8f1

+ 0
- 0
doc/ext/__init__.py View File


+ 93
- 0
doc/ext/list_plugins.py View File

@@ -0,0 +1,93 @@
1
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
2
+# not use this file except in compliance with the License. You may obtain
3
+# a copy of the License at
4
+#
5
+#      http://www.apache.org/licenses/LICENSE-2.0
6
+#
7
+# Unless required by applicable law or agreed to in writing, software
8
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
9
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
10
+# License for the specific language governing permissions and limitations
11
+# under the License.
12
+
13
+import inspect
14
+
15
+from docutils import nodes
16
+from docutils.parsers import rst
17
+from docutils.parsers.rst import directives
18
+from docutils.statemachine import ViewList
19
+from sphinx.util.nodes import nested_parse_with_titles
20
+
21
+from stevedore import extension
22
+
23
+
24
+class ListAuthPluginsDirective(rst.Directive):
25
+    """Present a simple list of the plugins in a namespace."""
26
+
27
+    option_spec = {
28
+        'class': directives.class_option,
29
+        'overline-style': directives.single_char_or_unicode,
30
+        'underline-style': directives.single_char_or_unicode,
31
+    }
32
+
33
+    has_content = True
34
+
35
+    @property
36
+    def app(self):
37
+        return self.state.document.settings.env.app
38
+
39
+    def report_load_failure(mgr, ep, err):
40
+        self.app.warn(u'Failed to load %s: %s' % (ep.module_name, err))
41
+
42
+    def display_plugin(self, ext):
43
+        overline_style = self.options.get('overline-style', '')
44
+        underline_style = self.options.get('underline-style', '=')
45
+
46
+        if overline_style:
47
+            yield overline_style * len(ext.name)
48
+
49
+        yield ext.name
50
+
51
+        if underline_style:
52
+            yield underline_style * len(ext.name)
53
+
54
+        yield "\n"
55
+
56
+        doc = inspect.getdoc(ext.obj)
57
+        if doc:
58
+            yield doc
59
+            yield "\n"
60
+            yield "------"
61
+
62
+        yield "\n"
63
+
64
+        for opt in ext.obj.get_options():
65
+            yield ":%s: %s" % (opt.name, opt.help)
66
+
67
+        yield "\n"
68
+
69
+    def run(self):
70
+        mgr = extension.ExtensionManager(
71
+            'keystoneauth1.plugin',
72
+            on_load_failure_callback=self.report_load_failure,
73
+	    invoke_on_load=True,
74
+        )
75
+
76
+        result = ViewList()
77
+
78
+        for name in sorted(mgr.names()):
79
+            for line in self.display_plugin(mgr[name]):
80
+                for l in line.splitlines():
81
+                    result.append(l, mgr[name].entry_point.module_name)
82
+
83
+        # Parse what we have into a new section.
84
+        node = nodes.section()
85
+        node.document = self.state.document
86
+        nested_parse_with_titles(self.state, result, node)
87
+
88
+        return node.children
89
+
90
+
91
+def setup(app):
92
+    app.info('loading keystoneauth1 plugins')
93
+    app.add_directive('list-auth-plugins', ListAuthPluginsDirective)

+ 3
- 0
doc/source/conf.py View File

@@ -24,6 +24,8 @@ import pbr.version
24 24
 
25 25
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
26 26
                 '..', '..')))
27
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
28
+                '..')))
27 29
 
28 30
 # If extensions (or modules to document with autodoc) are in another directory,
29 31
 # add these directories to sys.path here. If the directory is relative to the
@@ -40,6 +42,7 @@ extensions = ['sphinx.ext.autodoc',
40 42
               'sphinx.ext.coverage',
41 43
               'sphinx.ext.intersphinx',
42 44
               'oslosphinx',
45
+              'ext.list_plugins',
43 46
              ]
44 47
 
45 48
 todo_include_todos = True

+ 1
- 0
doc/source/index.rst View File

@@ -13,6 +13,7 @@ Contents:
13 13
 
14 14
    using-sessions
15 15
    authentication-plugins
16
+   plugin-options
16 17
 
17 18
    extras
18 19
    migrating

+ 92
- 0
doc/source/plugin-options.rst View File

@@ -0,0 +1,92 @@
1
+==============
2
+Plugin Options
3
+==============
4
+
5
+Using plugins via config file
6
+-----------------------------
7
+
8
+When using the plugins via config file you define the plugin name as
9
+``auth_type``. The options of the plugin are then specified while replacing
10
+``-`` with ``_`` to be valid in configuration.
11
+
12
+For example to use the password_ plugin in a config file you would specify:
13
+
14
+.. code-block:: ini
15
+
16
+    [section]
17
+    auth_url = http://keystone.example.com:5000/
18
+    auth_type = password
19
+    username = myuser
20
+    password = mypassword
21
+    project_name = myproject
22
+    default_domain_name = mydomain
23
+
24
+
25
+Using plugins via CLI
26
+---------------------
27
+
28
+When using auth plugins via CLI via ``os-client-config`` or ``shade`` you can
29
+specify parameters via environment configuration by using the pattern ``OS_``
30
+followed by the uppercase parameter name replacing ``-`` with ``_``.
31
+
32
+For example to use the password_ plugin via environment variable you specify:
33
+
34
+.. code-block:: bash
35
+
36
+    export OS_AUTH_TYPE=password
37
+    export OS_AUTH_URL=http://keystone.example.com:5000/
38
+    export OS_USERNAME=myuser
39
+    export OS_PASSWORD=mypassword
40
+    export OS_PROJECT_NAME=myproject
41
+    export OS_DEFAULT_DOMAIN_NAME=mydomain
42
+
43
+Specifying operations via CLI parameter will override the environment
44
+parameter. These are specified with the pattern ``--os-`` and the parameter
45
+name. Using the password_ example again:
46
+
47
+.. code-block:: bash
48
+
49
+    openstack --os-auth-type password \
50
+              --os-auth-url http://keystone.example.com:5000/ \
51
+              --os-username myuser \
52
+              --os-password mypassword \
53
+              --os-project-name myproject \
54
+              --os-default-domain-name mydomain \
55
+              operation
56
+
57
+Additional loaders
58
+------------------
59
+
60
+The configuration and CLI loaders are quite commonly used however similar
61
+concepts are found in other situations such as ``os-client-config`` in which
62
+you specify authentication and other cloud parameters in a ``clouds.yaml``
63
+file.
64
+
65
+Loaders such as these use the same plugin options listed below, but via their
66
+own mechanism. In ``os-client-config`` the password_ plugin looks like:
67
+
68
+.. code-block:: yaml
69
+
70
+    clouds:
71
+      mycloud:
72
+        auth_type: password
73
+        auth:
74
+          auth_url: http://keystone.example.com:5000/
75
+          auth_type: password
76
+          username: myuser
77
+          password: mypassword
78
+          project_name: myproject
79
+          default_domain_name: mydomain
80
+
81
+However different services may implement loaders in their own way and you
82
+should consult their relevant documentation. The same auth options will be
83
+available.
84
+
85
+
86
+Available Plugins
87
+-----------------
88
+
89
+This is a listing of all included plugins and the options that they accept.
90
+Plugins are listed alphabetically and not in any order of priority.
91
+
92
+.. list-auth-plugins::

+ 11
- 0
keystoneauth1/loading/_plugins/admin_token.py View File

@@ -15,6 +15,17 @@ from keystoneauth1 import token_endpoint
15 15
 
16 16
 
17 17
 class AdminToken(loading.BaseLoader):
18
+    """Use an existing token and a known endpoint to perform requests.
19
+
20
+    This plugin is primarily useful for development or for use with identity
21
+    service ADMIN tokens. Because this token is used directly there is no
22
+    fetching a service catalog or determining scope information and so it
23
+    cannot be used by clients that expect use this scope information.
24
+
25
+    Because there is no service catalog the endpoint that is supplied with
26
+    initialization is used for all operations performed with this plugin so
27
+    must be the full base URL to an actual service.
28
+    """
18 29
 
19 30
     @property
20 31
     def plugin_class(self):

+ 21
- 0
keystoneauth1/loading/_plugins/identity/generic.py View File

@@ -15,6 +15,18 @@ from keystoneauth1 import loading
15 15
 
16 16
 
17 17
 class Token(loading.BaseGenericLoader):
18
+    """Given an existing token rescope it to another target.
19
+
20
+    This plugin uses the Identity service's rescope mechanism to get a new
21
+    token based upon an existing token. Because an auth plugin requires a
22
+    service catalog and scope information it is often easier to fetch a new
23
+    token based on an existing one than validate and reuse the one you already
24
+    have.
25
+
26
+    As a generic plugin this plugin is identity version independent and will
27
+    discover available versions before use. This means it expects to be
28
+    providen an unversioned URL to operate against.
29
+    """
18 30
 
19 31
     @property
20 32
     def plugin_class(self):
@@ -32,6 +44,15 @@ class Token(loading.BaseGenericLoader):
32 44
 
33 45
 
34 46
 class Password(loading.BaseGenericLoader):
47
+    """Authenticate via a username and password.
48
+
49
+    Authenticate to the identity service using an inbuilt username and
50
+    password. This is the standard and most common form of authentication.
51
+
52
+    As a generic plugin this plugin is identity version independent and will
53
+    discover available versions before use. This means it expects to be
54
+    providen an unversioned URL to operate against.
55
+    """
35 56
 
36 57
     @property
37 58
     def plugin_class(self):

Loading…
Cancel
Save