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
This commit is contained in:
Felipe Monteiro 2018-05-24 11:51:30 -07:00
parent c59f261e03
commit 46c0ec93e3
4 changed files with 128 additions and 72 deletions

3
.gitignore vendored
View File

@ -101,6 +101,9 @@ ENV/
**/_partials.tpl
**/_globals.tpl
# OSX
.DS_STORE
AUTHORS
ChangeLog
etc/armada/armada.conf

View File

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

View File

@ -15,7 +15,7 @@ Operations Guide
guide-configure
guide-troubleshooting
guide-use-armada
validation
documents
exceptions/index
guide-helm-plugin
sampleconf

View File

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