11 KiB
Document Fundamentals
The definition of a site consists of a set of small YAML documents
that are managed by _Deckhand http://deckhand.readthedocs.io/en/latest/.
Each document is identified by a schema
top-level key and
the metadata.name
value that uniquely identifies a
particular document of the type schema
. Deckhand provides
functionality allowing documents to be authored such that data from
multiple documents can be merged.
- Abstact vs Concrete - Documents define a value in
metadata.layeringDefinition.abstract
to determine if a document is abstract (a value oftrue
) or concrete (a value offalse
). When calling the/revisions/{id}/rendered-documents
API, only concrete documents are returned.- Layering - Document _layering http://deckhand.readthedocs.io/en/latest/layering.html is used for whole documents that have known defaults but may need to be transformed in specific instances.
- Substitution - Data _substitution http://deckhand.readthedocs.io/en/latest/substitution.html is used for extracting particular values from a document's data section (whole or in-part) and inserting that data into a destination document (at the root of the data section or deeper into a document).
Shared Documents
Secrets
Several generic document _types http://deckhand.readthedocs.io/en/latest/document_types.html#provided-utility-document-kinds exist to support storing sensitive data encrypted.
These must be utilized for all data considered sensitive.
Global Catalogue Documents
Deckhand's layering functionality can be utilized in several ways,
but AIC site definitions will use a 'catalogue' approach. At the
global
layer there will be several documents providing
different configurations for an object or service. Each of these will be
abstract documents. They can be incorporated into a particular site
definition by creating a concrete child document in the
site
layer that selects the correct global
parent. The child can then do further customization on the configuration
if needed.
As a best practice, global
level documents using the
catalogue pattern should utilize the layering labels
component
and configuration
to provide a
consistent method for children documents select the correct parent. The
below example shows a set of documents for two configuration options for
OpenStack Keystone: one using local SQL-backed identity stores and one
using an LDAP backend. A site definition can then select and customize
the appropriate option.
When using a catalogue document, it is important to review that document to ensure you understand all the requirements for it.
- Abstract documents are not required to be fully formed, so selecting a catalogue document may require the child document to add data so the document passes validation. In the below example, the child document adds several required fields to the catalogue Chart:
chart_name
,release
, andnamespace
.- A catalogue document may define substitutions with the expectation that the substitution source documents are defined at a lower layer. In the example below, all of the required credentials in the chart are defined as substitutions in the
global
catalogue document, but the source documents for the substitutions are defined in thesite
layer.
This catalogue pattern can also be utilized for the type
layer if needed.