Clarify the meaning of "pull"

[todaywasawesome]

In light of ongoing discussions and questions in slack, of which this is the most recent example, it seems prudent to explain what pull means.

Sometimes, readers understand "pull" to mean that GitOps agents must live in the infrastructure under management so that it is self-sufficient and does not require external agents. This however, is not the intention of the word pull. The word pull here is specifically in reference to how desired state is discovered.

• Traditional CI/CD uses event-based triggers that "push" information to pipelines which then execute to perform updates
• Event-based triggers create a pseudo source of truth, where the desired state is carried in event-triggers rather than in git itself
• Pull specifically references how desired state is discovered
• Webhooks may fire and show value by speeding up the process of change discovery
• Should webhooks fail, GitOps agents should still be able to discover changes.

Proposal
Add a glossary item explaining pull and capturing the logic that originally went into the principles.

[scottrigby]

Thanks @todaywasawesome

From my reply in that Slack thread:

One important point here from our principles discussions is that for GitOps agents to reconcile drift at any time, regardless of how it occurs, they always need access to the desired state, regardless of whether there is an intended event (like a new Git commit) to trigger a push. This is why we use the word pull in the principle

We currently note this in the Glossary under Reconciliation:

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 from the desired state declarations, or a new desired state declaration version having been changed intentionally.

Cross-linking PR:

• Add glossary item for "pull" documents#65

Also linking previous discussion topics where this was touched on:

• Does GitOps apply to on-prem infrastructure? #101
• Usage of continuous in GitOps Principle Nr. 3 #80

[scottrigby]

This PR is ready for review. I believe we have addressed all open comments so far. Everyone is welcome to add reviews/comments there, whether you are a maintainer or not. We would ideally like to get more feedback before merging this. This would be part of a the next minor (semver) release of the principles.

• Add glossary item for "pull" documents#65

[christianh814]

I don't think it hurts to have an additional glossary term around what we mean by "pull". Especially since "pull/push" actually means something and we are using "pull" almost orthogonality from the "original" meaning.

[scottrigby]

I completely agree. Mentioning existing language so we can tie these together properly when we do

[ubaumann]

I think it is essential to clarify the meaning of principle number 3 and clarify that the way to achieve it is not the main point.

So if I translate number 3 into my own words, it would be something like "GitOps agent always needs to be able to retrieve the desired state from the SSoT, but we don't want to have a second SSoT or anything that could get a sync conflict."

So I suggested in the PR adding the sentence, "The GitOps agents need to be able to access the desired state at any time to avoid drifts."
But most likely, there is a better way to faze it.

[todaywasawesome]

That would imply that it is only capable of retrieving desired state and not automatically actually doing it. It's not meant to be a commentary on the uptime of git. It's the agent that draws the state continuously.

[ubaumann]

I certainly understand that rephrasing a principle is not the most popular choice, but how about replacing "pull" with "retrieve"?

[ubaumann]

@scottrigby My native language would be Swiss-German, but I saw you already have a German translation.

Maybe it is because I am not a native speaker, but I associate "pull" automatically with "git pull". And the agent could use any method/protocol to retrieve the desired state like HTTP Get, (g)RPC, or a fancy implementation using QUIC.

[scottrigby]

Oh, interesting. I can see an association with git pull. Is the concern that people will read this and believe they need to store their desired state declarations in Git? I hope we are clear enough in Principle 2 - and further emphasized in the State Store glossary item – that this is not the case:

State Store
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, 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.

I had understood this concern to be one of "push" vs "pull", which has come up in questions before (not this is still related, since git pull is only one of various method for pulling desired state). Can you please clarify if your main concern is implying that Git must be used for state store?

Either way I think this linked Glosssary item is a really good clarification to Principle 3.

[ubaumann]

Well, I have two points. First, I think people new to GitOps principle 3 can be misled by the word "push".
Secondly, I believe the protocol and direction are not critical to principle 3. Of course, a push is the most logical way but maybe not always be possible.

From my understanding, the most critical thing about principle 3 is to always access the up-to-date desired state without relying on any events.

As discussed in the Slack channel, it is possible the connection to a security zone can only be opened from outside. One suggestion was to have a git cash server in the "less secure" area and the GitOps agent "pulls" the change from there. I am not a big fan of duplicated data, as we must ensure the cash server always has the same data as our SSoT. Now we have an additional component with a potential drift. So if I need to ensure this cash server is always up-to-date, I can also ensure my GitOps agent is always up-to-date. I could use, for example, something as simple as rsync. But to fit principle 3, it can not be event-based (on a git commit).

So I wish to clarify principle 3 to reduce the risk people interpret it differently and focus more on the why than on the how.

[christianh814]

Well, I have two points. First, I think people new to GitOps principle 3 can be misled by the word "push". Secondly, I believe the protocol and direction are not critical to principle 3. Of course, a push is the most logical way but maybe not always be possible.

From my understanding, the most critical thing about principle 3 is to always access the up-to-date desired state without relying on any events.

As discussed in the Slack channel, it is possible the connection to a security zone can only be opened from outside. One suggestion was to have a git cash server in the "less secure" area and the GitOps agent "pulls" the change from there. I am not a big fan of duplicated data, as we must ensure the cash server always has the same data as our SSoT. Now we have an additional component with a potential drift. So if I need to ensure this cash server is always up-to-date, I can also ensure my GitOps agent is always up-to-date. I could use, for example, something as simple as rsync. But to fit principle 3, it can not be event-based (on a git commit).

So I wish to clarify principle 3 to reduce the risk people interpret it differently and focus more on the why than on the how.

So the more I think about this, and the more you explain it the more I disagree and I'm liking the word "pull". I don't like the word "event" because a reconciliation loop can also be interpreted as an event. Saying "without an event" is sort of like saying "by magic". Which is also not helpful.

With the example of the "cache"; I don't see an issue with this cache. In this model the Cache becomes true SSoT.

Example:

I have my declarations on GitHub but my cluster is arigapped. I then have to, somehow, get those declarations on to the Co-located "git cache" that's in the airgapped system. At that point, that "git cache" is my SSoT, not github. If there's a divergence, that's a people/process problem. Just the same as me forgetting to merge a pull request. There's a divergence there too.

I do agree, however, that we should make it clear that we do NOT mean "git pull"

My two cents.

[ubaumann]

I assume my English is not well enough to express myself.

I agree that "without an event" is not the best wording. Probably something like "without external trigger" would be better.
My main point is still the same. I think the 3rd principle should make clear why the agent needs the information of the SSoT and not how it gets it technically.

Using the word agent should make it clear it is not triggered by an external event. However, if it is pulled/received/synced from X should not meather.

How to handle an air-gapped environment is probably off-topic as it will probably end in a "management" problem.