Package list python-castellan / 54b1b52
rearrange existing documentation to fit the new standard layout README.rst was updated as the title of the doc top page was wrong. Change-Id: I3821bdaa78a982c0a08fef584aec62a5549d5b8b Akihiro Motoki 4 years ago
12 changed file(s) with 479 addition(s) and 476 deletion(s). Raw diff Collapse all Expand all
0 ========================
1 Team and repository tags
2 ========================
3
4 .. image:: https://governance.openstack.org/badges/castellan.svg
5 :target: https://governance.openstack.org/reference/tags/index.html
6
7 .. Change things from this point on
8
90 =========
101 Castellan
112 =========
167 * Documentation: https://docs.openstack.org/developer/castellan
178 * Source: https://git.openstack.org/cgit/openstack/castellan
189 * Bugs: https://bugs.launchpad.net/castellan
10
11 Team and repository tags
12 ========================
13
14 .. image:: https://governance.openstack.org/badges/castellan.svg
15 :target: https://governance.openstack.org/reference/tags/index.html
+0
-1
doc/source/contributing.rst less more
0 .. include:: ../../CONTRIBUTING.rst
0 .. include:: ../../../CONTRIBUTING.rst
0 ====================
1 Contributor Document
2 ====================
3
4 .. toctree::
5 :maxdepth: 2
6
7 contributing
8 testing
0 =======
1 Testing
2 =======
3
4 Every Castellan code submission is automatically tested against a number
5 of gating jobs to prevent regressions. Castellan developers should have a
6 habit of running tests locally to ensure the code works as intended before
7 submission.
8
9 For your convenience we provide the ability to run all tests through
10 the ``tox`` utility. If you are unfamiliar with tox please see
11 refer to the `tox documentation`_ for assistance.
12
13 .. _`tox documentation`: https://tox.readthedocs.org/en/latest/
14
15 Unit Tests
16 ----------
17
18 Currently, we provide tox environments for a variety of different Python
19 versions. By default all available test environments within the tox
20 configuration will execute when calling ``tox``. If you want to run an
21 independent version, you can do so with the following command:
22
23 .. code-block:: bash
24
25 # Executes tests on Python 2.7
26 $ tox -e py27
27
28
29 .. note::
30
31 Other available environments are py35, pypy and pep8.
32
33 If you do not have the appropriate Python versions available, consider
34 setting up PyEnv to install multiple versions of Python. See the
35 documentation regarding `Setting up a Barbican development environment`_
36 for more information.
37
38 Functional Tests
39 ----------------
40
41 Unlike running unit tests, the functional tests require Barbican and
42 Keystone services to be running in order to execute. For more
43 information on this please see `Setting up a Barbican development environment`_
44 and `Using Keystone Middleware with Barbican`_
45
46 .. _`Setting up a Barbican development environment`: https://docs.openstack.org/developer/barbican/setup/dev.html
47 .. _`Using Keystone Middleware with Barbican`: https://docs.openstack.org/developer/barbican/setup/keystone.html
48
49 Castellan uses either ``/etc/castellan/castellan-functional.conf`` or ``./etc/castellan/castellan-functional.conf``
50 in order to run functional tests. A sample file can be generated by running:
51
52 .. code-block:: bash
53
54 # Generate a sample configuration file
55 $ tox -e genconfig
56
57 ``castellan/etc/castellan/castellan-functional.conf.sample`` is generated.
58 It must be renamed to ``castellan-functional.conf`` and placed in
59 ``/etc/castellan`` or ``./etc/castellan``.
60
61 The file should look something like the following:
62
63 .. code-block:: bash
64
65 [DEFAULT]
66
67 [identity]
68 username = 'admin'
69 password = 'openstack'
70 project_name = 'admin'
71 auth_url = 'http://localhost/identity/v3'
72
73 Once you have the appropriate services running and configured you can execute
74 the functional tests through tox.
75
76 .. code-block:: bash
77
78 # Execute Barbican Functional Tests
79 $ tox -e functional
80
81
82 By default, the functional tox job will use ``testr`` to execute the
83 functional tests.
84
85 Debugging
86 ---------
87
88 In order to be able to debug code in Castellan, you must use the Python
89 Debugger. This can be done by adding ``import pdb; pdb.set_trace()``
90 to set the breakpoint. Then run the following command to hit the breakpoint:
91
92 .. code-block:: bash
93
94 # hit the pdb breakpoint
95 $ tox -e debug
96
97 Once in the Python Debugger, you can use the commands as stated in the
98 `Debugger Commands` section here: https://docs.python.org/2/library/pdb.html
99
100 Pep8 Check
101 ----------
102
103 Pep8 is a style guide for Python code. Castellan code should be have proper
104 style before submission. In order to ensure that pep8 tests can be run through
105 tox as follows:
106
107 .. code-block:: bash
108
109 # Checks python code style
110 $ tox -e pep8
111
112 Any comments on bad coding style will output to the terminal.
22 You can adapt this file completely to your liking, but it should at least
33 contain the root `toctree` directive.
44
5 Welcome to castellan's documentation!
6 ========================================================
5 .. include:: ../../README.rst
76
8 Contents:
7 Contents
8 ========
99
1010 .. toctree::
1111 :maxdepth: 2
1212
13 readme
14 installation
15 usage
16 testing
17 contributing
13 install/index
14 user/index
15 contributor/index
1816
1917 Indices and tables
2018 ==================
0 ============
1 Installation
2 ============
3
4 At the command line::
5
6 $ pip install castellan
7
8 Or, if you have virtualenvwrapper installed::
9
10 $ mkvirtualenv castellan
11 $ pip install castellan
+0
-12
doc/source/installation.rst less more
0 ============
1 Installation
2 ============
3
4 At the command line::
5
6 $ pip install castellan
7
8 Or, if you have virtualenvwrapper installed::
9
10 $ mkvirtualenv castellan
11 $ pip install castellan
+0
-1
doc/source/readme.rst less more
0 .. include:: ../../README.rst
+0
-113
doc/source/testing.rst less more
0 =======
1 Testing
2 =======
3
4 Every Castellan code submission is automatically tested against a number
5 of gating jobs to prevent regressions. Castellan developers should have a
6 habit of running tests locally to ensure the code works as intended before
7 submission.
8
9 For your convenience we provide the ability to run all tests through
10 the ``tox`` utility. If you are unfamiliar with tox please see
11 refer to the `tox documentation`_ for assistance.
12
13 .. _`tox documentation`: https://tox.readthedocs.org/en/latest/
14
15 Unit Tests
16 ----------
17
18 Currently, we provide tox environments for a variety of different Python
19 versions. By default all available test environments within the tox
20 configuration will execute when calling ``tox``. If you want to run an
21 independent version, you can do so with the following command:
22
23 .. code-block:: bash
24
25 # Executes tests on Python 2.7
26 $ tox -e py27
27
28
29 .. note::
30
31 Other available environments are py35, pypy and pep8.
32
33 If you do not have the appropriate Python versions available, consider
34 setting up PyEnv to install multiple versions of Python. See the
35 documentation regarding `Setting up a Barbican development environment`_
36 for more information.
37
38 Functional Tests
39 ----------------
40
41 Unlike running unit tests, the functional tests require Barbican and
42 Keystone services to be running in order to execute. For more
43 information on this please see `Setting up a Barbican development environment`_
44 and `Using Keystone Middleware with Barbican`_
45
46 .. _`Setting up a Barbican development environment`: https://docs.openstack.org/developer/barbican/setup/dev.html
47 .. _`Using Keystone Middleware with Barbican`: https://docs.openstack.org/developer/barbican/setup/keystone.html
48
49 Castellan uses either ``/etc/castellan/castellan-functional.conf`` or ``./etc/castellan/castellan-functional.conf``
50 in order to run functional tests. A sample file can be generated by running:
51
52 .. code-block:: bash
53
54 # Generate a sample configuration file
55 $ tox -e genconfig
56
57 ``castellan/etc/castellan/castellan-functional.conf.sample`` is generated.
58 It must be renamed to ``castellan-functional.conf`` and placed in
59 ``/etc/castellan`` or ``./etc/castellan``.
60
61 The file should look something like the following:
62
63 .. code-block:: bash
64
65 [DEFAULT]
66
67 [identity]
68 username = 'admin'
69 password = 'openstack'
70 project_name = 'admin'
71 auth_url = 'http://localhost/identity/v3'
72
73 Once you have the appropriate services running and configured you can execute
74 the functional tests through tox.
75
76 .. code-block:: bash
77
78 # Execute Barbican Functional Tests
79 $ tox -e functional
80
81
82 By default, the functional tox job will use ``testr`` to execute the
83 functional tests.
84
85 Debugging
86 ---------
87
88 In order to be able to debug code in Castellan, you must use the Python
89 Debugger. This can be done by adding ``import pdb; pdb.set_trace()``
90 to set the breakpoint. Then run the following command to hit the breakpoint:
91
92 .. code-block:: bash
93
94 # hit the pdb breakpoint
95 $ tox -e debug
96
97 Once in the Python Debugger, you can use the commands as stated in the
98 `Debugger Commands` section here: https://docs.python.org/2/library/pdb.html
99
100 Pep8 Check
101 ----------
102
103 Pep8 is a style guide for Python code. Castellan code should be have proper
104 style before submission. In order to ensure that pep8 tests can be run through
105 tox as follows:
106
107 .. code-block:: bash
108
109 # Checks python code style
110 $ tox -e pep8
111
112 Any comments on bad coding style will output to the terminal.
+0
-332
doc/source/usage.rst less more
0 =====
1 Usage
2 =====
3
4 This document describes some of the common usage patterns for Castellan. When
5 incorporating this package into your applications, care should be taken to
6 consider the key manager behavior you wish to encapsulate and the OpenStack
7 deployments on which your application will run.
8
9 Authentication
10 ~~~~~~~~~~~~~~
11
12 A fundamental concept to using Castellan is the credential context object.
13 Castellan supports the following credentials for authentication:
14
15 * Token
16 * Password
17 * Keystone Token
18 * Keystone Password
19
20 In order to use these credentials, valid configuration parameters must be
21 provided.
22
23 .. code:: ini
24
25 # token credential
26 # token variable not required, token can be obtained from context
27 [key_manager]
28 auth_type = 'token'
29 token = '5b4de0bb77064f289f7cc58e33bea8c7'
30
31 # password credential
32 [key_manager]
33 auth_type = 'password'
34 username = 'admin'
35 password = 'passw0rd1'
36
37 # keystone token credential
38 [key_manager]
39 auth_type = 'keystone_token'
40 token = '5b4de0bb77064f289f7cc58e33bea8c7'
41 project_id = 'a1e19934af81420d980a5d02b4afe9fb'
42
43 # keystone password credential
44 [key_manager]
45 auth_type = 'keystone_password'
46 username = 'admin'
47 password = 'passw0rd1'
48 project_id = '1099302ec608486f9879ba2466c60720'
49 user_domain_name = 'default'
50
51 .. note::
52
53 Keystone Token and Password authentication is achieved using
54 keystoneauth1.identity Token and Password auth plugins.
55 There are a variety of different variables which can be set for the
56 keystone credential options.
57
58
59 The configuration must be passed to a credential factory which will
60 generate the appropriate context.
61
62 .. code:: python
63
64 from castellan.common import utils
65
66 CONF = <your_configuration>
67 context = utils.credential_factory(conf=CONF, context=None)
68
69 Now you can go ahead and pass the context and use it for authentication.
70
71 .. note::
72
73 There is a special case for a token. Since a user may not want to store a
74 token in the configuration, the user can pass a context object containing
75 an 'auth_token' as well as a configuration file with 'token' as the
76 auth type.
77
78
79 An oslo context object can also be used for authentication, it is
80 frequently inherited from ``oslo.context.RequestContext``. This object
81 represents information that is contained in the current request, and is
82 usually populated in the WSGI pipeline. The information contained in this
83 object will be used by Castellan to interact with the specific key manager
84 that is being abstracted.
85
86 **Example. Creating RequestContext from Keystone Client**
87
88 .. code:: python
89
90 from keystoneauth1 import identity
91 from keystoneauth1 import session
92 from oslo_context import context
93
94 username = 'admin'
95 password = 'openstack'
96 project_name = 'admin'
97 auth_url = 'http://localhost/identity/v3'
98 auth = identity.Password(auth_url=auth_url,
99 username=username,
100 password=password,
101 project_name=project_name,
102 default_domain_id='default')
103 sess = session.Session()
104
105 ctxt = context.RequestContext(auth_token=auth.get_token(sess),
106 tenant=auth.get_project_id(sess))
107
108 ctxt can then be passed into any key_manager api call.
109
110
111 Basic usage
112 ~~~~~~~~~~~
113
114 Castellan works on the principle of providing an abstracted key manager based
115 on your configuration. In this manner, several different management services
116 can be supported through a single interface.
117
118 In addition to the key manager, Castellan also provides primitives for
119 various types of secrets (for example, asymmetric keys, simple passphrases,
120 and certificates). These primitives are used in conjunction with the key
121 manager to create, store, retrieve, and destroy managed secrets.
122
123 **Example. Creating and storing a key.**
124
125 .. code:: python
126
127 import myapp
128 from castellan.common.objects import passphrase
129 from castellan import key_manager
130
131 key = passphrase.Passphrase('super_secret_password')
132 manager = key_manager.API()
133 stored_key_id = manager.store(myapp.context(), key)
134
135 To begin with, we'd like to create a key to manage. We create a simple
136 passphrase key, then instantiate the key manager, and finally store it to
137 the manager service. We record the key identifier for later usage.
138
139 **Example. Retrieving a key and checking the contents.**
140
141 .. code:: python
142
143 import myapp
144 from castellan import key_manager
145
146 manager = key_manager.API()
147 key = manager.get(myapp.context(), stored_key_id)
148 if key.get_encoded() == 'super_secret_password':
149 myapp.do_secret_stuff()
150
151 This example demonstrates retrieving a stored key from the key manager service
152 and checking its contents. First we instantiate the key manager, then
153 retrieve the key using a previously stored identifier, and finally we check
154 the validity of key before performing our restricted actions.
155
156 **Example. Deleting a key.**
157
158 .. code:: python
159
160 import myapp
161 from castellan import key_manager
162
163 manager = key_manager.API()
164 manager.delete(myapp.context(), stored_key_id)
165
166 Having finished our work with the key, we can now delete it from the key
167 manager service. We once again instantiate a key manager, then we simply
168 delete the key by using its identifier. Under normal conditions, this call
169 will not return anything but may raise exceptions if there are communication,
170 identification, or authorization issues.
171
172 Configuring castellan
173 ~~~~~~~~~~~~~~~~~~~~~
174
175 Castellan contains several options which control the key management
176 service usage and the configuration of that service. It also contains
177 functions to help configure the defaults and produce listings for use
178 with the ``oslo-config-generator`` application.
179
180 In general, castellan configuration is handled by passing an
181 ``oslo_config.cfg.ConfigOpts`` object into the
182 ``castellan.key_manager.API`` call when creating your key manager. By
183 default, when no ``ConfigOpts`` object is provided, the key manager will
184 use the global ``oslo_config.cfg.CONF`` object.
185
186 **Example. Using the global CONF object for configuration.**
187
188 .. code:: python
189
190 from castellan import key_manager
191
192 manager = key_manager.API()
193
194 **Example. Using a predetermined configuration object.**
195
196 .. code:: python
197
198 from oslo_config import cfg
199 from castellan import key_manager
200
201 conf = cfg.ConfigOpts()
202 manager = key_manager.API(configuration=conf)
203
204 Controlling default options
205 ---------------------------
206
207 To change the default behavior of castellan, and the key management service
208 it uses, the ``castellan.options`` module provides the ``set_defaults``
209 function. This function can be used at run-time to change the behavior of
210 the library or the key management service provider.
211
212 **Example. Changing the barbican endpoint.**
213
214 .. code:: python
215
216 from oslo_config import cfg
217 from castellan import options
218 from castellan import key_manager
219
220 conf = cfg.ConfigOpts()
221 options.set_defaults(conf, barbican_endpoint='http://192.168.0.1:9311/')
222 manager = key_manager.API(conf)
223
224 **Example. Changing the key manager provider while using the global
225 configuration.**
226
227 .. code:: python
228
229 from oslo_config import cfg
230 from castellan import options
231 from castellan import key_manager
232
233 options.set_defaults(cfg.CONF, api_class='some.other.KeyManager')
234 manager = key_manager.API()
235
236 Logging from within Castellan
237 -----------------------------
238
239 Castellan uses ``oslo_log`` for logging. Log information will be generated
240 if your application has configured the ``oslo_log`` module. If your
241 application does not use ``oslo_log`` then you can enable default logging
242 using ``enable_logging`` in the ``castellan.options`` module.
243
244 **Example. Enabling default logging.**
245
246 .. code:: python
247
248 from castellan import options
249 from castellan import key_manager
250
251 options.enable_logging()
252 manager = key_manager.API()
253
254 Generating sample configuration files
255 -------------------------------------
256
257 Castellan includes a tox configuration for creating a sample configuration
258 file. This file will contain only the values that will be used by
259 castellan. To produce this file, run the following command from the
260 root of the castellan project directory:
261
262 .. code:: console
263
264 $ tox -e genconfig
265
266
267 Parsing the configuration files
268 -------------------------------
269
270 Castellan does not parse the configuration files by default. When you create
271 the files and occupy them, you still need to manipulate the
272 ``oslo_config.cfg`` object before passing it to the
273 ``castellan.key_manager.API`` object. You can create a list of locations where
274 the configuration files reside. If multiple configuration files are
275 specified, the variables will be used from the most recently parsed file and
276 overwrite any previous variables. In the example below, the configuration
277 file in the ``/etc/castellan`` directory will overwrite the values found in
278 the file in the user's home directory. If a file is not found in one of the
279 specified locations, then a config file not found error will occur.
280
281 **Example. Parsing the config files.**
282
283 .. code:: python
284
285 from oslo_config import cfg
286 from castellan import key_manager
287
288 conf=cfg.CONF
289 config_files = ['~/castellan.conf', '/etc/castellan/castellan.conf']
290 conf(default_config_files=config_files)
291 manager = key_manager.API(configuration=conf)
292
293 There are two options for parsing the Castellan values from a
294 configuration file:
295
296 - The values can be placed in a separate file.
297 - You can include the values in a configuration file you already use.
298
299 In order to see all of the default values used by Castellan, generate a
300 sample configuration by referring to the section directly above.
301
302 Adding castellan to configuration files
303 ---------------------------------------
304
305 One common task for OpenStack projects is to create project configuration
306 files. Castellan provides a ``list_opts`` function in the
307 ``castellan.options`` module to aid in generating these files when using
308 the ``oslo-config-generator``. This function can be specified in the
309 :file:`setup.cfg` file of your project to inform oslo of the
310 configuration options. *Note, this will use the default values supplied
311 by the castellan package.*
312
313 **Example. Adding castellan to the oslo.config entry point.**
314
315 .. code:: ini
316
317 [entry_points]
318 oslo.config.opts =
319 castellan.config = castellan.options:list_opts
320
321 The new namespace also needs to be added to your project's
322 oslo-config-generator conf, e.g. `etc/oslo-config-generator/myproject.conf`:
323
324 .. code:: ini
325
326 [DEFAULT]
327 output_file = etc/myproject/myproject.conf
328 namespace = castellan.config
329
330 For more information on the oslo configuration generator, please see
331 https://docs.openstack.org/developer/oslo.config/generator.html
0 =====
1 Usage
2 =====
3
4 This document describes some of the common usage patterns for Castellan. When
5 incorporating this package into your applications, care should be taken to
6 consider the key manager behavior you wish to encapsulate and the OpenStack
7 deployments on which your application will run.
8
9 Authentication
10 ~~~~~~~~~~~~~~
11
12 A fundamental concept to using Castellan is the credential context object.
13 Castellan supports the following credentials for authentication:
14
15 * Token
16 * Password
17 * Keystone Token
18 * Keystone Password
19
20 In order to use these credentials, valid configuration parameters must be
21 provided.
22
23 .. code:: ini
24
25 # token credential
26 # token variable not required, token can be obtained from context
27 [key_manager]
28 auth_type = 'token'
29 token = '5b4de0bb77064f289f7cc58e33bea8c7'
30
31 # password credential
32 [key_manager]
33 auth_type = 'password'
34 username = 'admin'
35 password = 'passw0rd1'
36
37 # keystone token credential
38 [key_manager]
39 auth_type = 'keystone_token'
40 token = '5b4de0bb77064f289f7cc58e33bea8c7'
41 project_id = 'a1e19934af81420d980a5d02b4afe9fb'
42
43 # keystone password credential
44 [key_manager]
45 auth_type = 'keystone_password'
46 username = 'admin'
47 password = 'passw0rd1'
48 project_id = '1099302ec608486f9879ba2466c60720'
49 user_domain_name = 'default'
50
51 .. note::
52
53 Keystone Token and Password authentication is achieved using
54 keystoneauth1.identity Token and Password auth plugins.
55 There are a variety of different variables which can be set for the
56 keystone credential options.
57
58
59 The configuration must be passed to a credential factory which will
60 generate the appropriate context.
61
62 .. code:: python
63
64 from castellan.common import utils
65
66 CONF = <your_configuration>
67 context = utils.credential_factory(conf=CONF, context=None)
68
69 Now you can go ahead and pass the context and use it for authentication.
70
71 .. note::
72
73 There is a special case for a token. Since a user may not want to store a
74 token in the configuration, the user can pass a context object containing
75 an 'auth_token' as well as a configuration file with 'token' as the
76 auth type.
77
78
79 An oslo context object can also be used for authentication, it is
80 frequently inherited from ``oslo.context.RequestContext``. This object
81 represents information that is contained in the current request, and is
82 usually populated in the WSGI pipeline. The information contained in this
83 object will be used by Castellan to interact with the specific key manager
84 that is being abstracted.
85
86 **Example. Creating RequestContext from Keystone Client**
87
88 .. code:: python
89
90 from keystoneauth1 import identity
91 from keystoneauth1 import session
92 from oslo_context import context
93
94 username = 'admin'
95 password = 'openstack'
96 project_name = 'admin'
97 auth_url = 'http://localhost/identity/v3'
98 auth = identity.Password(auth_url=auth_url,
99 username=username,
100 password=password,
101 project_name=project_name,
102 default_domain_id='default')
103 sess = session.Session()
104
105 ctxt = context.RequestContext(auth_token=auth.get_token(sess),
106 tenant=auth.get_project_id(sess))
107
108 ctxt can then be passed into any key_manager api call.
109
110
111 Basic usage
112 ~~~~~~~~~~~
113
114 Castellan works on the principle of providing an abstracted key manager based
115 on your configuration. In this manner, several different management services
116 can be supported through a single interface.
117
118 In addition to the key manager, Castellan also provides primitives for
119 various types of secrets (for example, asymmetric keys, simple passphrases,
120 and certificates). These primitives are used in conjunction with the key
121 manager to create, store, retrieve, and destroy managed secrets.
122
123 **Example. Creating and storing a key.**
124
125 .. code:: python
126
127 import myapp
128 from castellan.common.objects import passphrase
129 from castellan import key_manager
130
131 key = passphrase.Passphrase('super_secret_password')
132 manager = key_manager.API()
133 stored_key_id = manager.store(myapp.context(), key)
134
135 To begin with, we'd like to create a key to manage. We create a simple
136 passphrase key, then instantiate the key manager, and finally store it to
137 the manager service. We record the key identifier for later usage.
138
139 **Example. Retrieving a key and checking the contents.**
140
141 .. code:: python
142
143 import myapp
144 from castellan import key_manager
145
146 manager = key_manager.API()
147 key = manager.get(myapp.context(), stored_key_id)
148 if key.get_encoded() == 'super_secret_password':
149 myapp.do_secret_stuff()
150
151 This example demonstrates retrieving a stored key from the key manager service
152 and checking its contents. First we instantiate the key manager, then
153 retrieve the key using a previously stored identifier, and finally we check
154 the validity of key before performing our restricted actions.
155
156 **Example. Deleting a key.**
157
158 .. code:: python
159
160 import myapp
161 from castellan import key_manager
162
163 manager = key_manager.API()
164 manager.delete(myapp.context(), stored_key_id)
165
166 Having finished our work with the key, we can now delete it from the key
167 manager service. We once again instantiate a key manager, then we simply
168 delete the key by using its identifier. Under normal conditions, this call
169 will not return anything but may raise exceptions if there are communication,
170 identification, or authorization issues.
171
172 Configuring castellan
173 ~~~~~~~~~~~~~~~~~~~~~
174
175 Castellan contains several options which control the key management
176 service usage and the configuration of that service. It also contains
177 functions to help configure the defaults and produce listings for use
178 with the ``oslo-config-generator`` application.
179
180 In general, castellan configuration is handled by passing an
181 ``oslo_config.cfg.ConfigOpts`` object into the
182 ``castellan.key_manager.API`` call when creating your key manager. By
183 default, when no ``ConfigOpts`` object is provided, the key manager will
184 use the global ``oslo_config.cfg.CONF`` object.
185
186 **Example. Using the global CONF object for configuration.**
187
188 .. code:: python
189
190 from castellan import key_manager
191
192 manager = key_manager.API()
193
194 **Example. Using a predetermined configuration object.**
195
196 .. code:: python
197
198 from oslo_config import cfg
199 from castellan import key_manager
200
201 conf = cfg.ConfigOpts()
202 manager = key_manager.API(configuration=conf)
203
204 Controlling default options
205 ---------------------------
206
207 To change the default behavior of castellan, and the key management service
208 it uses, the ``castellan.options`` module provides the ``set_defaults``
209 function. This function can be used at run-time to change the behavior of
210 the library or the key management service provider.
211
212 **Example. Changing the barbican endpoint.**
213
214 .. code:: python
215
216 from oslo_config import cfg
217 from castellan import options
218 from castellan import key_manager
219
220 conf = cfg.ConfigOpts()
221 options.set_defaults(conf, barbican_endpoint='http://192.168.0.1:9311/')
222 manager = key_manager.API(conf)
223
224 **Example. Changing the key manager provider while using the global
225 configuration.**
226
227 .. code:: python
228
229 from oslo_config import cfg
230 from castellan import options
231 from castellan import key_manager
232
233 options.set_defaults(cfg.CONF, api_class='some.other.KeyManager')
234 manager = key_manager.API()
235
236 Logging from within Castellan
237 -----------------------------
238
239 Castellan uses ``oslo_log`` for logging. Log information will be generated
240 if your application has configured the ``oslo_log`` module. If your
241 application does not use ``oslo_log`` then you can enable default logging
242 using ``enable_logging`` in the ``castellan.options`` module.
243
244 **Example. Enabling default logging.**
245
246 .. code:: python
247
248 from castellan import options
249 from castellan import key_manager
250
251 options.enable_logging()
252 manager = key_manager.API()
253
254 Generating sample configuration files
255 -------------------------------------
256
257 Castellan includes a tox configuration for creating a sample configuration
258 file. This file will contain only the values that will be used by
259 castellan. To produce this file, run the following command from the
260 root of the castellan project directory:
261
262 .. code:: console
263
264 $ tox -e genconfig
265
266
267 Parsing the configuration files
268 -------------------------------
269
270 Castellan does not parse the configuration files by default. When you create
271 the files and occupy them, you still need to manipulate the
272 ``oslo_config.cfg`` object before passing it to the
273 ``castellan.key_manager.API`` object. You can create a list of locations where
274 the configuration files reside. If multiple configuration files are
275 specified, the variables will be used from the most recently parsed file and
276 overwrite any previous variables. In the example below, the configuration
277 file in the ``/etc/castellan`` directory will overwrite the values found in
278 the file in the user's home directory. If a file is not found in one of the
279 specified locations, then a config file not found error will occur.
280
281 **Example. Parsing the config files.**
282
283 .. code:: python
284
285 from oslo_config import cfg
286 from castellan import key_manager
287
288 conf=cfg.CONF
289 config_files = ['~/castellan.conf', '/etc/castellan/castellan.conf']
290 conf(default_config_files=config_files)
291 manager = key_manager.API(configuration=conf)
292
293 There are two options for parsing the Castellan values from a
294 configuration file:
295
296 - The values can be placed in a separate file.
297 - You can include the values in a configuration file you already use.
298
299 In order to see all of the default values used by Castellan, generate a
300 sample configuration by referring to the section directly above.
301
302 Adding castellan to configuration files
303 ---------------------------------------
304
305 One common task for OpenStack projects is to create project configuration
306 files. Castellan provides a ``list_opts`` function in the
307 ``castellan.options`` module to aid in generating these files when using
308 the ``oslo-config-generator``. This function can be specified in the
309 :file:`setup.cfg` file of your project to inform oslo of the
310 configuration options. *Note, this will use the default values supplied
311 by the castellan package.*
312
313 **Example. Adding castellan to the oslo.config entry point.**
314
315 .. code:: ini
316
317 [entry_points]
318 oslo.config.opts =
319 castellan.config = castellan.options:list_opts
320
321 The new namespace also needs to be added to your project's
322 oslo-config-generator conf, e.g. `etc/oslo-config-generator/myproject.conf`:
323
324 .. code:: ini
325
326 [DEFAULT]
327 output_file = etc/myproject/myproject.conf
328 namespace = castellan.config
329
330 For more information on the oslo configuration generator, please see
331 https://docs.openstack.org/developer/oslo.config/generator.html