For initial pre-release of GitOps Principles revised by the GitOps Working Group

[scottrigby]

This pull request is for an action item from the GitOps Working Group Principles Committee consensus to create the first pre-release of the revised GitOps Principles. The plan is to add this to a repo in the OpenGitOps project org.

[Scott] bring current principles into a new PR under the OpenGitOps github org which:

1. Brings in commit history from previous work by Brice, Scott, and the community through the pull request process prior to live sync sessions were deemed necessary
2. Includes dissenting/clarifying notes about the principles wording that reached broad consensus. Example: continuous vs instant
3. Gives proper attribution to the participation and co-authorship of the GitOps Principles Committee members, including all who participated in the initial PR, github discussions on these topics, and live sync sessions

Steps

• Commits from Define the GitOps Principles gitops-working-group/gitops-working-group#48 were git filtered only for the relevant files: GLOSSARY.md, PRINCIPLES.md, RATIONALE.md
• These commits were rebased onto an initial empty commit (85029c4) shared with main of this repo, so that we can successfully create this public pull request (commits through 45cd99d)
• Edits from the Principles Committee Weekly sync meetings collaborative HackMD file were added as a commit (4f0dd54) on top of the existing commits, so the complete history of edits is maintained within this PR branch
• Get all co-author's git commit emails (discussion in Slack)
• ensure all commits have proper DCO signoff
• This PR requires first merging Add licenses for non-code and any future code #5 (we need licenses clearly in place before publishing this PR content)
• Merge into main. This PR may be squash merged into main, as long as the co-authorship above is properly recorded
• Release v0.1.0 of the Principles - https://github.com/open-gitops/documents/releases/tag/v0.1.0
• Update short version of the principles in the GitOps Working Group README, and link to here for full context (notes, glossary, etc)
• There may be additional comments on this PR however broad consensus has been reached for the initial pre-release. Later PRs can be made to propose revisions leading up to a full release

Co-authors

• All co-authors listed alphabetically by last name
• Includes all existing co-authors from commits on Define the GitOps Principles gitops-working-group/gitops-working-group#48
• Includes Attendees of Principles Committee meetings Mar 29-May 05, 2021. These were drawn from the GitOps WG Principles Committee meeting notes, and listed again below
• 🚧 Please let us know if anyone's contribution was missed before we merge this PR

Co-authored-by: Andrew Block <ablock@redhat.com>
Co-authored-by: Shoubhik Bose <shbose@redhat.com>
Co-authored-by: Kevin Bowersox <kmb385@gmail.com>
Co-authored-by: Jesse Butler <butlerjl@amazon.com>
Co-authored-by: Lloyd Chang <lloydchang@gmail.com>
Co-authored-by: William Chia <thewilliamchia@gmail.com>
Co-authored-by: Cornelia Davis <ornelia@corneliadavis.com>
Co-authored-by: Brice Fernandes <brice@weave.works>
Co-authored-by: Robert A Ficcaglia <rficcaglia@users.noreply.github.com>
Co-authored-by: Brian Fox <brianhfox@gmail.com>
Co-authored-by: Christian Hernandez <christian@redhat.com>
Co-authored-by: Moshe Immerman <moshe@flanksource.com>
Co-authored-by: Timothy Lin <timothylin@deloitte.com>
Co-authored-by: Toni Menzel <toni.menzel@rebaze.com>
Co-authored-by: Leonardo Murillo <leonardo@devops.cr>
Co-authored-by: John Pitman <jpitman@redhat.com>
Co-authored-by: Scott Rigby <scott@r6by.com>
Co-authored-by: Chris Sanders <csand@microsoft.com>
Co-authored-by: Carlos Santana <csantana@us.ibm.com>
Co-authored-by: Schlomo Schapiro <schlomo@schapiro.org>
Co-authored-by: Lothar Schulz <mail@lotharschulz.info>
Co-authored-by: Regina Scott <rescott@redhat.com>
Co-authored-by: Ishita Sequeira <isequeir@redhat.com>
Co-authored-by: Roberth Strand <me@robstr.dev>
Co-authored-by: Sean Sundberg <seansund@us.ibm.com>

Mar 29, 2021 attendees

• Co-authors for number 3 above are:
• Brice Fernandes @bricef
• Christian Hernandez @christianh814
• Leonardo Murillo @murillodigital
• Lothar Schulz @ lotharschulz
• Moshe Immerman @moshloop
• Roberth Strand @roberthstrand
• Scott Rigby @scottrigby
• Toni Menzel @tonit

April 05, 2021 attendees

• Schlomo @schlomoschapiro
• Roberth Strand @roberthstrand
• Cornelia Davis @cdavisafc
• Brice Fernandes
• Leonardo Murillo
• Christian hernandez
• Jesse Butler
• Carlos Santana (IBM) @csantanapr
• Sean Sundberg (IBM)
• Timothy Lin (Deloitte)
• Scott Rigby

April 14, 2021 attendees

• Roberth Strand (Crayon)
• Shoubhik Bose (Red Hat) @sbose78
• Andrew Block (Red Hat) @sabre1041
• Leonardo Murillo (Cloud Native Architects)
• Schlomo
• John Pitman (Red Hat) @jopit
• Regina Scott (Red Hat) @reginapizza
• Ishita Sequeira (Red Hat) @ishitasequeira
• Scott Rigby

