From 8064a01c093a7d92e707162efb0d3e31a3cfa926 Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Sat, 3 Jul 2021 00:41:34 -0400 Subject: [PATCH 1/5] Simplification updates - Simplify first line of each principle, for easy memorization. - Swap principles 3 and 4. I think this is what we ultimately wanted to convey. - Swap notes for principles 3 and 4 to match. - Move principle 4 notes to Glossary (Drift and Reconciliation) Signed-off-by: Scott Rigby --- PRINCIPLES.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/PRINCIPLES.md b/PRINCIPLES.md index 2b6f917..455e03c 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -10,32 +10,27 @@ These principles were derived from modern software operations but are rooted in ## Principles -1. **Define state declaratively** +1. **The system's desired state described declaratively** A system managed by GitOps must have its _Desired State_ expressed declaratively as data in a format writable and readable by both humans and machines. -2. **Use immutable, versioned storage** +2. **Declaration change history stored as immutable versions** - _Desired State_ is stored in a way that supports versioning, immutability of versions, and retains a complete version history. + _Desired State_ declarations are stored in a way that supports versioning, immutability of versions, and retains a complete history of changes. -3. **Reconcile state continuously** +3. **System operation only through declaration changes** - Software agents continuously, and automatically, compare a system's _Actual State_ to its _Desired State_. - If the actual and desired states differ for any reason, automated actions to reconcile them are initiated. + The only mechanism through which the system is intentionally operated on is through versioned mutation of the _Desired State_ declarations. -4. **Use declaration as the sole way of operating a system** +4. **State reconciliation automated and continuous** - The only mechanism through which the system is intentionally operated on is through these principles. + Software agents continuously, and automatically, compare a system's _Actual State_ to its versioned _Desired State_ declarations. + If the actual and desired states differ for any reason, automated actions to reconcile them are initiated. ## Notes ### Principle 3 Notes -- These differences could be due to the actual state drifting from the desired state, or the desired state changing intentionally. -- The source of drift doesn't matter. Contrary to CIops, _any_ drift will trigger a reconciliation - -### Principle 4 Notes - - We talk here about "regular operations." In an emergency, other modes of operations, e.g. manual intervention, should be considered - followed by a reconciliation of the "tainted" system with the declared state. → resolve the conflict between "GitOps principle" and "I need to deal with problems that GitOps doesn't cover" ## Glossary @@ -52,6 +47,16 @@ These principles were derived from modern software operations but are rooted in The aggregate of all configuration data for a system form its _Desired State_ which is defined as data sufficient to recreate the system so that instances of the system are behaviourally indistinguishable. +- ### Drift + + When a system's _Actual State_ changes for any reason other than its versioned _Desired State_ declarations having changed, we say that the system has drifted from it's _Desired State_. + +- ### Reconciliation + + The process of ensuring that the _Actual State_ of a sytem matches it's versioned _Desired State_ declarations. + Contrary to CIops, any divergence between the two will trigger reconciliation, regardless of where changes occured. + Divergence could be due to the actual state unintentionally _Drifting_ from the desired state declarations, or a new desired state declaration version having been changed intentionally. + - ### Software System One or more Runtime environments consisting of resources under management. From 3d5a11857fdf7c29b5d1d96f324bc4349f4ebae7 Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Sat, 3 Jul 2021 00:47:19 -0400 Subject: [PATCH 2/5] Style improvement to glossary item definitions Signed-off-by: Scott Rigby --- PRINCIPLES.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/PRINCIPLES.md b/PRINCIPLES.md index 455e03c..e64456b 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -37,11 +37,11 @@ These principles were derived from modern software operations but are rooted in - ### Continuous - By "continuous" we adopt the industry standard term to mean reconciliation continues to happen, not that it must be instantaneous. + By "continuous" we adopt the industry standard term to mean _Reconciliation_ continues to happen, not that it must be instantaneous. - ### Declarative Description - Describing the desired state or behavior of a system without specifying how that state will be achieved, thereby separating between configuration - the desired state - and implementation - the commands, API calls, scripts ... that actually achieve the desired state described in the declarative description. + Describing the desired state or behavior of a system without specifying how that state will be achieved, thereby separating between configuration (the desired state) and implementation (the commands, API calls, scripts etc.) that actually achieves the desired state described in the declarative description. - ### Desired State @@ -65,6 +65,6 @@ These principles were derived from modern software operations but are rooted in One or more Administrators who are responsible for operating the runtime environments ie. installing, starting, stopping and updating software, code, configuration, etc. A set of policies controlling access and management of repositories, deployments, runtimes. -- #### State Store +- ### State Store A system for storing versioned, immutable Desired States that provides access control and auditing on the changes to the Desired State. Git may be configured as a State Store, but [special precautions must be taken](recipes/SETTING_UP_GIT.md). From d31cbb9adba1b27d25aa04565b78176f38a60cdf Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Sat, 3 Jul 2021 00:48:36 -0400 Subject: [PATCH 3/5] Fix broken link in State Store glossary definition. Summarize the intent of that forthcoming recipe while not assuming Git Signed-off-by: Scott Rigby --- PRINCIPLES.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/PRINCIPLES.md b/PRINCIPLES.md index e64456b..3f74455 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -67,4 +67,7 @@ These principles were derived from modern software operations but are rooted in - ### State Store - A system for storing versioned, immutable Desired States that provides access control and auditing on the changes to the Desired State. Git may be configured as a State Store, but [special precautions must be taken](recipes/SETTING_UP_GIT.md). + A system for storing immutable versions of _Desired State_ declarations. + This state store should provide access control and auditing on the changes to the Desired State. + Git is most often used as this State Store, but other systems may be used. + In all cases these must be properly configured, and special precautions must be taken, to comply with requirements set out in the GitOps Principles. From 0a8e9e93ef91d45e1e2443f673a9e9ef9a38a011 Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Sat, 3 Jul 2021 00:48:50 -0400 Subject: [PATCH 4/5] Bump version Signed-off-by: Scott Rigby --- PRINCIPLES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PRINCIPLES.md b/PRINCIPLES.md index 3f74455..4d161a3 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -1,4 +1,4 @@ -# GitOps Principles v0.1.0 +# GitOps Principles v0.2.0 ## Summary From 5517e3304511b617fcb6d9b6e44b8a529883da5b Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Sat, 3 Jul 2021 01:27:38 -0400 Subject: [PATCH 5/5] Move remaining note to Break Glass glossary definition. I believe this is the gist of the note, including the to-do at the end Signed-off-by: Scott Rigby --- PRINCIPLES.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/PRINCIPLES.md b/PRINCIPLES.md index 4d161a3..9662a9c 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -27,13 +27,14 @@ These principles were derived from modern software operations but are rooted in Software agents continuously, and automatically, compare a system's _Actual State_ to its versioned _Desired State_ declarations. If the actual and desired states differ for any reason, automated actions to reconcile them are initiated. -## Notes - -### Principle 3 Notes +## Glossary -- We talk here about "regular operations." In an emergency, other modes of operations, e.g. manual intervention, should be considered - followed by a reconciliation of the "tainted" system with the declared state. → resolve the conflict between "GitOps principle" and "I need to deal with problems that GitOps doesn't cover" +- ### Break Glass -## Glossary + The temporary suspension of GitOps principles, most often pausing automated _Reconciliation_. + While these principles apply to "regular operations," it may sometimes be necessary to pause or sidestep them during an emergency such as incident management. + In these cases, other modes of operations should be considered (e.g. manual intervention), followed by any necessary updates to the desired state declarations, and finally resuming reconciliation of the manually changed system with the updated declarations again. + Pragmatic exceptions to these guiding principles are expected from time to time during the journey toward a system being fully managed by GitOps. - ### Continuous