pegleg/docs/source/authoring_strategy.rst

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 of true) or concrete (a value of false). 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, and namespace.
• 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 the site layer.

This catalogue pattern can also be utilized for the type layer if needed.

Global Layer

Site Layer