2
Copyright 2011-2012 OpenStack, LLC
5
Licensed under the Apache License, Version 2.0 (the "License"); you may
6
not use this file except in compliance with the License. You may obtain
7
a copy of the License at
9
http://www.apache.org/licenses/LICENSE-2.0
11
Unless required by applicable law or agreed to in writing, software
12
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
License for the specific language governing permissions and limitations
17
========================
18
Developing with Keystone
19
========================
24
To contribute code, sign up for a Launchpad account and sign a contributor
25
license agreement, available on the `<http://wiki.openstack.org/CLA>`_. Once
26
the CLA is signed you can contribute code through the Gerrit version control
27
system which is related to your Launchpad account.
30
To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_.
32
.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub
37
Get your development environment set up according to :doc:`setup`. The
38
instructions from here will assume that you have installed keystone into a
39
virtualenv. If you chose not to, simply exclude "tools/with_venv.sh" from the
40
example commands below.
46
To run the keystone Admin and API server instances, use::
48
$ tools/with_venv.sh bin/keystone-all
50
this runs keystone with the configuration the etc/ directory of the project.
51
See :doc:`configuration` for details on how Keystone is configured. By default,
52
keystone is configured with KVS backends, so any data entered into keystone run
53
in this fashion will not persist across restarts.
56
Interacting with Keystone
57
-------------------------
59
You can interact with Keystone through the command line using
60
:doc:`man/keystone-manage` which allows you to establish tenants, users, etc.
63
You can also interact with Keystone through it's REST API. There is a python
64
keystone client library `python-keystoneclient`_ which interacts exclusively
65
through the REST API, and which keystone itself uses to provide it's
66
command-line interface.
68
When initially getting set up, after you've configured which databases to use,
69
you're probably going to need to run the following to your database schema in
72
$ bin/keystone-manage db_sync
74
.. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient
79
To run the full suites of tests maintained within Keystone, run::
83
This shows realtime feedback during test execution, iterates over
84
multiple configuration variations, and uses external projects to do
85
light integration testing to verify the keystone API against other projects.
90
``./run_test.sh`` uses its python cohort (``run_tests.py``) to iterate
91
through the ``tests`` directory, using Nosetest to collect the tests and
92
invoke them using an OpenStack custom test running that displays the tests
93
as well as the time taken to
96
Within the tests directory, the general structure of the tests is a basic
97
set of tests represented under a test class, and then subclasses of those
98
tests under other classes with different configurations to drive different
99
backends through the APIs.
101
For example, ``test_backend.py`` has a sequence of tests under the class
102
``IdentityTests`` that will work with the default drivers as configured in
103
this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests,
104
changing the configuration by overriding with configuration files stored in
105
the tests directory aimed at enabling the SQL backend for the Identity module.
107
Likewise, ``test_cli.py`` takes advantage of the tests written aainst
108
``test_keystoneclient`` to verify the same tests function through different
111
Testing Schema Migrations
112
-------------------------
114
The application of schema migrations can be tested using SQLAlchemy Migrate’s
115
built-in test runner, one migration at a time.
119
This may leave your database in an inconsistent state; attempt this in non-production environments only!
121
This is useful for testing the *next* migration in sequence (both forward &
122
backward) in a database under version control::
125
python keystone/common/sql/migrate_repo/manage.py test \
126
--url=sqlite:///test.db \
127
--repository=keystone/common/sql/migrate_repo/
129
This command references to a SQLite database (test.db) to be used. Depending on
130
the migration, this command alone does not make assertions as to the integrity
131
of your data during migration.
137
To add tests covering all drivers, update the base test class
138
(``test_backend.py``, ``test_legacy_compat.py``, and
139
``test_keystoneclient.py``).
141
To add new drivers, subclass the ``test_backend.py`` (look towards
142
``test_backend_sql.py`` or ``test_backend_kvs.py`` for examples) and update the
143
configuration of the test class in ``setUp()``.
149
devstack_ is the *best* way to quickly deploy keystone with the rest of the
150
OpenStack universe and should be critical step in your development workflow!
152
You may also be interested in either the
153
`OpenStack Continuous Integration Project`_ or the
154
`OpenStack Integration Testing Project`_.
156
.. _devstack: http://devstack.org/
157
.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci
158
.. _OpenStack Integration Testing Project: https://github.com/openstack/tempest
160
Building the Documentation
161
==========================
163
The documentation is all generated with Sphinx from within the docs directory.
164
To generate the full set of HTML documentation:
171
the results are in the docs/build/html and docs/build/man directories
added
removed
docs/source/developing.rst
