From 61256e7f57e7c771d6d17b959871e61c0e21d035 Mon Sep 17 00:00:00 2001 From: Sean Eagan Date: Fri, 27 Jul 2018 09:33:09 -0500 Subject: [PATCH] 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 --- specs/approved/armada_state_management.rst | 164 +++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 specs/approved/armada_state_management.rst diff --git a/specs/approved/armada_state_management.rst b/specs/approved/armada_state_management.rst new file mode 100644 index 0000000..2f48fe1 --- /dev/null +++ b/specs/approved/armada_state_management.rst @@ -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 `` +- ``armada get releases `` +- ``armada get manifest `` +- ``armada history `` +- ``armada status `` + +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