a8660a7e53
This patch set reorganizes Deckhand's documentation structure for better organization into 3 distinct categories: * developer's guide * operator's guide * user's guide This means that the RTD navigation menu on the left-hand side will have fewer links (see list above) making navigation much easier. This is similar to how Armada organizes its documentation too. This patch set also updates README section with a better overview and trims some fat from it (remove testing documentation as it doesn't really belong there -- there is a dedicated page for that already). Finally, this patch set changes the exceptions page to render as a basic list of autoexception classes because the current tabularized view is not rendering correctly on RTD [0]. [0] https://airship-deckhand.readthedocs.io/en/latest/exceptions.html Change-Id: I162383bf8e3bbd5004603c979ac7b0d760a210c4
152 lines
5.9 KiB
ReStructuredText
152 lines
5.9 KiB
ReStructuredText
..
|
|
Copyright 2017 AT&T Intellectual Property.
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
Overview
|
|
========
|
|
|
|
Deckhand provides document revision management, storage and mutation
|
|
functionality upon which the rest of the `Airship`_ components rely for
|
|
orchestration of infrastructure provisioning. Deckhand understands declarative
|
|
YAML documents that define, end-to-end, the configuration of sites: from the
|
|
hardware -- encompassing network topology and hardware and host profile
|
|
information -- up to the software level that comprises the overcloud.
|
|
|
|
.. _Airship: https://www.airshipit.org
|
|
|
|
Core Responsibilities
|
|
---------------------
|
|
|
|
* *revision history* - improves auditability and enables services to provide
|
|
functional validation of a well-defined collection of documents that are
|
|
meant to operate together
|
|
* *validation* - allows services to implement and register different kinds of
|
|
validations and report errors
|
|
* *buckets* - allow documents to be owned by different services, providing
|
|
write protections around collections of documents
|
|
* *layering* - helps reduce duplication in configuration while maintaining
|
|
auditability across many sites
|
|
* *substitution* - provides separation between secret data and other
|
|
configuration data, while also providing a mechanism for documents to
|
|
share data among themselves
|
|
|
|
Revision History
|
|
----------------
|
|
|
|
Like other version control software, Deckhand allows users to track incremental
|
|
changes to documents via a revision history, built up through individual
|
|
payloads to Deckhand, each forming a separate revision. Each revision, in other
|
|
words, contains its own set of immutable documents: Creating a new revision
|
|
maintains the existing revision history.
|
|
|
|
For more information, see the :ref:`revision-history` section.
|
|
|
|
Validation
|
|
----------
|
|
|
|
For each created revision, built-in :ref:`document-types` are automatically
|
|
validated. Validations are always stored in the database, including detailed
|
|
error messages explaining why validation failed, to help deployers rectify
|
|
syntactical or semantical issues with configuration documents. Regardless of
|
|
validation failure, a new revision is **always** created, except when the
|
|
documents are completely malformed.
|
|
|
|
Deckhand validation functionality is extensible via ``DataSchema`` documents,
|
|
allowing the ``data`` sections of registered document types to be subjected
|
|
to user-provided JSON schemas.
|
|
|
|
.. note::
|
|
|
|
While Deckhand ingests YAML documents, internally it translates them to
|
|
Python objects and can use JSON schemas to validate those objects.
|
|
|
|
For more information, see the :ref:`validation` section.
|
|
|
|
Buckets
|
|
-------
|
|
|
|
Collections of documents, called buckets, are managed together. All documents
|
|
belong to a bucket and all documents that are part of a bucket must be fully
|
|
specified together.
|
|
|
|
To create or update a new document in, e.g. bucket ``mop``, one must PUT the
|
|
entire set of documents already in ``mop`` along with the new or modified
|
|
document. Any documents not included in that PUT will be automatically
|
|
deleted in the created revision.
|
|
|
|
Each bucket provides write protections around a group of documents. That is,
|
|
only the bucket that owns a collection of documents can manage those documents.
|
|
However, documents can be read across different buckets and used together to
|
|
render finalized configuration documents, to be consumed by other services like
|
|
Armada, Drydock, Promenade or Shipyard.
|
|
|
|
In other words:
|
|
|
|
* Documents can be **read** from any bucket.
|
|
|
|
This is useful so that documents from different buckets can be used together
|
|
for layering and substitution.
|
|
|
|
* Documents can only be **written** to by the bucket that owns them.
|
|
|
|
This is useful because it offers the concept of ownership to a document in
|
|
which only the bucket that owns the document can manage it.
|
|
|
|
.. todo::
|
|
|
|
Deckhand should offer RBAC (Role-Based Access Control) around buckets. This
|
|
will allow deployers to control permissions around who can write or read
|
|
documents to or from buckets.
|
|
|
|
.. note::
|
|
|
|
The best analogy for a bucket is a folder. Like a folder, which houses files
|
|
and offers read and write permissions, a bucket houses documents and offers
|
|
read and write permissions around them.
|
|
|
|
A bucket is **not** akin to a repository, because a repository has its own
|
|
distinct revision history. A bucket, on the other hand, shares its revision
|
|
history with every other bucket.
|
|
|
|
Layering
|
|
--------
|
|
|
|
Layering provides a restricted data inheritance model intended to help reduce
|
|
duplication in configuration. A ``LayeringPolicy`` can be created to declare
|
|
the order of inheritance via layers for documents. Parent documents can
|
|
provide common data to child documents, who can override their parent data
|
|
or tweak it in order to achieve more nuanced configuration that builds on top
|
|
of common configurations.
|
|
|
|
For more information, see the :ref:`layering` section.
|
|
|
|
Substitution
|
|
------------
|
|
|
|
Substitution is a mechanism for documents to share data among themselves. It
|
|
is particularly useful for documents that possess secrets to be stored securely
|
|
and on demand provide the secrets to documents that need them. However,
|
|
substitution can also apply to any data, not just secrets.
|
|
|
|
For more information, see the :ref:`substitution` section.
|
|
|
|
Replacement
|
|
-----------
|
|
|
|
Document replacement provides an advanced mechanism for reducing the overhead
|
|
with data duplication across multiple documents.
|
|
|
|
For more information, see the :ref:`replacement` section.
|