From a0d89d9107b78a95257773681fe8e2cebf28a59a Mon Sep 17 00:00:00 2001 From: Dan Garfield Date: Fri, 24 Sep 2021 10:59:06 -0600 Subject: [PATCH 1/8] Remove breaking glass language as it is no longer referenced. This is something we may add back later as we add things. Signed-off-by: Dan Garfield --- GLOSSARY.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 9f9434d..c7d689d 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -2,13 +2,6 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other supporting documents in this repository. -- ## Break Glass - - The temporary suspension of GitOps principles, often accomplished by pausing automated [reconciliation](#reconciliation). - While these principles apply to typical operations, it may at times be necessary to temporarily pause reconciliation, for example during incident management activities. - 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 system with the updated declarations. - Pragmatic exceptions to these guiding principles are expected from time to time during the journey toward a system being fully managed by GitOps. - - ## Continuous By "continuous" we adopt the industry standard to mean that [reconciliation](#reconciliation) continues to happen, not that it must be instantaneous. From 1995ce2a4e1c60c6aba2d13f457f633083fc746f Mon Sep 17 00:00:00 2001 From: Dan Garfield Date: Fri, 24 Sep 2021 11:47:27 -0600 Subject: [PATCH 2/8] Revise wording to make each definition more clear. Also remove the extra components under software system. Signed-off-by: Dan Garfield --- GLOSSARY.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index c7d689d..dc67d1d 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -4,39 +4,37 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Continuous - By "continuous" we adopt the industry standard to mean that [reconciliation](#reconciliation) continues to happen, not that it must be instantaneous. + "Continuous" is intended to match the industry standard term: [reconciliation](#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 configuration (the desired state) from the implementation (commands, API calls, scripts etc.) that actually achieves the desired state described in the declarative description. + A configuration that describes the desired operating state of a system without specifying procedures for how that state will be acheived. This separates configuration (the desired state) from the implementation (commands, API calls, scripts etc.) used to achieve that state. - ## Desired State - 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, but do not include the state of any data stored within the system, eg. database contents. + The aggregate of all configiuration data needed to start, bootstrap, recreate, run, and recover a system. This does not include data stored within a system, eg. database contents. - ## Drift - When a system's actual state changes for any reason other than its versioned [desired state](#desired-state) declarations having changed, we say that the system has drifted from its desired state. + When a system's actual state changes for any reason other than its [desired state](#desired-state)declarations having changed. When this occurs, the system has drifted from its desired state. - ## Reconciliation - The process of ensuring that the actual state of a system matches its [desired state](#desired-state) declarations. - Contrary to CIops, any divergence between the two will trigger reconciliation, regardless of where changes occured. + The process of ensuring the actual state of a system matches its [desired state](#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](#drift) from the desired state declarations, or a new desired state declaration version having been changed intentionally. - ## Software System - We currently understand a software system to include: + A software system managed by GitOps includes: - - One or more runtime environments consisting of resources under management - - In each runtime, the management agents which act on resources according to security policies - - One or more software repositories for storing deployable artifacts that may be loaded into the runtime environments, eg. configuration files, code, binaries, and packages - - 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 + 1. One or more runtime environments consisting of resources under management + 1. The management agents within each runtime + 1. Policies for controlling access and management of repositories, deployments, runtimes - ## State Store A system for storing immutable versions of [desired state](#desired-state) declarations. This state store should provide access control and auditing on the changes to the Desired State. Git, from which GitOps derives its name, is the canonical example used as this state store but any other system that meets these criteria may be used. - In all cases, these state stores must be properly configured and special precautions must be taken to comply with requirements set out in the GitOps Principles. + In all cases, these state stores must be properly configured and precautions must be taken to comply with requirements set out in the GitOps Principles. From 36bd7da3861d9b1d610d9e9225bf9933623e5c01 Mon Sep 17 00:00:00 2001 From: Piotr Date: Mon, 27 Sep 2021 21:23:22 +0200 Subject: [PATCH 3/8] Fixed 3 typos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 3 small typos were fixed in the document. Co-authored-by: Lloyd Chang Co-authored-by: Cansu Kavılı Örnek Signed-off-by: Piotr --- GLOSSARY.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index dc67d1d..faf51f3 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -8,11 +8,11 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Declarative Description - A configuration that describes the desired operating state of a system without specifying procedures for how that state will be acheived. This separates configuration (the desired state) from the implementation (commands, API calls, scripts etc.) used to achieve that state. + A configuration that describes the desired operating state of a system without specifying procedures for how that state will be achieved. This separates configuration (the desired state) from the implementation (commands, API calls, scripts etc.) used to achieve that state. - ## Desired State - The aggregate of all configiuration data needed to start, bootstrap, recreate, run, and recover a system. This does not include data stored within a system, eg. database contents. + The aggregate of all configuration data needed to start, bootstrap, recreate, run, and recover a system. This does not include data stored within a system, eg. database contents. - ## Drift @@ -21,7 +21,7 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Reconciliation The process of ensuring the actual state of a system matches its [desired state](#desired-state) declarations. - Contrary to "CIops", any divergence between the two will trigger reconciliation, regardless of where changes occured. + Contrary to "CIops", any divergence between the two will trigger reconciliation, regardless of where changes occurred. Divergence could be due to the actual state unintentionally [drifting](#drift) from the desired state declarations, or a new desired state declaration version having been changed intentionally. - ## Software System From 782ae1e9a2a69396964547d698dd09e5739bc45e Mon Sep 17 00:00:00 2001 From: Dan Garfield Date: Wed, 29 Sep 2021 14:48:26 -0600 Subject: [PATCH 4/8] Remove CIOps and use standard language to clarify reconciliation. Signed-off-by: Dan Garfield --- GLOSSARY.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index faf51f3..be8e511 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -21,8 +21,7 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Reconciliation The process of ensuring the actual state of a system matches its [desired state](#desired-state) declarations. - Contrary to "CIops", any divergence between the two will trigger reconciliation, regardless of where changes occurred. - Divergence could be due to the actual state unintentionally [drifting](#drift) from the desired state declarations, or a new desired state declaration version having been changed intentionally. + Contrary to traditional CI/CD where automation is generally driven by pre-set triggers, in GitOps reconciliation is triggered whenever there is a divergence. Divergence could be due to the actual state unintentionally [drifting](#drift) from the desired state declarations, or a new desired state declaration version having been changed intentionally. - ## Software System From 3858e7a216df05aade7e9cf677d1c6830a551d15 Mon Sep 17 00:00:00 2001 From: Dan Garfield Date: Fri, 1 Oct 2021 10:51:03 -0600 Subject: [PATCH 5/8] Add space Co-authored-by: Brian Fox Signed-off-by: Dan Garfield --- GLOSSARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index be8e511..278e54a 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -16,7 +16,7 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Drift - When a system's actual state changes for any reason other than its [desired state](#desired-state)declarations having changed. When this occurs, the system has drifted from its desired state. + When a system's actual state changes for any reason other than its [desired state](#desired-state) declarations having changed. When this occurs, the system has drifted from its desired state. - ## Reconciliation From 350da1f678a1ff9ecafceabedf41fb92a28d7ede Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Fri, 1 Oct 2021 12:52:55 -0400 Subject: [PATCH 6/8] Remove unnecessary 'declarations' modifier Co-authored-by: Brian Fox Signed-off-by: Scott Rigby --- GLOSSARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 278e54a..08c81ca 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -20,7 +20,7 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Reconciliation - The process of ensuring the actual state of a system matches its [desired state](#desired-state) declarations. + The process of ensuring the actual state of a system matches its [desired state](#desired-state). Contrary to traditional CI/CD where automation is generally driven by pre-set triggers, in GitOps reconciliation is triggered whenever there is a divergence. Divergence could be due to the actual state unintentionally [drifting](#drift) from the desired state declarations, or a new desired state declaration version having been changed intentionally. - ## Software System From 1d56650854f36d86d5096e3d098b3fb538d35e58 Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Fri, 1 Oct 2021 13:21:38 -0400 Subject: [PATCH 7/8] Update Desired State glossary item Co-authored-by: Lloyd Chang Co-authored-by: Michael Bridgen Co-authored-by: Dan Garfield Signed-off-by: Scott Rigby --- GLOSSARY.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 08c81ca..c15bcc9 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -12,7 +12,8 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Desired State - The aggregate of all configuration data needed to start, bootstrap, recreate, run, and recover a system. This does not include data stored within a system, eg. database contents. + 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. + This configuration data generally does not include persistent application data, eg. database contents, though often does include credentials for accessing that data, or configuration for data recovery tools running on that system. - ## Drift From a433baf653e045cf0fa13211b379a03639079ab9 Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Fri, 1 Oct 2021 13:52:57 -0400 Subject: [PATCH 8/8] Clarify "drift" means moving away from desired state not moving toward Good note Michael, important to be precise here. Co-authored-by: Michael Bridgen Co-authored-by: Dan Garfield Co-authored-by: Lloyd Chang Signed-off-by: Scott Rigby --- GLOSSARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index c15bcc9..b224d24 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -17,7 +17,7 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su - ## Drift - When a system's actual state changes for any reason other than its [desired state](#desired-state) declarations having changed. When this occurs, the system has drifted from its desired state. + When a system's actual state has moved or is in the process of moving away from the [desired state](#desired-state), this is often referred to as drift. - ## Reconciliation