How you can help now

1. Please read Dan’s good issue summary (original issue below), which came out of our last group meeting. The gist of the question is, do we think the originally included “closed loop” principle should be added back before the planned v1.0.0 release milestone (scheduled for EOW, no later than Monday Oct 11)

2. We are now asking YOU – WG members & maintainers – to 👍 or 👎 this issue by Friday Oct 8th. (ideally, also comment a short reason).

   Note this is not a decision for all time, but just for this first full release. We can continue to discuss for possible inclusion after v1.0.0 if there is too much divergence in opinion. It was left out of RC 1 (see “items left out of this PR”) and not yet included in RC 2 because there was not enough group response so far.

Original issue

This came up as part of an ongoing discussion around #22 with @squaremo @lloydchang @scottrigby @murillodigital.

#22 (comment)

When we did #21 we removed the closed-loop because we couldn't really articulate why it was there. Some of the discussions referenced above brought back some of the ideas of why we had included closed-loop in the first place.

I'm not very familiar with control theory so the usage of the word "feedback" really threw me off. Feedback seemed like something could happen to your actual state that would then somehow inform your desired state. After going through it with @scottrigby, the way control theory uses "feedback" is that there is a recognition of what is actually occurring in the system and that it is taken into account.

On some level, I think this is encapsulated in two principles "declarative" + "continuously reconciled". With those two ideas, I think you can probably get to closed-loop. For example, if you were to create a progressive delivery plan that involved checking metrics and then making a decision to rollback or move ahead I would view that as part of GitOps as long as it is declaratively expressed and continuously reconciled. The reconciliation implies the idea of closed-loop feedback.

However, as it has come up over and over again and @scottrigby has pointed out, it may be worthwhile making that idea clearly explicit by making it a principle.

For #22 I think we're time boxing to move toward GitOps V1 but if we:

1. Believe there is an important value add to bring closed-loop back and
2. That we can articulate that value clearly

then we may move ahead to include it in v1. So long as it does not introduce a delay.

In other words: if this is important to you, please fight for it here and give your ideas for how to communicate it.

Now that GitOps is getting a lot of traction, we got a lot of questions from different parties how to start their own GitOps journey.
I think this warrants a dedicated document of what are the things to consider before even thinking of adopting GitOps to avoid disaster or bad taste.

Something I have discussed with my colleagues are GitOps pre-requisites and we ended up with this list.

1. Communication Strategy (why are we doing this, how does it fit our context, how will we manage risk)
2. Automation Maturity - Infrastructure as Code at the minimum
3. Executive sponsor
4. Champions / CoP - a team that can ‘go first’
5. Standardisation (can’t have 20 x Git sources of truth)
6. Enablement strategy - Git enablement, Ansible enablement, DevSecOps Enablement
7. Matrix view of crawl / walk / run (ie start w infra, then apps, then network)
8. K8s has to be on the roadmap - how do we get ready for that
9. Start Small!

Happy to expound this and contribute if needed.

Good fix for #20

On the main branch we now use a {{version}} placeholder at the top of PRINCIPLES.md markdown file, as a way to solve #20.

Incomplete though

However, we forgot to resolve this in the README 🤦, which still links to the first pre-release:

The current version v0.1.0 is a pre-release, which includes:

• GitOps Principles
• GitOps Glossary

Sigh.

Proposed solutions

1. change the README to use a placeholder
   • pros: the {{version}} => semver replacement could be automated, just as we plan to do for the PRINCIPLES.md on release branches
   • cons: users who encounter the readme would likely be confused by broken links on main
2. change the text above to just point to the list of releases and milestones for planned upcoming releases
   • pros: the README will be clear to new users. also don't have to update it for every new release
   • cons: README won't list the current version on main
3. solve README differently than PRINCIPLES.md, since the goal is different. On PRINCIPLES.md we don't want the previously published version to be displayed after new commits are added to main, because of #20. However in the README we (may) want to list the most recently published version. Perhaps this could be solved by a GitHub action.

