Add documentation for the project history and guide lines
Because of how vague the scope of Adjutant is (for a reason) we need a way to define what actually fits in a sensible way. The new guide lines are part of that, and we're also now adding a section to our docs about the project history to explain why the scope is so vague and how it got there. Plus a section on project features, to help define what it can do. Change-Id: I7d05c1f43570843171a4144ece2228efc3227cce
This commit is contained in:
Adrian Turjak
parent
1a07c1ead2
commit
9fefbfe85b
@ -1,6 +1,6 @@
|
||||
####################################
|
||||
Functionality
|
||||
####################################
|
||||
###########
|
||||
Development
|
||||
###########
|
||||
|
||||
Adjutant is built around tasks and actions.
|
||||
|
||||
102
doc/source/features.rst
Normal file
102
doc/source/features.rst
Normal file
@ -0,0 +1,102 @@
|
||||
Project Features
|
||||
################
|
||||
|
||||
To be clear, Adjutant doesn't really have features. It's a framework for
|
||||
deployer defined workflow, and a service to expose those workflows on
|
||||
configurable APIs, and supplementary micro APIs. This provides useful ways to
|
||||
extend some functionality in OpenStack and wrap sensible business logic around
|
||||
it, all while providing a clear audit trail for all tasks that Adjutant
|
||||
handles.
|
||||
|
||||
Adjutant does have default implementations of workflows and the APIs for
|
||||
them. These are in part meant to be workflow that is applicable to any cloud,
|
||||
but also example implementations, as well as actions that could potentially be
|
||||
reused in deployer specific workflow in their own plugins. If anything could
|
||||
be considered a feature, it potentially could be these. The plan is to add many
|
||||
of these, which any cloud can use out of the box, or augment as needed.
|
||||
|
||||
To enable these they must be added to `ACTIVE_TASKVIEWS` in the conf file.
|
||||
|
||||
For most of these there are matching panels in Horizon.
|
||||
|
||||
Built in Tasks and APIs
|
||||
=======================
|
||||
|
||||
UserList
|
||||
++++++++
|
||||
|
||||
List the users on your project if you have the `project_admin` or `project_mod`
|
||||
role, and allow the invitiation of additional members (via email) to your
|
||||
project.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Project Users panel for Horizon.
|
||||
|
||||
UserRoles
|
||||
+++++++++
|
||||
|
||||
Allows the editing of roles for users in the same project provided you have
|
||||
the `project_admin` or `project_mod` role.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Project Users panel for Horizon.
|
||||
|
||||
RoleList
|
||||
++++++++
|
||||
|
||||
Mirco API to list roles that can be managed by your current user for users on
|
||||
your project.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Project Users panel for Horizon.
|
||||
|
||||
UserDetail
|
||||
++++++++++
|
||||
|
||||
Just a micro API to show details of users on your project, and cancel invite
|
||||
user tasks.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Project Users panel for Horizon.
|
||||
|
||||
UserResetPassword
|
||||
+++++++++++++++++
|
||||
|
||||
An unauthenticated API that allows password reset request submissions. Will
|
||||
check if user exists, and email user with password reset token to reset
|
||||
password. This token is usable in Horizon, or via the API directly.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Forgot Password panel for Horizon.
|
||||
|
||||
SignUp
|
||||
++++++
|
||||
|
||||
An unauthenticated API that allows prospective users to submit requests to have
|
||||
a project and account created. This will then notify an admin as configured
|
||||
and an admin can approve or cancel the request.
|
||||
|
||||
This is mostly built as a basic example of a signup workflow. Most companies
|
||||
would use this only as a template and expand on the actions to talk to external
|
||||
systems and facilitate much more complex validation.
|
||||
|
||||
A more complex example of a signup process built on top of the defaults is
|
||||
Catalyst Cloud's own one: https://github.com/catalyst-cloud/adjutant-odoo
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Sign Up panel for Horizon.
|
||||
|
||||
UserUpdateEmail
|
||||
+++++++++++++++
|
||||
|
||||
A simple task that allows a user to update their own email address (or username
|
||||
if username==email). An email is sent to the old email informing them of the
|
||||
change, and a token to the new email so that the user must confirm they have
|
||||
correctly given their email.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Update Email Address panel for
|
||||
Horizon.
|
||||
|
||||
|
||||
UpdateProjectQuotas
|
||||
+++++++++++++++++++
|
||||
|
||||
A way for users to request quota changes between given sizes. These requests
|
||||
are either automatically approved if configured as such, or require an admin
|
||||
to approve the quota change.
|
||||
|
||||
.. note:: Adjutant-UI exposes this with the Quota Management panel for Horizon.
|
||||
103
doc/source/guide-lines.rst
Normal file
103
doc/source/guide-lines.rst
Normal file
@ -0,0 +1,103 @@
|
||||
Project Guide Lines
|
||||
===================
|
||||
|
||||
Because of the extremely vague scope of the Adjutant project, we need to have
|
||||
some sensible guides lines to help us define what isn't part of it, and what
|
||||
should or could be.
|
||||
|
||||
Adjutant is a service to let cloud providers build workflow around certain
|
||||
actions, or to build smaller APIs around existing things in OpenStack. Or even
|
||||
APIs to integrate with OpenStack, but do actions in external systems.
|
||||
|
||||
Ultimately Adjutant is a Django project with a few limitations, and the plugin
|
||||
system probably exposes too much extra functionality which can be added by a
|
||||
plugin. Some of this we plan to cut down, and throw in some explicitly defined
|
||||
limitations, but even with the planned limitations the framework will always
|
||||
be very flexible.
|
||||
|
||||
|
||||
Should a feature become part of core
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Core Adjutant is mostly two parts. The first is the underlying workflow system,
|
||||
the APIs associated that, and the notifications. The second is the provider
|
||||
configurable APIs. This separation will increase further as we try and distance
|
||||
the workflow layer away from having one task linked to a view.
|
||||
|
||||
Anything that is a useful improvement to the task workflow framework and the
|
||||
associated APIs and notifications system, is always useful for core. As part of
|
||||
this we do include, and plan to keep adding to, a collection of generally
|
||||
useful actions and tasks. For those we need to be clear what should be part of
|
||||
core.
|
||||
|
||||
1. Is the action one that better makes sense as a feature in one of the
|
||||
existing services in OpenStack? If so, we should add it there, and then
|
||||
build an action in Adjutant that calls this new API or feature.
|
||||
2. Is the action you want to add one that is useful or potentially useful to
|
||||
any cloud provider? If it is too specific, it should not be added to core.
|
||||
3. Is the action you want to add talking to system outside of Adjutant itself
|
||||
or outside of OpenStack? If either, then it should not be added to core.
|
||||
4. Is the task (a combination of actions), doing something that is already in
|
||||
some fashion in OpenStack, or better suited to be a feature in another
|
||||
OpenStack service. If so, it does not belong in core.
|
||||
|
||||
In addition to that, we include a collection of generally useful API views
|
||||
which expose certain underlying tasks as part of the workflow framework. These
|
||||
also need clarification as to when they should be in core. These are mostly a
|
||||
way to build smaller APIs that cloud users can use consume that underneath are
|
||||
using Adjutant's workflow framework. Or often build APIs that expose useful
|
||||
wrappers or supplementary logic around existing OpenStack APIs and features.
|
||||
|
||||
1. Is the API you are building something that makes better sense as a feature
|
||||
in one of the other existing OpenStack services? If so, it doesn't belong in
|
||||
Adjutant core.
|
||||
2. Does the API query systems outside of Adjutant or OpenStack? Or rely on
|
||||
actions or tasks that also need to consume systems outside of Adjutant or
|
||||
OpenStack.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If an action, task, or API doesn't fit in core, it may fit in a plugin,
|
||||
potentially even one that is maintained by the core team. If a feature isn't
|
||||
yet present in OpenStack that we can build in Adjutant quickly, we can do so
|
||||
as a semi-official plugin with the knowledge that we plan to deprecate that
|
||||
feature when it becomes present in OpenStack proper. In addition this process
|
||||
allows us to potentially allow providers to expose a variant of the feature
|
||||
if they are running older versions of OpenStack that don't entirely support
|
||||
it, but Adjutant could via the plugin mechanism. This gives us a large amount
|
||||
of flexibility, while ensuring we aren't reinventing the wheel.
|
||||
|
||||
|
||||
Appropriate locations for types of logic in Adjutant
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
In Adjutant there are different elements of the system that are better suited
|
||||
to certain types of logic either because of what they expose, or what level of
|
||||
auditability is appropriate for a given area.
|
||||
|
||||
Actions and Tasks
|
||||
*****************
|
||||
|
||||
Actions and Tasks (collections of actions), have no real constraint. An action
|
||||
can do anything, and needs a high level of flexibility. Given that is the cases
|
||||
they should ideally have sensible validation built in, and should log what
|
||||
they'd done so it can be audited.
|
||||
|
||||
Pluggable APIs
|
||||
**************
|
||||
|
||||
Within the pluggable APIs, there should never be any logic that changes
|
||||
resources outside of Adjutant. They should either only change Adjutant internal
|
||||
resources (such as cancel a task), or query and return data. Building an API
|
||||
which can return a complex query across multiple OpenStack services is fine,
|
||||
but if a resource in any of those services needs to be changed, that should
|
||||
always be done by triggering an underlying task workflow. This keeps the logic
|
||||
clean, and the changes auditable.
|
||||
|
||||
.. warning::
|
||||
|
||||
Anyone writing API plugins that break the above convention will not be
|
||||
supported. We may help and encourage you to move to using the underlying
|
||||
workflows, but the core team won't help you troubleshoot any logic that isn't
|
||||
in the right place.
|
||||
85
doc/source/history.rst
Normal file
85
doc/source/history.rst
Normal file
@ -0,0 +1,85 @@
|
||||
Project History
|
||||
===============
|
||||
|
||||
Adjutant was started by CatalystCloud to fill our needs around missing
|
||||
features in OpenStack. CatalystCloud is public cloud provider based in New
|
||||
Zealand with a strong focus on opensource, with a team of operators and
|
||||
developers who are all contributors to OpenStack itself.
|
||||
|
||||
Early prototyping for Adjutant began at the end of of 2015 to fill some of the
|
||||
missing pieces we needed as a public cloud provider. It was initially something
|
||||
we had started designing as far back as early 2014, with the scope and design
|
||||
changing many times until initial prototyping and implementation was started in
|
||||
late 2015.
|
||||
|
||||
Originally it was designed to act as a service to manage customers, their
|
||||
users, projects, quotas, and to be able to process signups and initial resource
|
||||
creation for new customers. It would act as a layer above OpenStack and most
|
||||
non-authentication based identity management from a user perspective would
|
||||
happen through it, with the service itself making the appropriate changes to
|
||||
the underlying OpenStack services and resources. The reason why it didn't end
|
||||
up quite so complex and so big is because OpenStack itself, and many of the
|
||||
services (and the future roadmap) had planned solutions to many of the things
|
||||
we wanted, and our business requirements changed to storing our customer
|
||||
information in an eternal ERP system (Odoo/OpenERP at the time) rather than a
|
||||
standalone service.
|
||||
|
||||
So instead of something so grand, we tried smaller, a service that handles our
|
||||
unique public cloud requirements for signup. It should take in signup data from
|
||||
some source such as a public API that our website posts to, then validate it,
|
||||
give us those validation notes, and lets us decide if we wanted that customer,
|
||||
or even have the system itself based on certain criteria approve that customer
|
||||
itself. It would then create the user in Keystone, create a project, give them
|
||||
access, create a default network, and then also link and store the customer
|
||||
data in our ERP and billing systems. This was the initial
|
||||
'openstack-registration' project, and the naming of which is present in our git
|
||||
history, and where the initial service-type name comes from.
|
||||
|
||||
As we prototyped this we realised that it was just a workflow system for
|
||||
business logic, so we decided to make it flexible, and found other things we
|
||||
could use it for:
|
||||
|
||||
- Allowing non-admin users to invite other users to their project.
|
||||
- Let users reset their password by sending an email token to them.
|
||||
- Manage and create child-projects in a single domain environment.
|
||||
- Request quota increases for their projects.
|
||||
|
||||
All with the optional step of actually requiring an admin to approve the user
|
||||
request if needed. And with a good audit trail as to where the actions came
|
||||
from, and who approved them.
|
||||
|
||||
Eventually it also got a rename, because calling it OpenStack Registration got
|
||||
dull and wasn't accurate anymore. The name it got at the time was StackTask,
|
||||
and there are still elements of that naming in our systems, and plenty in the
|
||||
git history. Eventually we would rename it again because the name still being
|
||||
feel right, and was too close to StackTach.
|
||||
|
||||
Around that time we also added plugin support to try and keep any company
|
||||
specific code out of the core codebase, and in the process realised just how
|
||||
much further flexibility we'd now added.
|
||||
|
||||
The service gave us an easy way to build APIs around workflow we wanted our
|
||||
customers to be able to trigger around larger normally unsafe admin APIs in
|
||||
OpenStack itself. With the ability to have those workflows do changes to our
|
||||
ERP system, and other external systems. It gave us the missing glue we needed
|
||||
to make our public cloud business requirements and logic actually work.
|
||||
|
||||
But we were always clear, that if something made better sense as a feature in
|
||||
another service, we should implemented in that other service. This was meant to
|
||||
be a glue layer, or potentially for mini API features that don't entirely have
|
||||
a good place for them, or just a wrapper around an existing OpenStack feature
|
||||
that needs organisation specific logic added to it.
|
||||
|
||||
Throughout all this, the goal was always to keep this project fully opensource,
|
||||
to invite external contribution, to do our planning, bug tracking, and
|
||||
development where the OpenStack community could see and be transparent about
|
||||
our own internal usage of the service and our plans for it. The code had been
|
||||
on our company github for a while, but it was time to move it somewhere better.
|
||||
|
||||
So we renamed again, and then finally moved all the core repos to OpenStack
|
||||
infrastructure, as well as the code review, bug, and spec tracking.
|
||||
|
||||
Adjutant, in it's current form is the culmination of that process, and while
|
||||
the core driving force behind Adjutant was our own needs, it always was the
|
||||
intention to provide Adjutant for anyone to build and use themselves so that
|
||||
their effort isn't wasted threading the same ground.
|
||||
@ -1,8 +1,3 @@
|
||||
.. Adjutant documentation master file, created by
|
||||
sphinx-quickstart on Wed Jun 21 13:29:33 2017.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
####################################
|
||||
Welcome to Adjutant's documentation!
|
||||
####################################
|
||||
@ -10,11 +5,14 @@ Welcome to Adjutant's documentation!
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
design
|
||||
development
|
||||
devstack-guide
|
||||
configuration
|
||||
plugins
|
||||
quota
|
||||
guide-lines
|
||||
features
|
||||
history
|
||||
|
||||
.. standard task views and actions
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user