From 46c0ec93e3eceefab02d3c02d94ef51f009e694c Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Thu, 24 May 2018 11:51:30 -0700 Subject: [PATCH] Add documentation on Armada documents This patchset adds documentation on the 3 Armada documents (Charts, Chart Groups and Manifests). A brief introduction is given on each document type. In a follow-up documentation on authoring patterns (how to use the 3 types of Armada documents) will be added. Change-Id: I41bd9c9107b083a2e231e4aae61f70798e86cd3c --- .gitignore | 3 + doc/source/operations/documents.rst | 124 +++++++++++++++++++++++++++ doc/source/operations/index.rst | 2 +- doc/source/operations/validation.rst | 71 --------------- 4 files changed, 128 insertions(+), 72 deletions(-) create mode 100644 doc/source/operations/documents.rst delete mode 100644 doc/source/operations/validation.rst diff --git a/.gitignore b/.gitignore index 2ea4403e..e8e34227 100644 --- a/.gitignore +++ b/.gitignore @@ -101,6 +101,9 @@ ENV/ **/_partials.tpl **/_globals.tpl +# OSX +.DS_STORE + AUTHORS ChangeLog etc/armada/armada.conf diff --git a/doc/source/operations/documents.rst b/doc/source/operations/documents.rst new file mode 100644 index 00000000..7ab083d9 --- /dev/null +++ b/doc/source/operations/documents.rst @@ -0,0 +1,124 @@ +.. + 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. + +.. _armada-documents: + +Armada Documents +================ + +Below are the schemas Armada uses to validate :ref:`Charts`, +:ref:`Chart Groups`, and :ref:`Manifests`. + +.. _Charts: + +Charts +------ + +Charts consist of the smallest building blocks in Armada. A ``Chart`` is +comparable to a Helm chart. Charts consist of all the labels, dependencies, +install and upgrade information, hooks and additional information needed to +convey to Tiller. + +.. _Chart Groups: + +Chart Groups +------------ + +A ``Chart Group`` consists of a list of charts. ``Chart Group`` documents are +useful for managing a group of ``Chart`` documents together. + +.. _Manifests: + +Manifests +--------- + +A ``Manifest`` is the largest building block in Armada. ``Manifest`` documents +are responsible for managing collections of ``Chart Group`` documents. + +Validation Schemas +------------------ + +Introduction +^^^^^^^^^^^^ + +All schemas below are `Deckhand DataSchema`_ documents, which are essentially +JSON schemas, with additional metadata useful for Deckhand to perform +`layering`_ and `substitution`_. + +The validation schemas below are used by Armada to validate all ingested +Charts, Chart Groups, and Manifests. Use the schemas below as models for +authoring Armada documents. + +.. _Deckhand DataSchema: https://deckhand.readthedocs.io/en/latest/document-types.html?highlight=dataschema#dataschema +.. _Helm charts: https://docs.helm.sh/developing_charts/ +.. _layering: https://deckhand.readthedocs.io/en/latest/layering.html +.. _substitution: https://deckhand.readthedocs.io/en/latest/substitution.html + +Schemas +^^^^^^^ + +* ``Chart`` schema. + + JSON schema against which all documents with ``armada/Chart/v1`` + ``metadata.name`` are validated. + + .. literalinclude:: + ../../../armada/schemas/armada-chart-schema.yaml + :language: yaml + :lines: 15- + :caption: Schema for ``armada/Chart/v1`` documents. + + This schema is used to sanity-check all ``Chart`` documents that are passed + to Armada. + +* ``Chart Group`` schema. + + JSON schema against which all documents with ``armada/Chart/v1`` + ``metadata.name`` are validated. + + .. literalinclude:: + ../../../armada/schemas/armada-chartgroup-schema.yaml + :language: yaml + :lines: 15- + :caption: Schema for ``armada/ChartGroup/v1`` documents. + + This schema is used to sanity-check all ``Chart Group`` documents that are + passed to Armada. + +* ``Manifest`` schema. + + JSON schema against which all documents with ``armada/Manifest/v1`` + ``metadata.name`` are validated. + + .. literalinclude:: + ../../../armada/schemas/armada-manifest-schema.yaml + :language: yaml + :lines: 15- + :caption: Schema for ``armada/Manifest/v1`` documents. + + This schema is used to sanity-check all ``Manifest`` documents that are passed + to Armada. + +.. _authoring-guidelines: + +Authoring Guidelines +-------------------- + +All Armada documents must use the ``deckhand/DataSchema/v1`` schema. + +.. todo:: + + Expand on this section. diff --git a/doc/source/operations/index.rst b/doc/source/operations/index.rst index b1a7ff65..26363c83 100644 --- a/doc/source/operations/index.rst +++ b/doc/source/operations/index.rst @@ -15,7 +15,7 @@ Operations Guide guide-configure guide-troubleshooting guide-use-armada - validation + documents exceptions/index guide-helm-plugin sampleconf diff --git a/doc/source/operations/validation.rst b/doc/source/operations/validation.rst deleted file mode 100644 index 17ba2789..00000000 --- a/doc/source/operations/validation.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. - 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. - -.. _validation: - -=================== -Document Validation -=================== - -Validations -=========== - -Armada, like other UCP components, uses ``jsonschema`` to validate documents -passed to it. This includes dedicated schemas for ``Chart``, ``ChartGroup`` -and ``Manifest``. - -Validation Schemas -================== - -Below are the schemas Armada uses to validate documents. - -Armada Schemas --------------- - -* Chart schema. - - Chart schema against which all Armada ``Chart`` documents are validated. - - .. literalinclude:: ../../../armada/schemas/armada-chart-schema.yaml - :language: yaml - :lines: 15- - :caption: Armada Chart schema. - - This schema is used to sanity-check all ``Chart`` documents. - -* ChartGroup schema. - - ChartGroup schema against which all Armada ``ChartGroup`` documents are - validated. - - .. literalinclude:: ../../../armada/schemas/armada-chartgroup-schema.yaml - :language: yaml - :lines: 15- - :caption: Armada ChartGroup schema. - - This schema is used to sanity-check all ``ChartGroup`` documents. - -* Manifest schema. - - Manifest schema against which all Armada ``Manifest`` documents are - validated. - - .. literalinclude:: ../../../armada/schemas/armada-manifest-schema.yaml - :language: yaml - :lines: 15- - :caption: Armada Manifest schema. - - This schema is used to sanity-check all ``Manifest`` documents.