From b598e850ccb8e78284dcab16ebd80de16391df5b Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Thu, 7 Feb 2019 12:31:39 -0600 Subject: [PATCH] pki: Add documentation for PKI implementation This adds documentation for the PKI implementation in Pegleg that was recently ported from Promenade. Change-Id: I248ec62a0c3523fc5f3950a6a678cf6d998b093a --- doc/source/cli/cli.rst | 46 +++++---- doc/source/index.rst | 1 + doc/source/pki/document-types.rst | 161 ++++++++++++++++++++++++++++++ doc/source/pki/index.rst | 35 +++++++ doc/source/pki/pki.rst | 52 ++++++++++ 5 files changed, 273 insertions(+), 22 deletions(-) create mode 100644 doc/source/pki/document-types.rst create mode 100644 doc/source/pki/index.rst create mode 100644 doc/source/pki/pki.rst diff --git a/doc/source/cli/cli.rst b/doc/source/cli/cli.rst index 63477d0e..dd0f2656 100644 --- a/doc/source/cli/cli.rst +++ b/doc/source/cli/cli.rst @@ -59,7 +59,7 @@ For example: .. code-block:: console cd /opt/airship-pegleg - export WORKSPACE=/opt/airship-treasuremap + export WORKSPACE=/opt/airship/treasuremap ./tools/pegleg.sh site -r /workspace --help .. note:: @@ -71,7 +71,7 @@ For example: .. code-block:: console cd /opt/airship-pegleg - export WORKSPACE=/opt/airship-treasuremap + export WORKSPACE=/opt/airship/treasuremap sudo -E ./tools/pegleg.sh site -r /workspace --help CLI Options @@ -95,23 +95,23 @@ Options Path to the root of the site repository (containing site_definition.yaml) repo. -For example: /opt/airship-treasuremap +For example: /opt/airship/treasuremap The revision can also be specified via (for example): :: - -r /opt/airship-treasuremap@revision + -r /opt/airship/treasuremap@revision **-p / --clone-path** (Optional, Default=/tmp/). -The path where the repo will be cloned. If this option is included and the -repo already exists, then the repo will not be cloned again and the user must -specify a new clone path or pass in the local copy of the repository as the -site repository. Suppose the repo name is airship-treasuremap and the clone -path is /tmp/mypath then the following directory is created -/tmp/mypath/airship-treasuremap which will contain the contents of the repo. -Example of using clone path: +The path where the repo will be cloned. By default the repo will be cloned to +the /tmp path. If this option is included and the repo already exists, then the +repo will not be cloned again and the user must specify a new clone path or +pass in the local copy of the repository as the site repository. Suppose the +repo name is ``treasuremap`` and the clone path is ``/tmp/mypath`` then the +following directory is created ``/tmp/mypath/treasuremap`` which will contain +the contents of the repo. Example of using clone path: :: @@ -145,13 +145,13 @@ Options Path to the root of the site repository (containing site_definition.yaml) repo. -For example: /opt/airship-treasuremap +For example: /opt/airship/treasuremap The revision can also be specified via (for example): :: - -r /opt/airship-treasuremap@revision + -r /opt/airship/treasuremap@revision **-e / --extra-repository** (Optional). @@ -166,13 +166,13 @@ These should be named per the site-definition file, e.g.: **-p / --clone-path** (Optional, Default=/tmp/). -The path where the repo will be cloned. If this option is included and the -repo already exists, then the repo will not be cloned again and the user must -specify a new clone path or pass in the local copy of the repository as the -site repository. Suppose the repo name is airship-treasuremap and the clone -path is /tmp/mypath then the following directory is created -/tmp/mypath/airship-treasuremap which will contain the contents of the repo. -Example of using clone path: +The path where the repo will be cloned. By default the repo will be cloned to +the /tmp path. If this option is included and the repo already exists, then the +repo will not be cloned again and the user must specify a new clone path or +pass in the local copy of the repository as the site repository. Suppose the +repo name is ``treasuremap`` and the clone path is ``/tmp/mypath`` then the +following directory is created ``/tmp/mypath/treasuremap`` which will +contain the contents of the repo. Example of using clone path: :: @@ -443,7 +443,9 @@ Usage: Site Secrets Group ------------------ -Subgroup of :ref:`site-group`. +Subgroup of :ref:`site-group`. The commands below create +:ref:`PeglegManagedDocument manifests ` in the local +repository. A sub-group of site command group, which allows you to perform secrets level operations for secrets documents of a site. @@ -473,7 +475,7 @@ Generate PKI ^^^^^^^^^^^^ Generate certificates and keys according to all PKICatalog documents in the -site using the PKI module. The default behavior is to generate all +site using the :ref:`pki` module. The default behavior is to generate all certificates that are not yet present. For example, the first time generate PKI is run or when new entries are added to the PKICatalogue, only those new entries will be generated on subsequent runs. diff --git a/doc/source/index.rst b/doc/source/index.rst index f86ed6d7..7e8fda6c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -34,6 +34,7 @@ Design artifacts authoring_strategy + pki/index Developer's Guide ----------------- diff --git a/doc/source/pki/document-types.rst b/doc/source/pki/document-types.rst new file mode 100644 index 00000000..e850d766 --- /dev/null +++ b/doc/source/pki/document-types.rst @@ -0,0 +1,161 @@ +.. + Copyright 2018 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. + +.. _pegleg-document-types: + +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. + +.. todo:: + + Provide documentation for what Catalog classes are. + +Documents +--------- + +Pegleg generates or ingests each of the documents below, each identified by +its schema. + +.. _pegleg-managed-document: + +``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: + by: + specifiedBy: + repo: <...> + reference: + path: + managedDocument: + schema: + metadata: + storagePolicy: encrypted + schema: + + + 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: + by: + managedDocument: + schema: + metadata: + storagePolicy: encrypted + schema: + + + data: + +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`` + +.. _Deckhand-formatted: https://airship-deckhand.readthedocs.io/en/latest/users/documents.html +.. _metadata: https://airship-deckhand.readthedocs.io/en/latest/users/encryption.html +.. _Deckhand schemas: https://airship-deckhand.readthedocs.io/en/latest/users/document-types.html#provided-utility-document-kinds diff --git a/doc/source/pki/index.rst b/doc/source/pki/index.rst new file mode 100644 index 00000000..b9a637e5 --- /dev/null +++ b/doc/source/pki/index.rst @@ -0,0 +1,35 @@ +.. + Copyright 2018 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. + +=============== +Secrets Catalog +=============== + +Artifacts +--------- + +.. toctree:: + :maxdepth: 2 + + document-types + +Public Key Infrastructure (PKI) +------------------------------- + +.. toctree:: + :maxdepth: 2 + + pki diff --git a/doc/source/pki/pki.rst b/doc/source/pki/pki.rst new file mode 100644 index 00000000..57beea48 --- /dev/null +++ b/doc/source/pki/pki.rst @@ -0,0 +1,52 @@ +.. + Copyright 2018 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. + +.. _pki: + +Public Key Infrastructure (PKI) Catalog +======================================= + +Configuration for certificate and keypair generation in the cluster. The +``pegleg generate-certs`` command will read all ``PKICatalog`` documents and +either find pre-existing certificates/keys, or generate new ones based on the +given definition. + +Dependencies +------------ + +Pegleg's PKI Catalog depends on `CloudFlare's PKI/TLS toolkit`_, which is +installed as a part of Pegleg's `Dockerfile`_. + +.. _sample-pki-catalog-yaml: + +Sample Document +--------------- + +Here is a sample document: + +.. literalinclude:: ../../../site_yamls/site/pki-catalog.yaml + +Certificate Authorities +----------------------- + +The data in the ``certificate-authorities`` key is used to generate +certificates for each authority and node. + +Each certificate authority requires essential host-specific information for +each node. + +.. _CloudFlare's PKI/TLS toolkit: https://github.com/cloudflare/cfssl +.. _Dockerfile: https://github.com/openstack/airship-pegleg/blob/master/images/pegleg/Dockerfile