deckhand/doc/source/users/document-types.rst

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 rendering operations:

• encryption
• layering
• substitution
• replacement

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

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:

---
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 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
...