Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Address notes on the principles and remove the notes section #15

Merged
merged 5 commits into from
Sep 15, 2021
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 23 additions & 14 deletions PRINCIPLES.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,31 +27,37 @@ These principles were derived from modern software operations but are rooted in

The only mechanism through which the system is intentionally operated on is through these principles.

## 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
## 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_.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved
While these principles apply to "regular operations," it may sometimes be necessary to pause or sidestep them during an emergency such as incident management.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved
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.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved
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 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.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

- ### 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.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

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

- ### 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_.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

- ### Reconciliation

The process of ensuring that the _Actual State_ of a sytem matches it's versioned _Desired State_ declarations.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved
Contrary to CIops, any divergence between the two will trigger reconciliation, regardless of where changes occured.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this be "where" or "how" changes occurred?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is meant to convey that unlike event driven CI, reconciliation doesn't only need to be triggered by an intentional change to the desired state stored in Git. Divergence could also happen in the runtime environment, accidentally (by a developer with permissions they shouldn't have), purposefully (by someone authorized to do incident management during an emergency or by a bad actor), or from some system failure, etc. Agents running inside the runtime who watch the desired state store allows divergence from whichever direction to trigger a reconciliation loop.

Maybe this could be worded differently, but this is what "where" was supposed to mean. Any suggestions on clarifying that in a simple way?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually with that explanation, I see it clearly now. I was probably being pedantic, all good with it as is.

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member Author

@scottrigby scottrigby Sep 15, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be a revisited after RC 1 👌


One or more Runtime environments consisting of resources under management.
Expand All @@ -60,6 +66,9 @@ 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).
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.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved
In all cases these must be properly configured, and special precautions must be taken, to comply with requirements set out in the GitOps Principles.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved