Document Types¶
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 Document Rendering operations:
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 Application Documents are validated and rendered.
Note
Unlike 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 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 Application Documents: when there is a match
between both values, the data
section of all 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:
---
# 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
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.
LayeringPolicy¶
This document defines the strict order in which documents are layered together from their component parts.
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. An error is raised if a document refers to a layer
not specified in the LayeringPolicy
.
Below is an example of a LayeringPolicy
document:
---
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 Document 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.
---
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¶
---
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¶
---
schema: deckhand/CertificateAuthority/v1
metadata:
schema: metadata/Document/v1
name: application-ca
storagePolicy: cleartext
data: some-ca
...
CertificateAuthorityKey¶
---
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¶
---
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¶
---
schema: deckhand/Passphrase/v1
metadata:
schema: metadata/Document/v1
name: application-admin-password
storagePolicy: encrypted
data: some-password
...
PrivateKey¶
---
schema: deckhand/PrivateKey/v1
metadata:
schema: metadata/Document/v1
name: application-private-key
storagePolicy: encrypted
data: some-private-key
...
PublicKey¶
---
schema: deckhand/PublicKey/v1
metadata:
schema: metadata/Document/v1
name: application-public-key
storagePolicy: cleartext
data: some-password
...