April 28, 2021 attendees

• Leonardo Murillo
• Christian Hernandez
• Roberth Strand
• Chris Sanders @csand-msft
• Jesse Butler
• Schlomo Schapiro
• Lothar Schulz
• Scott Rigby

May 05, 2021 attendees

• Chris Sanders
• Christian Hernandez (halfway through)
• Leonardo Murillo
• Brice Fernandes
• Lothar Schulz
• Moshe Immerman
• Roberth Strand
• Cornelia Davis
• Scott Rigby

Additional asynchronous participants on GitHub: #4 (comment)

[lloydchang]

@scottrigby wrote:

🚧 Please let us know if anyone's contribution was missed before we merge this PR

Hi, @scottrigby,

When your time permits, I suggest that you skim
gitops-working-group/gitops-working-group#48
and
https://github.com/gitops-working-group/gitops-working-group/discussions/129
for reviewers and participants who cannot attend live meetings, and contributed feedback asynchronously.

For example, I noticed that @kmb385, @theWilliamChia and I commented in the above GitHub links, outside of live meetings. Perhaps others did too. My understanding of the GitHub links are intended to allow people who cannot attend live meetings to contribute asynchronously.

In this PR, I just requested suggestions for docs: fix misspellings and grammar. If you include the suggestions, then please list me as a co-author accordingly.

Co-authored-by: Lloyd Chang <lloydchang@gmail.com>

Thank you @scottrigby 🙂

[scottrigby]

Thank you @lloydchang, merged suggestions.

About users who reviewed the past PR, I wouldn't normally consider comments as part of git co-authorship – however in this case I think you are right. Async participants participated as much and in some cases more than live attendees of the Principles Committee meetings.

Here are all the additional users who participated in in that PR and discussion:

• @kmb385: Kevin Bowersox <kmb385@gmail.com>
• @lloydchang: lloydchang <lloydchang@gmail.com>
• @onematchfox: Brian Fox <brian@midnite-it.se>
• @theWilliamChia: William Chia <thewilliamchia@gmail.com>
• @rficcaglia: Robert A Ficcaglia <rficcaglia@users.noreply.github.com> *

* Note: I believe @ficcaglia who commented on gitops-working-group/gitops-working-group#48 is another account for @rficcaglia (example). I have reached out on Slack, but because I don't know their availability I do not want to hold up this PR merging if we can help it. Luckily because this account was created before 2017 we can use the GitHub no-reply email in the form of username@users.noreply.github.com. I'll wait until Monday to merge ⏳

[onematchfox]

• @onematchfox: Brian Fox <brian@midnite-it.se>

Just a quick confirmation that this is the same Brian Fox as listed in the PR description. No need to duplicate. 😄

[sabre1041]

@scottrigby Any chance my email could be changed to ablock@redhat.com?

[scottrigby]

@sabre1041 absolutely, changed in description above and commit message ✅

[scottrigby]

Thanks @onematchfox 😸

[rficcaglia]

@scottrigby sorry for the hassle! rficcaglia@gmail.com is fine or you can keep it as is - whichever is easier for you!

[williamcaban]

What is considered "tainted"? The statement of "reconciliation of the 'tainted' system does not have a definition. Is 'tainted' a state that is defined by GitOps tool, the action of "manual intervention" or to the modification of the artifact outside the GitOps reconciliation cycle?

[williamcaban]

Is this referring to an emergency temporary disconnection/pause of the GitOps reconciliation cycle to address the "emergency" and then, once the source of truth is updated, continue/reconnect/unpause the GitOps controller for resuming the reconciliations? If that is the case, would it be appropriate to state that a temporary pause of GitOps could happen, and resuming GitOps after that event should be treated like any initial reconciliation cycle where the cycle remediates towards Desired State?

[scottrigby]

@williamcaban Thanks for this question! This note a little rough. But yes, I think you have a good sense of the spirit it's intending to convey. This may feel repetitive, but here's a quick summary of the intentions for that principle and note:

• The intention of Principle 4 is to drive home the message that a system managed by GitOps should only be intentionally operated on through principles 1-3.
• The intention of this note on principle 4 is to acknowledge a caveat to that message: That individuals responsible for incident management may still need to temporarily bypass the normal GitOps process to handle an emergency.

So to answer your question, I think so yes. Typically this happens by:

1. pausing GitOps reconciliation for a specific subsystem/component
2. performing emergency actions directly on the system
3. once addressed, in order to resume GitOps reconciliation, any directly applied "fixes" should be declared in the desired state, and reconciliation should be resumed.

Since these GitOps Principles are meant to be applied broadly – and specific use cases will build on them – we are being very careful not to assume anything about specific systems or tools within the principles or the notes.

If you have a specific proposal for updating the wording for this note to make it more clear, please feel free to propose it using GitHub suggestions directly on this PR. However, since we have already reached broad consensus on this for the initial pre-release, this PR is scheduled for merge very soon. If this PR merges before your suggestion is able to be properly reviewed/incorporated, you may open another PR against main after that point. Also, if you are able, please also join the weekly GitOps Principles Committee Meetings 😄 These are Wednesdays weekly at 19:00 GMT, unless otherwise specified.

[csand-msft]

The word 'tainted' could be removed. Use "...followed by a reconciliation of the system to the declared state. ...".