592 lines
22 KiB
ReStructuredText
592 lines
22 KiB
ReStructuredText
..
|
|
Copyright 2019 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.
|
|
|
|
.. _document_authoring_v1:
|
|
|
|
v1 Authoring
|
|
============
|
|
|
|
armada/Manifest/v1
|
|
------------------
|
|
|
|
+---------------------+--------+----------------------+
|
|
| keyword | type | action |
|
|
+=====================+========+======================+
|
|
| ``release_prefix`` | string | appends to the |
|
|
| | | front of all |
|
|
| | | charts |
|
|
| | | released |
|
|
| | | by the |
|
|
| | | manifest in |
|
|
| | | order to |
|
|
| | | manage releases |
|
|
| | | throughout their |
|
|
| | | lifecycle |
|
|
+---------------------+--------+----------------------+
|
|
| ``chart_groups`` | array | references |
|
|
| | | ChartGroup document |
|
|
| | | of all groups |
|
|
| | | |
|
|
+---------------------+--------+----------------------+
|
|
|
|
Manifest Example
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
---
|
|
schema: armada/Manifest/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: simple-armada
|
|
data:
|
|
release_prefix: armada
|
|
chart_groups:
|
|
- chart_group
|
|
|
|
|
|
armada/ChartGroup/v1
|
|
--------------------
|
|
|
|
+-----------------+----------+------------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=================+==========+========================================================================+
|
|
| description | string | description of chart set |
|
|
+-----------------+----------+------------------------------------------------------------------------+
|
|
| chart_group | array | reference to chart document |
|
|
+-----------------+----------+------------------------------------------------------------------------+
|
|
| sequenced | bool | enables sequenced chart deployment in a group |
|
|
+-----------------+----------+------------------------------------------------------------------------+
|
|
| test_charts | bool | run pre-defined helm tests in a ChartGroup (DEPRECATED) |
|
|
+-----------------+----------+------------------------------------------------------------------------+
|
|
|
|
.. DANGER::
|
|
|
|
DEPRECATION: The ``test_charts`` key will be removed, as Armada will run
|
|
helm tests for all charts by default.
|
|
|
|
|
|
Chart Group Example
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
---
|
|
schema: armada/ChartGroup/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-group
|
|
data:
|
|
description: Deploys Simple Service
|
|
sequenced: False
|
|
chart_group:
|
|
- chart
|
|
- chart
|
|
|
|
armada/Chart/v1
|
|
---------------
|
|
|
|
.. DANGER::
|
|
|
|
DEPRECATION: ``timeout`` key-value will be removed timeout will be defined
|
|
under ``wait`` object.
|
|
|
|
|
|
Chart
|
|
^^^^^
|
|
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=================+==========+=======================================================================================+
|
|
| chart\_name | string | name for the chart |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| release | string | name of the release (Armada will prepend with ``release-prefix`` during processing) |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| namespace | string | namespace of your chart |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| wait | object | See `Wait`_. |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| protected | object | do not delete FAILED releases when encountered from previous run (provide the |
|
|
| | | 'continue_processing' bool to continue or halt execution (default: halt)) |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| test | object | See Test_. |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| install | object | install the chart into your Kubernetes cluster |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| upgrade | object | upgrade the chart managed by the armada yaml |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| delete | object | See Delete_. |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| values | object | override any default values in the charts |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| source | object | provide a path to a ``git repo``, ``local dir``, or ``tarball url`` chart |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| dependencies | object | reference any chart dependencies before install |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
| timeout | int | time (in seconds) allotted for chart to deploy when 'wait' flag is set (DEPRECATED) |
|
|
+-----------------+----------+---------------------------------------------------------------------------------------+
|
|
|
|
Wait
|
|
^^^^
|
|
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+====================================================================+
|
|
| timeout | int | time (in seconds) to wait for chart to deploy |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| resources | array | Array of `Wait Resource`_ to wait on, with ``labels`` added to each|
|
|
| | | item. Defaults to pods and jobs (if any exist) matching ``labels``.|
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| labels | object | Base mapping of labels to wait on. They are added to any labels in |
|
|
| | | each item in the ``resources`` array. |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| native | boolean | See `Wait Native`_. |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
|
|
Wait Resource
|
|
^^^^^^^^^^^^^
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+====================================================================+
|
|
| type | string | k8s resource type, supports: controllers ('deployment', |
|
|
| | | 'daemonset', 'statefulset'), 'pod', 'job' |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| labels | object | mapping of kubernetes resource labels |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| min\_ready | int | Only for controller ``type``s. Amount of pods in a controller |
|
|
| | string | which must be ready. Can be integer or percent string e.g. ``80%``.|
|
|
| | | Default ``100%``. |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
|
|
Wait Native
|
|
^^^^^^^^^^^
|
|
|
|
Config for the native ``helm (install|upgrade) --wait`` flag.
|
|
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+====================================================================+
|
|
| enabled | boolean | defaults to true |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
|
|
Test
|
|
^^^^
|
|
|
|
Run helm tests on the chart after install/upgrade.
|
|
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+====================================================================+
|
|
| enabled | bool | whether to enable/disable helm tests for this chart (default True) |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| timeout | int | time (in sec) to wait for completion of Helm tests. Default 300. |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
| options | object | See `Test Options`_. |
|
|
+-------------+----------+--------------------------------------------------------------------+
|
|
|
|
.. note::
|
|
|
|
Armada will attempt to run helm tests by default. They may be disabled by
|
|
setting the ``enabled`` key to ``False``.
|
|
|
|
.. DANGER::
|
|
|
|
DEPRECATION: In addition to an object with the above fields, the ``test``
|
|
key currently also supports ``bool``, which maps to ``enabled``, but this is
|
|
deprecated and will be removed. The ``cleanup`` option below is set to true
|
|
in this case for backward compatibility.
|
|
|
|
Test Options
|
|
^^^^^^^^^^^^
|
|
|
|
Test options to pass through directly to helm.
|
|
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+===============================================================+
|
|
| cleanup | bool | cleanup test pods after test completion, defaults to false |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
|
|
.. note::
|
|
|
|
If cleanup is ``true`` this prevents being able to debug a test in the event of failure.
|
|
|
|
Historically, the preferred way to achieve test cleanup has been to add a pre-upgrade delete
|
|
action on the test pod.
|
|
|
|
This still works, however it is usually no longer necessary as Armada now automatically
|
|
cleans up any test pods which match the ``wait.labels`` of the chart, immediately before
|
|
running tests. Similar suggestions have been made for how ``helm test --cleanup`` itself
|
|
ought to work (https://github.com/helm/helm/issues/3279).
|
|
|
|
Upgrade - Pre
|
|
^^^^^^^^^^^^^
|
|
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+===============================================================+
|
|
| pre | object | actions performed prior to updating a release |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
|
|
Upgrade - Actions
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+===============================================================+
|
|
| update | object | update daemonsets in pre-upgrade update actions |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| delete | sequence | delete jobs and pods in pre-upgrade delete actions |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
|
|
Upgrade - Actions - Update/Delete
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+===============================================================+
|
|
| name | string | name of action |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| type | string | type of Kubernetes workload to execute in scope for action |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
| labels | object | k:v mapping of labels to select Kubernetes resources |
|
|
+-------------+----------+---------------------------------------------------------------+
|
|
|
|
.. note::
|
|
|
|
Update Actions only support type: 'daemonset'
|
|
|
|
.. note::
|
|
|
|
Delete Actions support type: 'pod', 'job', 'cronjob'
|
|
|
|
Chart Example
|
|
^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-1
|
|
data:
|
|
chart_name: blog-1
|
|
release: blog-1
|
|
namespace: default
|
|
wait:
|
|
timeout: 100
|
|
protected:
|
|
continue_processing: false
|
|
test:
|
|
enabled: true
|
|
install:
|
|
no_hooks: false
|
|
upgrade:
|
|
no_hooks: false
|
|
pre:
|
|
update:
|
|
- name: test-daemonset
|
|
type: daemonset
|
|
labels:
|
|
foo: bar
|
|
component: bar
|
|
rak1: enabled
|
|
delete:
|
|
- name: test-job
|
|
type: job
|
|
labels:
|
|
foo: bar
|
|
component: bar
|
|
rak1: enabled
|
|
values: {}
|
|
source:
|
|
type: git
|
|
location: https://github.com/namespace/repo
|
|
subpath: .
|
|
reference: master
|
|
dependencies: []
|
|
|
|
Delete
|
|
^^^^^^
|
|
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+===================================================================================+
|
|
| timeout | integer | time (in seconds) to wait for chart to be deleted |
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
|
|
Source
|
|
^^^^^^
|
|
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
| keyword | type | action |
|
|
+=============+==========+===================================================================================+
|
|
| type | string | source to build the chart: ``git``, ``local``, or ``tar`` |
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
| location | string | ``url`` or ``path`` to the chart's parent directory |
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
| subpath | string | (optional) relative path to target chart from parent (``.`` if not specified) |
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
| reference | string | (optional) branch, commit, or reference in the repo (``master`` if not specified) |
|
|
+-------------+----------+-----------------------------------------------------------------------------------+
|
|
|
|
Source Example
|
|
^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
# type git
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-1
|
|
data:
|
|
chart_name: blog-1
|
|
release: blog-1
|
|
namespace: default
|
|
wait:
|
|
timeout: 100
|
|
labels:
|
|
component: blog
|
|
install:
|
|
no_hooks: false
|
|
upgrade:
|
|
no_hooks: false
|
|
values: {}
|
|
source:
|
|
type: git
|
|
location: https://github.com/namespace/repo
|
|
subpath: .
|
|
reference: master
|
|
dependencies: []
|
|
|
|
# type local
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-1
|
|
data:
|
|
chart_name: blog-1
|
|
release: blog-1
|
|
namespace: default
|
|
wait:
|
|
timeout: 100
|
|
install:
|
|
no_hooks: false
|
|
upgrade:
|
|
no_hooks: false
|
|
values: {}
|
|
source:
|
|
type: local
|
|
location: /path/to/charts
|
|
subpath: chart
|
|
reference: master
|
|
dependencies: []
|
|
|
|
# type tar
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-1
|
|
data:
|
|
chart_name: blog-1
|
|
release: blog-1
|
|
namespace: default
|
|
wait:
|
|
timeout: 100
|
|
install:
|
|
no_hooks: false
|
|
upgrade:
|
|
no_hooks: false
|
|
values: {}
|
|
source:
|
|
type: tar
|
|
location: https://localhost:8879/charts/chart-0.1.0.tgz
|
|
subpath: mariadb
|
|
reference: null
|
|
dependencies: []
|
|
|
|
|
|
|
|
|
|
|
|
Defining a Manifest
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
To define your Manifest you need to define a ``armada/Manifest/v1`` document,
|
|
``armada/ChartGroup/v1`` document, ``armada/Chart/v1``.
|
|
Following the definitions above for each document you will be able to construct
|
|
an armada manifest.
|
|
|
|
Armada - Deploy Behavior
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
1. Armada will perform set of pre-flight checks to before applying the manifest
|
|
- validate input manifest
|
|
- check tiller service is Running
|
|
- check chart source locations are valid
|
|
|
|
2. Deploying Armada Manifest
|
|
|
|
1. If the chart is not found
|
|
|
|
- we will install the chart
|
|
|
|
|
|
3. If exist then
|
|
|
|
- Armada will check if there are any differences in the chart
|
|
- if the charts are different then it will execute an upgrade
|
|
- else it will not perform any actions
|
|
|
|
.. note::
|
|
|
|
You can use references in order to build your charts, this will reduce
|
|
the size of the chart definition will show example in multichart below
|
|
|
|
Simple Example
|
|
^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-1
|
|
data:
|
|
chart_name: blog-1
|
|
release: blog-1
|
|
namespace: default
|
|
values: {}
|
|
source:
|
|
type: git
|
|
location: https://github.com/namespace/repo
|
|
subpath: blog-1
|
|
reference: new-feat
|
|
dependencies: []
|
|
---
|
|
schema: armada/ChartGroup/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-group
|
|
data:
|
|
description: Deploys Simple Service
|
|
sequenced: False
|
|
chart_group:
|
|
- blog-1
|
|
---
|
|
schema: armada/Manifest/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: simple-armada
|
|
data:
|
|
release_prefix: armada
|
|
chart_groups:
|
|
- blog-group
|
|
|
|
Multichart Example
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-1
|
|
data:
|
|
chart_name: blog-1
|
|
release: blog-1
|
|
namespace: default
|
|
values: {}
|
|
source:
|
|
type: git
|
|
location: https://github.com/namespace/repo
|
|
subpath: blog1
|
|
reference: master
|
|
dependencies: []
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-2
|
|
data:
|
|
chart_name: blog-2
|
|
release: blog-2
|
|
namespace: default
|
|
values: {}
|
|
source:
|
|
type: tar
|
|
location: https://github.com/namespace/repo/blog2.tgz
|
|
subpath: blog2
|
|
dependencies: []
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-3
|
|
data:
|
|
chart_name: blog-3
|
|
release: blog-3
|
|
namespace: default
|
|
values: {}
|
|
source:
|
|
type: local
|
|
location: /home/user/namespace/repo/blog3
|
|
dependencies: []
|
|
---
|
|
schema: armada/ChartGroup/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-group-1
|
|
data:
|
|
description: Deploys Simple Service
|
|
sequenced: False
|
|
chart_group:
|
|
- blog-2
|
|
---
|
|
schema: armada/ChartGroup/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: blog-group-2
|
|
data:
|
|
description: Deploys Simple Service
|
|
sequenced: False
|
|
chart_group:
|
|
- blog-1
|
|
- blog-3
|
|
---
|
|
schema: armada/Manifest/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: simple-armada
|
|
data:
|
|
release_prefix: armada
|
|
chart_groups:
|
|
- blog-group-1
|
|
- blog-group-2
|
|
|
|
References
|
|
~~~~~~~~~~
|
|
|
|
For working examples please check the examples in our repo
|
|
`here <https://opendev.org/airship/armada/src/branch/master/examples>`__.
|