c69f29e92f
This PS updates all Deckhand documentation to be sphinx-compliant so that it can be rendered into HTML automatically for hosting. This PS also removes deprecated/redundant/unhelpful documentation and upates README to a bit more informative and helpful. The design.md file has been broken up into different sections with deckhand/docs for easier consumption. Change-Id: I44afcd22a7f5f05e44563342bb98b30fd806f598
152 lines
4.4 KiB
ReStructuredText
152 lines
4.4 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.
|
|
|
|
.. _layering:
|
|
|
|
Document Layering
|
|
=================
|
|
|
|
Layering provides a restricted data inheritance model intended to help reduce
|
|
duplication in configuration. Documents with different ``schema``'s are never
|
|
layered together (see the :ref:`substitution` section if you need to combine data
|
|
from multiple types of documents).
|
|
|
|
Layering is controlled in two places:
|
|
|
|
1. The ``LayeringPolicy`` control document (described below), which defines the
|
|
valid layers and their order of precedence.
|
|
2. In the ``metadata.layeringDefinition`` section of normal
|
|
(``metadata.schema=metadata/Document/v1``) documents.
|
|
|
|
When rendering a particular document, you resolve the chain of parents upward
|
|
through the layers, and begin working back down each layer rendering at each
|
|
document in the chain.
|
|
|
|
When rendering each layer, the parent document is used as the starting point,
|
|
so the entire contents of the parent are brought forward. Then the list of
|
|
`actions` will be applied in order. Supported actions are:
|
|
|
|
* ``merge`` - "deep" merge child data at the specified path into the existing data
|
|
* ``replace`` - overwrite existing data with child data at the specified path
|
|
* ``delete`` - remove the existing data at the specified path
|
|
|
|
After actions are applied for a given layer, substitutions are applied (see
|
|
the Substitution section for details).
|
|
|
|
Selection of document parents is controlled by the ``parentSelector`` field and
|
|
works as follows. A given document, ``C``, that specifies a ``parentSelector``
|
|
will have exactly one parent, ``P``. Document ``P`` will be the highest
|
|
precedence (i.e. part of the lowest layer defined in the ``layerOrder`` list
|
|
from the ``LayeringPolicy``) document that has the labels indicated by the
|
|
``parentSelector`` (and possibly additional labels) from the set of all
|
|
documents of the same ``schema`` as ``C`` that are in layers above the layer ``C``
|
|
is in. For example, consider the following sample documents:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/LayeringPolicy/v1
|
|
metadata:
|
|
schema: metadata/Control/v1
|
|
name: layering-policy
|
|
data:
|
|
layerOrder:
|
|
- global
|
|
- region
|
|
- site
|
|
---
|
|
schema: example/Kind/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: global-1234
|
|
labels:
|
|
key1: value1
|
|
layeringDefinition:
|
|
abstract: true
|
|
layer: global
|
|
data:
|
|
a:
|
|
x: 1
|
|
y: 2
|
|
---
|
|
schema: example/Kind/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: region-1234
|
|
labels:
|
|
key1: value1
|
|
layeringDefinition:
|
|
abstract: true
|
|
layer: region
|
|
parentSelector:
|
|
key1: value1
|
|
actions:
|
|
- method: replace
|
|
path: .a
|
|
data:
|
|
a:
|
|
z: 3
|
|
---
|
|
schema: example/Kind/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: site-1234
|
|
layeringDefinition:
|
|
layer: site
|
|
parentSelector:
|
|
key1: value1
|
|
actions:
|
|
- method: merge
|
|
path: .
|
|
data:
|
|
b: 4
|
|
|
|
When rendering, the parent chosen for ``site-1234`` will be ``region-1234``,
|
|
since it is the highest precedence document that matches the label selector
|
|
defined by ``parentSelector``, and the parent chosen for ``region-1234`` will be
|
|
``global-1234`` for the same reason. The rendered result for ``site-1234`` would
|
|
be:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: example/Kind/v1
|
|
metadata:
|
|
name: site-1234
|
|
data:
|
|
a:
|
|
z: 3
|
|
b: 4
|
|
|
|
If ``region-1234`` were later removed, then the parent chosen for `site-1234`
|
|
would become ``global-1234``, and the rendered result would become:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: example/Kind/v1
|
|
metadata:
|
|
name: site-1234
|
|
data:
|
|
a:
|
|
x: 1
|
|
y: 2
|
|
b: 4
|
|
|
|
.. TODO: Add figures for this example, with region present, have site point
|
|
.. with dotted line at global and indicate in caption (or something) that it's
|
|
.. selected for but ignored, because there's a higher-precedence layer to select
|