321 lines
9.4 KiB
ReStructuredText
321 lines
9.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.
|
|
|
|
.. _document-types:
|
|
|
|
Document Types
|
|
==============
|
|
|
|
.. _application-documents:
|
|
|
|
Application Documents
|
|
---------------------
|
|
|
|
Application documents are those whose ``metadata.schema`` begins with
|
|
``metadata/Document``. These documents define all the data that make up
|
|
a site deployment, including but not limited to: networking, hardware, host,
|
|
bare metal, software, etc. site information. Prior to ingestion by Deckhand,
|
|
application documents are known as "raw documents". After rendering, they are
|
|
known as "rendered documents". Application documents are subject to the
|
|
following :ref:`rendering` operations:
|
|
|
|
* :ref:`encryption`
|
|
* :ref:`layering`
|
|
* :ref:`substitution`
|
|
* :ref:`replacement`
|
|
|
|
.. _control-documents:
|
|
|
|
Control Documents
|
|
-----------------
|
|
|
|
Control documents (documents which have ``metadata.schema`` of
|
|
``metadata/Control/v1``), are special, and are used to control
|
|
the behavior of Deckhand at runtime. Control documents are immutable so
|
|
any document mutation or manipulation does not apply to them.
|
|
|
|
Control documents only exist to control how :ref:`application-documents` are
|
|
validated and rendered.
|
|
|
|
.. note::
|
|
|
|
Unlike :ref:`application-documents`, control documents do not require
|
|
``storagePolicy`` or ``layeringDefinition`` properties; in fact, it is
|
|
recommended that such properties not be used for control documents. Again,
|
|
this is because such documents should not themselves undergo layering,
|
|
substitution or encryption. It is not meaningful to treat them like normal
|
|
documents. See :ref:`validation-schemas` for more information on required
|
|
document properties.
|
|
|
|
Only the following types of control documents are allowed:
|
|
|
|
DataSchema
|
|
^^^^^^^^^^
|
|
|
|
``DataSchema`` documents are used by various services to register new schemas
|
|
that Deckhand can use for validation. No ``DataSchema`` documents with names
|
|
beginning with ``deckhand/`` or ``metadata/`` are allowed. The
|
|
``metadata.name`` field of each ``DataSchema`` document references the
|
|
top-level ``schema`` of :ref:`application-documents`: when there is a match
|
|
between both values, the ``data`` section of all :ref:`application-documents`
|
|
is validated against the JSON schema found in the matching ``DataSchema``
|
|
document.
|
|
|
|
The JSON schema definition is found in the ``data`` key of each ``DataSchema``
|
|
document. The entire ``data`` section of the target document is validated.
|
|
|
|
The following is an example of a sample ``DataSchema`` document, whose ``data``
|
|
section features a simplistic JSON schema:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
# This specifies the official JSON schema meta-schema.
|
|
schema: deckhand/DataSchema/v1
|
|
metadata:
|
|
schema: metadata/Control/v1
|
|
name: promenade/Node/v1 # Specifies the documents to be used for validation.
|
|
labels:
|
|
application: promenade
|
|
data: # Valid JSON Schema is expected here.
|
|
$schema: http://blah
|
|
properties:
|
|
foo:
|
|
enum:
|
|
- bar
|
|
- baz
|
|
- qux
|
|
required:
|
|
- foo
|
|
...
|
|
|
|
The JSON schema abvove requires that the ``data`` section of
|
|
:ref:`application-documents` that match this ``DataSchema`` have a property
|
|
called ``foo`` whose value must be one of: "bar", "baz", or "qux".
|
|
|
|
Reference the `JSON schema`_ documentation for more information on writing
|
|
correct schemas.
|
|
|
|
.. _JSON schema: http://json-schema.org
|
|
|
|
LayeringPolicy
|
|
^^^^^^^^^^^^^^
|
|
|
|
Only one ``LayeringPolicy`` document can exist within the system at any time.
|
|
It is an error to attempt to insert a new ``LayeringPolicy`` document if it has
|
|
a different ``metadata.name`` than the existing document. If the names match,
|
|
it is treated as an update to the existing document.
|
|
|
|
.. note::
|
|
|
|
In order to create a new ``LayeringPolicy`` document in Deckhand, submit
|
|
an **empty** payload via ``PUT /buckets/{bucket_name}/documents``. Afterward,
|
|
submit another request containing the new batch of documents, including
|
|
the new ``LayeringPolicy``.
|
|
|
|
This document defines the strict order in which documents are merged together
|
|
from their component parts. It should result in a validation error if a
|
|
document refers to a layer not specified in the ``LayeringPolicy``.
|
|
|
|
Below is an example of a ``LayeringPolicy`` document:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/LayeringPolicy/v1
|
|
metadata:
|
|
schema: metadata/Control/v1
|
|
name: layering-policy
|
|
data:
|
|
layerOrder:
|
|
- global
|
|
- site-type
|
|
- region
|
|
- site
|
|
- force
|
|
...
|
|
|
|
In the ``LayeringPolicy`` above, a 5-tier ``layerOrder`` is created, in which
|
|
the topmost layer is ``global`` and the bottommost layer is ``force``. This
|
|
means that ``global`` constitutes the "base" layer onto which other documents
|
|
belonging to sub-layers can be layered. In practice, this means that
|
|
documents with ``site-type`` can layer with documents with ``global`` and
|
|
documents with ``region`` can layer with documents with ``site-type``, etc.
|
|
|
|
Note that in the absence of any document belonging to an "intermediate" layer,
|
|
base layers can layer with "interspersed" sub-layers, no matter the number of
|
|
layers between them. This means that a document with layer ``force`` could
|
|
layer with a document with layer ``global``, *provided* no document exists
|
|
with a layer of ``site-type``, ``region``, or ``site``. For more information
|
|
about document layering, reference the :ref:`layering` documentation.
|
|
|
|
ValidationPolicy
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Unlike ``LayeringPolicy``, many ``ValidationPolicy`` documents are allowed. This
|
|
allows services to check whether a particular revision (described below) of
|
|
documents meets a configurable set of validations without having to know up
|
|
front the complete list of validations.
|
|
|
|
Each validation ``name`` specified here is a reference to data that is POSTable
|
|
by other services. Names beginning with ``deckhand`` are reserved for internal
|
|
use. See the Validation section below for more details.
|
|
|
|
Since validations may indicate interactions with external and changing
|
|
circumstances, an optional ``expiresAfter`` key may be specified for each
|
|
validation as an ISO8601 duration. If no ``expiresAfter`` is specified, a
|
|
successful validation does not expire. Note that expirations are specific to
|
|
the combination of ``ValidationPolicy`` and validation, not to each validation
|
|
by itself.
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/ValidationPolicy/v1
|
|
metadata:
|
|
schema: metadata/Control/v1
|
|
name: site-deploy-ready
|
|
data:
|
|
validations:
|
|
- name: deckhand-schema-validation
|
|
- name: drydock-site-validation
|
|
expiresAfter: P1W
|
|
- name: promenade-site-validation
|
|
expiresAfter: P1W
|
|
- name: armada-deployability-validation
|
|
...
|
|
|
|
Provided Utility Document Kinds
|
|
-------------------------------
|
|
|
|
These are documents that use the ``Document`` metadata schema, but live in the
|
|
``deckhand`` namespace.
|
|
|
|
Certificate
|
|
^^^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/Certificate/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-api
|
|
storagePolicy: cleartext
|
|
data: |-
|
|
-----BEGIN CERTIFICATE-----
|
|
MIIDYDCCAkigAwIBAgIUKG41PW4VtiphzASAMY4/3hL8OtAwDQYJKoZIhvcNAQEL
|
|
...snip...
|
|
P3WT9CfFARnsw2nKjnglQcwKkKLYip0WY2wh3FE7nrQZP6xKNaSRlh6p2pCGwwwH
|
|
HkvVwA==
|
|
-----END CERTIFICATE-----
|
|
...
|
|
|
|
CertificateAuthority
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/CertificateAuthority/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-ca
|
|
storagePolicy: cleartext
|
|
data: some-ca
|
|
...
|
|
|
|
CertificateAuthorityKey
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/CertificateAuthorityKey/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-ca-key
|
|
storagePolicy: encrypted
|
|
data: |-
|
|
-----BEGIN CERTIFICATE-----
|
|
MIIDYDCCAkigAwIBAgIUKG41PW4VtiphzASAMY4/3hL8OtAwDQYJKoZIhvcNAQEL
|
|
...snip...
|
|
P3WT9CfFARnsw2nKjnglQcwKkKLYip0WY2wh3FE7nrQZP6xKNaSRlh6p2pCGwwwH
|
|
HkvVwA==
|
|
-----END CERTIFICATE-----
|
|
...
|
|
|
|
CertificateKey
|
|
^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/CertificateKey/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-api
|
|
storagePolicy: encrypted
|
|
data: |-
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
MIIEpQIBAAKCAQEAx+m1+ao7uTVEs+I/Sie9YsXL0B9mOXFlzEdHX8P8x4nx78/T
|
|
...snip...
|
|
Zf3ykIG8l71pIs4TGsPlnyeO6LzCWP5WRSh+BHnyXXjzx/uxMOpQ/6I=
|
|
-----END RSA PRIVATE KEY-----
|
|
...
|
|
|
|
Passphrase
|
|
^^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/Passphrase/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-admin-password
|
|
storagePolicy: encrypted
|
|
data: some-password
|
|
...
|
|
|
|
PrivateKey
|
|
^^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/PrivateKey/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-private-key
|
|
storagePolicy: encrypted
|
|
data: some-private-key
|
|
...
|
|
|
|
PublicKey
|
|
^^^^^^^^^
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: deckhand/PublicKey/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-public-key
|
|
storagePolicy: cleartext
|
|
data: some-password
|
|
...
|