docs: add cilium-operator technical overview documentation

[fristonio]

Fixes #13298

[aanm]

Looks great!

[ungureanuvladvictor]

LGTM

[christarazi]

This is great! Pointed out mostly minor things for consistency and clarity

[qmonnet]

Looks great, thanks for the doc!
Please find a few nits inline. Additionally,

• Please make sure to be consistent and use either regular or title case for all titles.
• Should this document be moved elsewhere than the root of Documentation? Maybe Documentation/concepts/ at least?

[stale]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[qmonnet]

It looks like this PR is waiting for my approval to be merged, but I would still appreciate to have

• Consistent title case on titles (+ consistency on expansion, or not, of “Garbage Collection”),
• Consistent case on “KVStore”.

Would it make sense to add a directory for documentation oriented towards developers? We probably don't want to move the existing documents bpf, hubble etc.), but that would avoid adding too many new documents to the root of the Documentation/ as this section grows?

[fristonio]

@qmonnet I have updated the docs to have a more consistent format for the specifics you mentioned. Let me know if I missed something.

Would it make sense to add a directory for documentation oriented towards developers?

Yeah, I think it makes sense to do this. I don't have a concrete option for this though, we can possibly have a section inside For Developers called Internals and put hubble and these operator docs under it?

[qmonnet]

Thanks for the changes!

we can possibly have a section inside For Developers called Internals and put hubble and these operator docs under it?

Yes, this sounds like a good option to me, let's do this please.

[fristonio]

@qmonnet I have added a section for Cilium components specific internals under For Developers. Let me know if you see a way we can improve it.

[qmonnet]

Thanks! Looks good, I'm just wondering if we're OK with moving the Hubble doc (I thought you meant reorganising the TOC, I didn't think you would rename the file and change the URL). I think it's fine, because if people want stable links, they should use a version number in the URL, but I'm not entirely sure of our policy on that. I'd appreciate another look from @joestringer, for example.

[joestringer]

👍 I'm okay with this. We can also set up redirects so that the old link leads to the new location.

[qmonnet]

Ok let's go with this version then 👍
Do you know how we would add a redirect, is it configured in this repo in Documentation/ (I could not find it), or on the hosting platform?

[joestringer]

It's configured in the hosting platform (https://readthedocs.org/dashboard/cilium/redirects/). I have access, I just need source and destination paths and I can add it. I'm not exactly sure whether it unconditionally redirects or whether it only redirects in the case of direct navigation hitting a 404 so we may need to do a little investigation together there.

[fristonio]

Hey @joestringer
I am happy to help setup the redirect. If setting path based redirect is possible then we need a redirect from /hubble to /internals/hubble. The URL for the two looks will like this for latest version:

• https://docs.cilium.io/en/latest/hubble/
• https://docs.cilium.io/en/latest/internals/hubble/

[joestringer]

The Hubble/K8s codeowners are only pulled in because the files are touched, but the validation is more related to docs codeowners. Good to merge.

[joestringer]

Will just close/reopen to kick GH workflows to double-check that docs tests pass before merge.

[joestringer]

I set up the redirect, looks like it's working correctly. 👍

[fristonio]

Thanks a lot @joestringer