How about we start with option 2, and consider option 3 when we get around to making a release workflow using gh actions (similar to https://github.com/helm/chart-testing#releasing).

Many people are looking for GitOps to replace some imperative existing model, like a CI job running kubectl set image .... This often results in people independently authoring janky shell scripts that end up needing to...

0. decide something about the world, like some new image being ready for use in production
1. enough resource type awareness to edit some files - Possibly flimsy, such as with sed / envsubst
2. make a commit
3. push it somewhere and

• make a PR (vendor-specific api) for something else to review or automerge
• deal with merge conflicts - possibly rebase or discard & retry

FluxCD v1 implemented a stack of code for detecting & bumping image versions, but never dealt with the generalized case directed by some other tooling. Other bits in the GitOps toolkit may. An opinionated way to implement a common flow should be documented. And ideally not require the end-administrator to reimplement common logic themselves.

Tasks need to be further detailed out:

• #29
• Request technical doc review by CNCF/LF
  • Add support ticket https://cncfservicedesk.atlassian.net/servicedesk/customer/portal/1/CNCFSD-954?created=true
  • Added to CNCF techdocs queue (to be addressed after kubecon) https://github.com/cncf/techdocs/projects/3
  • Actual review

Hi openGitOps team,

As principles reached version 1.0, I was wondering if you think valuable to have some translations to ease the spread?
If yes, how would you like to manage this? dedicated i18n folder + tagging which markdown files need to be considered ?
I can manage it for french with some reviewers.

Best,
Philippe

So far I've mostly seen GitOps described from a "developers" persona. Several of the "GitOps benefits" described in the README list benefits that are more "operational" in nature:

• Increased Developer & Operational Productivity
• Improved Stability
• Higher Reliability

Given these "operational" benefits I believe it would be good to include "operator" persona in this GitOps Manifesto. Some "operational" concerns that come to my mind would be:

• User/Identity Management between "git" and "k8s" i.e. should the set of users be shared between them or should they be purposefully different
• Secret Management (which has already been mentioned separately in Issue gitops-working-group/gitops-working-group-old#16)
• Git Repo Sprawl i.e. how does an "operator" reconstruct all the applications/deployments/configuration for a specific k8s cluster from all the possible git repos that "control" the intended state of the cluster in the case of Disaster Recovery

I'm sure there are other concerns "operators" will have with GitOps that should be addressed by this GitOps Manifesto.

By doing GitOps access control moves from Kubernetes to git. Controllers which apply git resources to a cluster such as GitOps Engine might provide mechanisms to control which kinds of resources might be applied or in which namespaces those might be created.

Managing larger clusters, which contain applications from multiple teams moves permission management from pure RBAC within the cluster to git. It suddenly becomes important to which repositories people have access to, where they can make changes and who needs to approve what.

Repository features, which allow you to control who needs to review which directory are helpful, but not the only thing to consider.

Documentation around repository best practices explaining pros and cons of different setups might guide users to decide based on their needs.

Some options worth describing:

• one repo per cluster
• one cluster repo + one/multiple application repositories
• different stages within one repo vs staged in branches vs different repos per stage

The "notes" on the principles should each be addressed so they are no longer necessary to live there and that temporary section is removed entirely. This is what principles committee agreed to during the pre-release editing phase.

They should be either resolved, or added to the next best supporting document location (in glossary, best practices, use cases, etc). IMO this is important for a v1.0.0 release.

There is a broken anchor link in the Spanish translation of the glossary in line 25 where it points to (#desvio) should be [desvio](#desvio).

Good initial idea

The principles version was added to the header in markdown so that, when printed (and hung in every tech office in the world!), it will be clear which version of the principles is on view.

New problem

However, the problem is that in-between releases the last version is still part of the markdown header even as new changes are approved and merged into main. Take a look at this oneline commit history sample from today:

You can see there are 4 commits after tag v0.1.0 which a user could view that still contain # GitOps Principles v0.1.0 at the top of PRINCIPLES.md.

Recommended fix

Remove principles version from header markdown in main to a separate commit in release branches. Can be manual at first then automated.

In the Language README.md I suggest name language also both in English in their own language.

https://github.com/open-gitops/documents/blob/main/i18n/README.md

Change to this:

German / Deutsch
Spanish / Español
Portuguese / Português
French / Français

OR Change to this:

Deutsch (German)
Español (Spanish)
Português (Portuguese)
Français (French)

I am working in IT, but have an automation engineering background from university. For me, as an engineer, one key feature of a closed-loop control system is to be able to catch/react to disturbances (in the picture called "load"), which are not directly measured, or are even unkown effects, which affect the system.
An example in a k8s cluster could be a node which dies. If this is not measured (normally it is, but to make this example valid), this would be a disturbance, which affects the system from outside, changes the actual vs desired state, and therefore, affects the cluster operation. But as we have Feedback, new pods are scheduled, routing is adjusted etc. So because you are able to observe the disturbance, you can take actions to mitigate it. And you are only able to see these disturbances, as they get visible in the Feedback of the system.
And from my point of view, this inherent feature, to catch/react to disturbances with a closed-loop, makes e.g. k8s so robust.

Edit: removed the controller part

Same reasoning as #20

GLOSSARY.md should follow the same pattern now that it's in a separate file.

Hi Folks

On the one hand, GitOps increase the security itself through limitation to a minimum of administrative access to infrastructure and configuration, eliminate human error, an audit of any change, declarative single source of truth, automatic verification, and policy enforcement. Using GitOps tools and technologies, organizations can mitigate the vectors of attack by reducing the number of people and machines that have access to the target system.
On the other hand, more attention should be paid to securing Git repositories and CI/CD processes.

I would like to open a discussion about the security of GitOps and in particular what are the best security practices. And as a result create a dedicated document.

Based on the conversation in the todays WG Fortnightly, did we want to add discussions to this repository and add categories based on work streams? We obviously still need to define how we want things documented (pun intended) but if we get a place where we can suggest specific topics that we want to explore or check for interest, we would be better situated when we start to work.

Of the top of my head the only category suggestions I could come up with is:

• Security
• Lifecycle (and/or) Operations
• Patterns

Having these discussions in this repository would help to keep things tidy, and not overwhelm people when they look at discussions in the project repo.

Adding anchor links to each principle was a good idea, per open-gitops/project#166.

Thanks for implementing that in this PR. However, the PR also changed the markdown ordered list to an unordered list, which – according to our recorded principle committee meetings and Kubecon talks where we explain on stage that the order matters, as each principle must build upon the previous ones – we want to keep the numbers. #67

Please re-add principle numbering. Thanks!

Since the creation of the GitOps Working Group and The OpenGitOps Project, the community has provided ample insights, feedback and commentary related to the GitOps Principles. This issue attempts to reconcile references to all that information in one single location, towards having clear visibility into the community views as we work towards 1.0RC1:

Discussions

• https://github.com/gitops-working-group/gitops-working-group/discussions/129
• https://github.com/gitops-working-group/gitops-working-group/discussions/93
• open-gitops/project#17 (comment)

Pull Request

• Legacy Principles Discussion: gitops-working-group/gitops-working-group#48 (Closed)
• Simplify Principles: #14

Project

• https://github.com/open-gitops/documents/milestone/6

Our first draft attempting to reconcile all views as shared by the community into a RC will be taken place in the following HackMD Document: https://hackmd.io/@vKEUvseCSBGjQWVuAWA_7g/Bk6e-P_lF/edit

There has been some feedback about the initial summary sentence of each principle, as of v0.1.0.

1. The repeated use of "the principle of" feels repetitive

   The group agrees that prefix should be removed from each principle, but there is still the question of how to adjust what we're left with once removed.

2. Overall the wording of each initial sentence is a bit too complex, and not easily memorable.

   The group agrees that as long as the underlying meaning of each principle isn't lost, the intro sentence of each could simplified, and ideally be more "catchy".

   The group is however overall satisfied with the 1-2 sentence full description below each initial summary sentence. One exception could be potentially making principle 4 more explicit.

There should be a acceptance criteria for people doing PRs for things like Whitepapers/Greenpapers/Patterns/etc.

Currently, we've only verbally agreed that "as long as it conforms to the principals it should be okay". While this is fine for now, we should eventually define these.

For:

• Code: Apache 2.0. html, text
• Non-code: CC BY 4.0. html, text

References:

• https://en.wikipedia.org/wiki/Wikipedia:Multi-licensing
• CNCF Charter 9(b)iii.a and 11(b-g). https://github.com/cncf/foundation/blob/master/charter.md
• GitHub default community health files do not support licenses, so:

  License files must be added to individual repositories so the file will be included when a project is cloned, packaged, or downloaded

Related:

• https://github.com/gitops-working-group/gitops-working-group/discussions/77

I need a German translation of the principles and I will be happy to coordinate the work on that.

Anybody interested please contribute to https://docs.google.com/document/d/1uwcNXo-hfJsqloW58pjByE3nVI-0zNHGeg47E9aAvAc/edit?usp=sharing

Update

Meeting notes have been transferred to the main GWG meeting notes doc, so everyone can contribute to notes.

Link for this week's notes: https://docs.google.com/document/d/1hxifmCdOV5_FbKloDJRWZQHq0ge-trXJKF-BgV4wHVk/edit#heading=h.lfuaf62iclbk

What we've done so far and plans

• @todaywasawesome, @murillodigital and I all tried to bear this in mind before publishing RC 2
• The longer-term effort, #73 – originally planned for v1.0.0 release milestone – has now been moved to a post-KubeCon NA 2021 milestone. There is now an internal CNCF support ticket for this, which has already been noticed by and CNCF techdocs team and soon will be added to the techdocs queue! It will for sure not happen until after KubeCon NA 2021.

How you can help now

We can at least do a best effort internal review before KubeCon. Can we please get more eyes on this from WG members and maintainers before the planned v1.0.0 release at the end of this week?

1. Please re-read PRINCIPLES.md, GLOSSARY.md, and README.md from a language accessibility point of view. You can comment here or give an emoji reaction if that is more efficient.

2. We are now asking YOU – WG members & maintainers – to 👍 or 👎 this issue by Friday Oct 8th. (ideally, also comment a short reason).

   Note this does not require language accessibility expertise – that is scheduled with CNCF already. This is an ask for one more best effort pass by WG members available to do so before 1.0.0 goes out.

Thanks! 😄