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
|
**/_partials.tpl
|
||||||
**/_globals.tpl
|
**/_globals.tpl
|
||||||
|
|
||||||
|
# OSX
|
||||||
|
.DS_STORE
|
||||||
|
|
||||||
AUTHORS
|
AUTHORS
|
||||||
ChangeLog
|
ChangeLog
|
||||||
etc/armada/armada.conf
|
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-configure
|
||||||
guide-troubleshooting
|
guide-troubleshooting
|
||||||
guide-use-armada
|
guide-use-armada
|
||||||
validation
|
documents
|
||||||
exceptions/index
|
exceptions/index
|
||||||
guide-helm-plugin
|
guide-helm-plugin
|
||||||
sampleconf
|
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…
x
Reference in New Issue
Block a user