Add docs/dev/sig-network with the service proxy doc from kpng

[danwinship]

What this PR does / why we need it:

kubernetes/community#7421 stalled, and just got bounced away from lifecycle/rotten again, so let's try to jump start it.

This copies the service proxying doc from kpng into a new docs/dev/sig-network directory. It doesn't currently try to set up anything to deal with publishing it anywhere. The doc itself is mostly unmodified from the existing kpng version, with the largest change being to update it for the loadbalancer IPMode feature, which is new since the last updates to the kpng doc. (Diff from kpng version)

Although this doesn't yet solve the problem of making this doc more accessible to potential readers, it at least moves it to a better location, and maybe it will encourage other people to think about similar things? (And I have a partial doc on implementing NetworkPolicy to add to it, and I suspect I'll be writing up a doc on implementing and e2e-testing cloud load balancers too...)

Which issue(s) this PR fixes:

It is a start at addressing kubernetes/community#7421.

Does this PR introduce a user-facing change?

NONE

/kind documentation
/sig network

/assign @thockin

[k8s-ci-robot]

This issue is currently awaiting triage.

If a SIG or subproject determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[thockin]

Thanks!

/lgtm
/approve

/hold for a few days to see if anyone balks

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: e150c644a89efcafb291ed4882ae11cad73b6d0e

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: danwinship, thockin

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• docs/OWNERS [thockin]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[aojea]

The problem I see of adding docs here is that then you are tied to the releases and its rules, code freeze, test freeze ... if the problem is discovery an alternative is just create a docs/README.md that redirect to the community ...

In any case, having the docs in both places at the same time is fragmented and still more confusing

[danwinship]

Read the linked issue; part of the goal of putting them here was to make it easier to modify the docs at the same time as the APIs. And neither code freeze nor test freeze applies to docs anyway, right? (If the existing descriptions are unclear about that, it's probably because there currently isn't much in the way of docs in k/k.)

[aojea]

Read the linked issue; part of the goal of putting them here was to make it easier to modify the docs at the same time as the APIs. And neither code freeze nor test freeze applies to docs anyway, right? (If the existing descriptions are unclear about that, it's probably because there currently isn't much in the way of docs in k/k.)

I don't feel we'll have the discipline to update the docs and the APIs, but I can be wrong and I will be super happy of being wrong ... still, or all the sigs do the same and move the docs in tree, or having it fragmented with sigs in one places and others in other place looks worse situation than before ...

[thockin]

This is the conversation I wanted to have. Today, it's far too easy to forget to update docs having them in-tree means I can do it in one PR. Obviously, IMO, these won't be the only or even final docs with translation etc.

I want things to be easier to find, and close to the places they are used. This doc is really aimed at implementers. If we had a dedicated kube-proxy repo, maybe it would go there. That's an option - staging/src/k8s.io/kube-proxy/docs ?

I'd like API conventions to be similarly scoped.

[danwinship]

If we had a dedicated kube-proxy repo

We do, we just don't currently use it for anything except the versioned config APIs. (Though there's that vague plan to eventually move pkg/proxy there, once the APIs are in better shape.)

I guess the discussion in kubernetes/community#7421 mentioned that we could potentially be pulling content from multiple repos into the developer site, so this wouldn't block that.

OTOH I want to merge a NetworkPolicy implementation notes doc too, and that wouldn't really fit in k8s.io/kube-proxy (or, really, anywhere except k/k or sigs.k8s.io/network-policy-api).

(I also want to merge a cloud load balancer implementation notes doc, and that could fit in k8s.io/kube-proxy, though maybe it would be better in k8s.io/cloud-provider? I guess that's one down side of not using k/k/docs/devel; it makes it harder to figure out where any individual doc is.)

[thockin]

Those docs sound great!

Today the answer for such docs would be either https://git.k8s.io/community/contributors/devel/sig-network or https://git.k8s.io/community/sig-network - neither is terrible, but really "community" is not the repo wherein I would expect to find technical docs. IMO, these are not "glossy", end-user facing docs that need fancy formatting. They are (IMO) text docs (or simple markdown), which are aimed at implementors. I'm not AGAINST fancy formatting, but I don't want to waste time on it.

So, to me it makes sense to stick them in k/k/docs/..., but I would be fine with something like k/dev-docs/..., and if pressed I could just concede one of the above.