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
parent
c59f261e03
commit
46c0ec93e3
3
.gitignore
vendored
3
.gitignore
vendored
@ -101,6 +101,9 @@ ENV/
|
||||
**/_partials.tpl
|
||||
**/_globals.tpl
|
||||
|
||||
# OSX
|
||||
.DS_STORE
|
||||
|
||||
AUTHORS
|
||||
ChangeLog
|
||||
etc/armada/armada.conf
|
||||
|
||||
124
doc/source/operations/documents.rst
Normal file
124
doc/source/operations/documents.rst
Normal 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.
|
||||
@ -15,7 +15,7 @@ Operations Guide
|
||||
guide-configure
|
||||
guide-troubleshooting
|
||||
guide-use-armada
|
||||
validation
|
||||
documents
|
||||
exceptions/index
|
||||
guide-helm-plugin
|
||||
sampleconf
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user