From 9fefbfe85bf4241f9e4eb30cb3e57495ab8bc8d2 Mon Sep 17 00:00:00 2001 From: Adrian Turjak Date: Thu, 22 Feb 2018 14:49:50 +1300 Subject: [PATCH] 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 --- doc/source/{design.rst => development.rst} | 6 +- doc/source/features.rst | 102 ++++++++++++++++++++ doc/source/guide-lines.rst | 103 +++++++++++++++++++++ doc/source/history.rst | 85 +++++++++++++++++ doc/source/index.rst | 10 +- 5 files changed, 297 insertions(+), 9 deletions(-) rename doc/source/{design.rst => development.rst} (98%) create mode 100644 doc/source/features.rst create mode 100644 doc/source/guide-lines.rst create mode 100644 doc/source/history.rst diff --git a/doc/source/design.rst b/doc/source/development.rst similarity index 98% rename from doc/source/design.rst rename to doc/source/development.rst index f6e052f..6067f2f 100644 --- a/doc/source/design.rst +++ b/doc/source/development.rst @@ -1,6 +1,6 @@ -#################################### -Functionality -#################################### +########### +Development +########### Adjutant is built around tasks and actions. diff --git a/doc/source/features.rst b/doc/source/features.rst new file mode 100644 index 0000000..8c27524 --- /dev/null +++ b/doc/source/features.rst @@ -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. diff --git a/doc/source/guide-lines.rst b/doc/source/guide-lines.rst new file mode 100644 index 0000000..448deef --- /dev/null +++ b/doc/source/guide-lines.rst @@ -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. diff --git a/doc/source/history.rst b/doc/source/history.rst new file mode 100644 index 0000000..bd70cbc --- /dev/null +++ b/doc/source/history.rst @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst index abeaa17..22c06de 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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