RC 1 draft (#21)

First release candidate drafted by GWG/OGO chairs, incorporating all discussion
and feedback thus far. The objective was to propose a release candidate draft
reconciling and incorporating the varying views of all GitOps Working Group
community participants.

This draft has now been reviewed by GitHub WG maintainers. It was also reviewed
by GitOps Working Group members, including members of the principles committee.
After merge, we will create a release branch and tag the release. The goal is
to publish RC 1 widely, to request async feedback from the WG principles
committee, the wider WG, people listed in the interested-parties document:
https://github.com/gitops-working-group/gitops-working-group/blob/main/interested-parties.md
and the wider GitOps community.

This draft addresses previously planned milestones (now closed):

- Simplify principles titles
- Clarify language to emphasize main point of each principle
- Incorporate all community feedback with broad consensus
- Resolve notes and glossary items
- Ensure consistency of language
- Ensure accessibility of all language

RC 1 PR drafted by:
Co-authored-by: Scott Rigby <[email protected]>
Co-authored-by: Dan Garfield <[email protected]>
Co-authored-by: Leonardo Murillo <[email protected]>

RC 1 PR reviewed by:
Co-authored-by: Nicholas Thomson <[email protected]>
Co-authored-by: William Caban <[email protected]>
Co-authored-by: Dan Garfield <[email protected]>
Co-authored-by: Moshe Immerman <[email protected]>
Co-authored-by: Chris Sanders <[email protected]>
Co-authored-by: Leonardo Murillo <[email protected]>
Co-authored-by: Carlos Santana <[email protected]>

This draft was also based on work by the GitOps WG over the past 6 months.
Specifically #14, which was closed in favor of this RC 1 draft. Contributors
to that PR were:

Co-authored-by: Jesse Butler <[email protected]>
Co-authored-by: William Caban <[email protected]>
Co-authored-by: Dan Garfield <[email protected]>
Co-authored-by: Moshe Immerman <[email protected]>
Co-authored-by: Christian Hernandez <[email protected]>
Co-authored-by: Leonardo Murillo <[email protected]>
Co-authored-by: Scott Rigby <[email protected]>
Co-authored-by: Chris Sanders <[email protected]>
Co-authored-by: Roberth Strand <[email protected]>
Co-authored-by: Daniel Warner <[email protected]>
Co-authored-by: Florian Heubeck <[email protected]>
Co-authored-by: Lloyd Chang <[email protected]>

Signed-off-by: Scott Rigby <[email protected]>

Review changes after the initial draft were:

* Moving glossary to separate file, and adding hyperlinks from principles to
  glossary items

* Added context sentence for the principle headers grammar

* Removed incomplete summary from introduction. Unecessary now because
  principles are shorter and summmarize themselves

* Moved glossary to a standalone file

* Linked terms in principles to now linkable glossary items

* Address markdown version / git revision mismatch. Fixes #20

* Typo fixes

Co-authored-by: Nicholas Thomson <[email protected]>

* Added note about configuration data excluding other external data

Co-authored-by: Nicholas Thomson <[email protected]>

* Fixed formatting of software system glossary item. Clarified one list item

Co-authored-by: Nicholas Thomson <[email protected]>

* Added links within glossary items

Co-authored-by: Dan Garfield <[email protected]>

* Broadened user data example to just database contents. Fix formatting

Co-authored-by: Dan Garfield <[email protected]>

* Remove 'versioned' from reconciliation glossary item.

Co-authored-by: Dan Garfield <[email protected]>

* Fixed grammar, capitalization, and other formatting

Co-authored-by: Dan Garfield <[email protected]>

Signed-off-by: Scott Rigby <[email protected]>

Author: scottrigby

GLOSSARY.md

@@ -0,0 +1,49 @@
+# GitOps Glossary
+
+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.
+
+- ## 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.
+
+- ## 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.
+
+- ## 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.
+
+- ## 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.
+    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:
+
+  - 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
+
+- ## 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.

PRINCIPLES.md

@@ -1,74 +1,22 @@
-# GitOps Principles v0.1.0
-
-## Summary
+# GitOps Principles {{version}}
 
 GitOps is a set of principles for operating and managing software systems.
+These principles are derived from modern software operations, but are also rooted in pre-existing and widely adopted best practices.
 
-When using GitOps, the _Desired State_ of a system or subsystem is defined declaratively as versioned, immutable data, and the running system's configuration is continuously derived from this data.
-
-These principles were derived from modern software operations but are rooted in pre-existing and widely adopted best practices.
-
-## Principles
-
-1. **The principle of declarative desired state**
-
-    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. **The principle of immutable desired state versions**
-
-    _Desired State_ is stored in a way that supports versioning, immutability of versions, and retains a complete version history.
-
-3. **The principle of continuous state reconciliation**
-
-    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.
-
-4. **The principle of operations through declaration**
-
-    The only mechanism through which the system is intentionally operated on is through these principles.
-
-## Glossary
-
-- ### Break Glass
-
-    The temporary suspension of GitOps principles, often accomplished by pausing automated _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_ 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.
-
-- ### 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.
+The [desired state](./GLOSSARY.md#desired-state) of a GitOps managed system must be:
 
-- ### Drift
+1. **Declarative**
 
-    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 its _Desired State_.
+    A [system](./GLOSSARY.md#software-system) managed by GitOps must have its desired state expressed [declaratively](./GLOSSARY.md#declarative-description).
 
-- ### Reconciliation
+2. **Versioned and Immutable**
 
-    The process of ensuring that the _Actual State_ of a sytem matches its 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.
+    Desired state is [stored](./GLOSSARY.md#state-store) in a way that enforces immutability, versioning and retains a complete version history.
 
-- ### Software System
+3. **Pulled Automatically**
 
-    One or more Runtime environments consisting of resources under management.
-    In each Runtime, management Agents to 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.
+    Software agents automatically pull the desired state declarations from the source.
 
-- ### State Store
+4. **Continuously Reconciled**
 
-    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 the canonical example used as this State Store, and where GitOps derived its name, but but any other system that meets this criteria 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.
+    Software agents [continuously](./GLOSSARY.md#continuous) observe actual system state and [attempt to apply](./GLOSSARY.md#reconciliation) the desired state.