# GitOps Principles

## Summary

GitOps is a set of principles for operating and managing software systems.

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.

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.

GitOps principles were derived from modern software operations but are rooted in pre-existing and widely adopted best practices. These principles are:

1. [**The principle of declarative desired state**]()

A system managed by GitOps must have its _Desired State_ expressed declaritively 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 a system can be intentionally operated on is through these principles.

**To be discussed Re all principles:**
- How short or long should the short form of the principles be? Which points are important enough to note but not to be memorizable in the one-line, one-paragraph, or expanded notes for each?
- Proposal: "notes" section be displayed prominently
- Principles notes could refer to "under what circumstances" should these principles be implemented, have exceptions, etc.
- example: any form of bootstrap can not by definition follow gitops principles. There are always exceptions
- example: continuous vs instant
- example: break glass/incident management

**To be discussed Re Principle #3:**
- Use of "continuous" in one-line. See https://github.com/gitops-working-group/gitops-working-group/discussions/129

**To be discussed Re further principles:**
- Proposed "principle 5: governance through gitops" https://github.com/gitops-working-group/gitops-working-group/discussions/93

## Principle 1 Notes

## Principle 2 Notes
- "configuration" in header adds confusion and makes things less clear
- Lack of coherence between heading and description
- "We call systems that store desired state in this way _State Stores_." isn't helpful and adds details that are not needed.

## Principle 3 Notes
- These differences could be due to the actual state drifting from the desired state, or the desired state changing intentionally.
- source of drift doesn't matter. Contrary to CIops, _any_ drift will trigger a reconciliation
- Dissenting position: By "continuous" we adopt the industry standard term to mean reconcilation continues to happen, not that it must be instant
- "continuous?" - subtleties with closed/open loops in system and control theory, what about event driven stuff?
- Ensure we discuss loops (and systems theory) in longer discussion

## Principle 4 Notes

- we talk here about "regular operations". In an emergency also other mode of operation, e.g. manual intervention, should be considered - followed by a reconsiliation 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- What circumstances can this be broken?
- Human/machines note

## Notes

Principles to be taken as a whole.

# Glossary extract

- **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).

- **Desired State**

The aggregate of all configuration data for a system form its "Desired State". The "Desired State" of a system is defined as data sufficient to recreate the system so that instances of the system are behaviourally indistinguishable.

- **Software System**

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.

- **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.