Add armada_state_management spec
The armada_state_management spec outlines changes to armada to track deployment metadata including list of deployments in a deployment target and versions of those deployments. Change-Id: I8ff989848149c3942fdf8e31a81cad5a0f31ead3
This commit is contained in:
Sean Eagan
parent
43b300cdc5
commit
61256e7f57
164
specs/approved/armada_state_management.rst
Normal file
164
specs/approved/armada_state_management.rst
Normal file
@ -0,0 +1,164 @@
|
||||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=======================
|
||||
Armada State Management
|
||||
=======================
|
||||
|
||||
Proposal to enhance armada to track deployment metadata.
|
||||
|
||||
Links
|
||||
=====
|
||||
|
||||
None
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
Armada does not currently track the following deployment metadata:
|
||||
|
||||
- List of deployments in a deployment target.
|
||||
- Versions of those deployments (one for each manifest application).
|
||||
|
||||
This spec is limited to state management, and doesn't include any API or CLI
|
||||
extensions to inspect it, or otherwise take advantage of it.
|
||||
|
||||
For example, some potential API's to inspect a deployment target, based on
|
||||
``helm`` precedent, would be:
|
||||
|
||||
- ``armada ls``
|
||||
- ``armada get <manifest>``
|
||||
- ``armada get releases <manifest>``
|
||||
- ``armada get manifest <manifest>``
|
||||
- ``armada history <manifest>``
|
||||
- ``armada status <manifest>``
|
||||
|
||||
Storing the rendered armada documents used in a given version would also allow
|
||||
for rollback functionality to be added.
|
||||
|
||||
The ``release_prefix`` in an armada manifest ought to be unchanged across
|
||||
versions of a deployment, and unique across deployments in a deployment target,
|
||||
so storing this would allow enforcement of these invariants. There are likely
|
||||
other invariants that could be implemented as well.
|
||||
|
||||
If a new manifest application is received while an existing one is still
|
||||
processing, the new one could be either rejected or delayed until the existing
|
||||
one completes.
|
||||
|
||||
Impacted components
|
||||
===================
|
||||
|
||||
Armada
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Two types of objects are defined and stored:
|
||||
|
||||
- ReleaseGroup
|
||||
- ReleaseGroup Version
|
||||
|
||||
These objects are similar to the state management objects used in `helm v3`_.
|
||||
|
||||
ReleaseGroup
|
||||
------------
|
||||
|
||||
This is a `ConfigMap`_. It represents the entire lifecycle of a
|
||||
deployment of a group of releases via a given armada manifest.
|
||||
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| key | type | description |
|
||||
+==================================+=========+========================================================================+
|
||||
| ``metadata.name`` | array | ``releasegroup-`` + ``metadata.name`` of the deployed armada manifest. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``data.version`` | array | The currently (potentially partially) applied ReleaseGroup Version. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``data.release_prefix`` | array | The ``data.release_prefix`` of the armada manifest. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
|
||||
ReleaseGroup Version
|
||||
--------------------
|
||||
|
||||
This is a `Secret`_. It represents a version of a deployment of a group of
|
||||
releases via a given armada manifest.
|
||||
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| key | type | description |
|
||||
+==================================+=========+========================================================================+
|
||||
| ``metadata.name`` | array | Concatenation of ``releasegroup`` and ``version`` from below. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``metadata.labels.releasegroup`` | string | The ``metadata.name`` of the ReleaseGroup. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``metadata.labels.version`` | string | The ULID_ of the version. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``data.releases`` | array | A list of release objects deployed by this release group version, each |
|
||||
| | | containing the name and version of the release. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``data.documents`` | string | A YAML blob containing the rendered documents. |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
| ``data.status`` | string | Status of the deployment. Potential values could be UNKNOWN, DEPLOYED, |
|
||||
| | | SUPERCEDED, DELETED (based on ``helm status`` precedent). |
|
||||
+----------------------------------+---------+------------------------------------------------------------------------+
|
||||
|
||||
State Management
|
||||
----------------
|
||||
|
||||
When an armada apply occurs and passes validation, the ``metadata.name`` of its
|
||||
manifest is inspected and if no existing ``ReleaseGroup`` is found with a
|
||||
matching name, then one is created.
|
||||
|
||||
Then, a ReleaseGroup version is created, and assigned as the current version in
|
||||
the ReleaseGroup object. It's status is initialized to ``UNKNOWN``, and updated
|
||||
to ``DEPLOYED`` upon manifest application completion. It is then set to
|
||||
``SUPERCEDED`` once a new version is created.
|
||||
|
||||
A deployment's objects are deleted during an armada delete operation.
|
||||
|
||||
Namespacing
|
||||
-----------
|
||||
|
||||
These objects are stored in the ``kube-system`` namespace.
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
As with any Secrets, it may be desired to `configure encryption`_.
|
||||
|
||||
Performance impact
|
||||
------------------
|
||||
|
||||
The impact of the kubernetes API calls to manage and retrieve these objects
|
||||
should be negligible.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
For ReleaseGroup, ConfigMap was chosen over CustomResourceDefinition_ for
|
||||
simplicity, for example to avoid having to initialize the
|
||||
CustomResourceDefinition object, and since none of the features of
|
||||
CustomResourceDefinition seem to be necessary.
|
||||
|
||||
For ReleaseGroup Version, Secret was chosen over ConfigMap to secure any
|
||||
sensitive data included in the override values included in the deployment.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
None - there are no specific milestones identified for this blueprint.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
.. _ULID: https://github.com/ulid/spec
|
||||
.. _Secret: https://kubernetes.io/docs/concepts/configuration/secret/
|
||||
.. _CustomResourceDefinition: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
|
||||
.. _`configure encryption`: https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/
|
||||
.. _`helm v3`: https://github.com/helm/community/blob/master/helm-v3/003-state.md
|
||||
Loading…
Reference in New Issue
Block a user