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