Pegleg Document Types¶

Overview¶

Pegleg is not only the custodian of deployment manifests that handles responsibilities such as aggregation and linting, but is also the author of certain Deckhand-formatted manifests. These manifests are generated via Catalog classes.

Documents¶

Pegleg generates or ingests each of the documents below, each identified by its schema.

`pegleg/PeglegManagedDocument/v1`¶

Pegleg both generates and ingests this type of document. A PeglegManagedDocument can have one or both of the following data elements:

generated
encrypted

A PeglegManagedDocument serves as a wrapper around other documents, and the wrapping serves to capture additional metadata that is necessary, but separate from the managed document proper.

The managed document data lives in the data.managedDocument portion of a PeglegManagedDocument.

Generated¶

If a PeglegManagedDocument is generated, then its contents have been created by Pegleg, and it thus includes provenance information per this example:

schema: pegleg/PeglegManagedDocument/v1
metadata:
  name: matches-document-name
  schema: deckhand/Document/v1
  labels:
    matching: wrapped-doc
  layeringDefinition:
    abstract: true
    # Pegleg will initially support generation at site level only
    layer: site
  storagePolicy: encrypted
data:
  generated:
    at: <timestamp>
    by: <author>
    specifiedBy:
      repo: <...>
      reference: <git ref-head or similar>
      path: <PKICatalog/PassphraseCatalog details>
  managedDocument:
    schema: <as appropriate for wrapped document>
    metadata:
      storagePolicy: encrypted
      schema: <as appropriate for wrapped document>
      <metadata from parent PeglegManagedDocument>
      <any other metadata as appropriate>
    data: <generated data>

Encrypted¶

If a PeglegManagedDocument is encrypted, then its contents have been encrypted by Pegleg, and it thus includes provenance information per this example:

schema: pegleg/PeglegManagedDocument/v1
metadata:
  name: matches-document-name
  schema: deckhand/Document/v1
  labels:
    matching: wrapped-doc
  layeringDefinition:
    abstract: false
    layer: matching-wrapped-doc
  storagePolicy: encrypted
data:
  encrypted:
    at: <timestamp>
    by: <author>
  managedDocument:
    schema: <as appropriate for wrapped document>
    metadata:
      storagePolicy: encrypted
      schema: <as appropriate for wrapped document>
      <metadata from parent PeglegManagedDocument>
      <any other metadata as appropriate>
    data: <encrypted string blob>

Note that this encrypted has a different purpose than the Deckhand storagePolicy: encrypted metadata, which indicates an intent for Deckhand to store a document encrypted at rest in the cluster. The two can be used together to ensure security. If a document is marked as storagePolicy: encrypted, then automation may validate that it is only persisted (e.g. to a Git repository) if it is in fact encrypted within a PeglegManagedDocument.

Generated & Encrypted¶

A PeglegManagedDocument that is both generated via a Catalog, and encrypted (as specified by the Catalog) will contain both generated and encrypted stanzas.

Supported Managed Documents¶

Supported managed document schemas include one of the following Deckhand schemas:

Certificates:
- deckhand/Certificate/v1
- deckhand/CertificateKey/v1
Certificate Authorities:
- deckhand/CertificateAuthority/v1
- deckhand/CertificateAuthorityKey/v1
Keypairs:
- deckhand/PrivateKey/v1
- deckhand/PublicKey/v1