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.

Sign up for GitHub

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

Move control-loop rom principle to glossary for now #31

Merged
merged 9 commits into from
Oct 8, 2021
Merged

Move control-loop rom principle to glossary for now #31

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
af283d9
Add control-loop principle for consideration.
todaywasawesome Oct 7, 2021
494a5a9
Add link
todaywasawesome Oct 7, 2021
f3dea2c
Remove extra dash
todaywasawesome Oct 7, 2021
394df22
Improve inclusivity of language
todaywasawesome Oct 7, 2021
99ff0d3
Add feedback reference to reconcilliation
todaywasawesome Oct 8, 2021
4699168
Move closed-loop to glossary to avoid confusion in the principles.
todaywasawesome Oct 8, 2021
c4b29b0
Remove closed loop from the principles and focus in the glossary
todaywasawesome Oct 8, 2021
eddb05e
Update GLOSSARY.md
todaywasawesome Oct 8, 2021
9f6042c
Update GLOSSARY.md
todaywasawesome Oct 8, 2021
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
7 changes: 6 additions & 1 deletion GLOSSARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,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).
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.
Contrary to traditional CI/CD where automation is generally driven by pre-set triggers, in GitOps reconciliation is triggered whenever there is a divergence with [feedback](#feedback) from previous attempts. 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.
todaywasawesome marked this conversation as resolved.
Show resolved Hide resolved

- ## Software System

Expand All @@ -38,3 +38,8 @@ This glossary accompanies the [GitOps Principles](./PRINCIPLES.md), and other su
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 precautions must be taken to comply with requirements set out in the GitOps Principles.

- ## Feedback
Copy link
Contributor

Choose a reason for hiding this comment

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

I like this addition for the spec on feedback

Copy link
Contributor

Choose a reason for hiding this comment

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

To alphabetize Feedback, I created #41


Open GitOps follows [control-theory](https://en.wikipedia.org/wiki/Control_theory) and operates in a closed-loop. In control theory, feedback represents how previous attempts to apply a desired state have affected the actual state. For example if the desired state requires more resources than exist in a system, the software agent may make attempts to add resources, to automatically rollback to a previous version, or to send alerts to human operators.

Comment on lines +43 to +46
Copy link
Contributor

Choose a reason for hiding this comment

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

To alphabetize Feedback, I created #41

4 changes: 4 additions & 0 deletions PRINCIPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,7 @@ The [desired state](./GLOSSARY.md#desired-state) of a GitOps managed system must
4. **Continuously Reconciled**

Software agents [continuously](./GLOSSARY.md#continuous) observe actual system state and [attempt to apply](./GLOSSARY.md#reconciliation) the desired state.

5. **Applied in a Closed Loop**

Software agents follow control theory and depend on [feedback](./GLOSSARY.md#feedback) about the actual state and the attempts at reconcilliation in order to reduce deviation over time.
Copy link
Member

Choose a reason for hiding this comment

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

  • I like linking to the glossary defintion of feedback that specifies its place in control theory. But then don't need to mention control theory again here in the principle.
  • I think it's important to keep the note we had, that the agents follow rules about what to do with the feedback they receive from the system (including past attempts)
Suggested change
Software agents follow control theory and depend on [feedback](./GLOSSARY.md#feedback) about the actual state and the attempts at reconcilliation in order to reduce deviation over time.
Software agents take actions based on policies around [feedback](./GLOSSARY.md#feedback) from the system and previous reconciliation attempts, in order to reduce deviation over time.

Copy link
Contributor

Choose a reason for hiding this comment

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

policies are transformational, whereas previous reconciliation is transactional.

I'm OK with adding both.

If only one out of two amendments can be included, then I favor the addition of ... policies ... even over previous reconciliation.

Copy link
Member

Choose a reason for hiding this comment

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

Agree that previous reconciliation attempts are different from policies, but I mean there are policies which tell agents what to do with this feedback information. The simplest example I can think of is do something different after N attempts or T time (essentially, this is what k8s core controller CrashloopBackOff is). These require feedback from the system (closed loop) rather than just continue an open loop infinitely.

For GitOps this could be sending a failure notification requiring human decision making, rollbacks, or other specified actions. These policies are usually configurations delivered to agents who are doing the work of reconciliation and other actions around this, and therefore generally defined as part of Desired State. I didn't suggest specifying this though because the policies could also be built-in to the software agents chosen for the job.

Copy link
Member

Choose a reason for hiding this comment

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

@lloydchang Just checking, do you have a concrete recommendation for modifying the wording of my suggested edit to Dan's change request?

Right now I'm hearing you say why you approve of this and what the constraints are if we were to change it even further. Please lmk if that is not correct 🙂

Copy link
Contributor

Choose a reason for hiding this comment

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

Agreed @scottrigby

Copy link
Contributor

@lloydchang lloydchang Oct 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

@scottrigby I noticed v1.0.0's PRINCIPLE.md is missing your suggested change.

To confirm, is it intentional because of:

@scottrigby changed the title of this pull request to
"Move control-loop from principle to glossary for now"

?

FWIW, you and I are aligned regarding your proposed suggestions to PRINCIPLE.md if the topic resurfaces in future working group meetings, discussions, pull requests, etc.

Thank you.

Copy link
Member

@scottrigby scottrigby Oct 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Yes, I understood that you were OK with it as worded now, but also had at least slight misgivings as a foundational requirement/principle, but all seem to agree it is at least a best practice.

Several other people had misgivings as well, some noted in slack because they were not able to get to github in time. We said in order to stick to schedule, if there was divergence in opinion we would leave the fifth principle omitted for the first release, so we did.

But it still seems important enough to include in the glossary, and link feedback item from the reconciliation glossary item.

This seemed a good compromise for now, and I believe does not go against the group conscience. We can continue discussing after v1.0.0 (which is now released!), and see where we all align on this when there is feedback on it from more WG and community members.

PS you are heavily thanked along with everyone else in the release notes 😇💯🎊

Copy link
Contributor

@lloydchang lloydchang Oct 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Thanks @scottrigby

No slight misgivings from me at all about including your suggested changes as a Principle.

While I would like to see your suggested changes as a Principle, I am OK with v1.0.0's PRINCIPLE.md.

Thank you, everyone!

Copy link
Member

Choose a reason for hiding this comment

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

Got it. Ok thanks for clarifying, we will continue discussing w the rest of the group post-kubecon 👌

Also, now that these are in a full release, we can also focus on the other documents and programs (and any potential code) that depended on these. Looking forward to moving ahead with those too!

Copy link
Contributor

@lloydchang lloydchang Oct 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Thanks again @scottrigby — Another reason for adding your suggested changes as a fifth principle before further compromising its position in Documents, Glossary, Best Practices, Programs, Code, etc. is that our focus and intent is to be principle-led:

The GitOps WG focus is to clearly define a vendor-neutral, principle-led meaning of GitOps, which will establish a foundation for interoperability between tools, conformance, and certification. Lasting GitOps programs, documents, and code will live within the CNCF OpenGitOps project, also guided by the WG.
https://github.com/gitops-working-group/gitops-working-group/blob/main/README.md

OK that:

we will continue discussing w the rest of the group post-kubecon 👌