docs: Add git proxy support docs

[darkowlzz]

#524 added support for git proxy in libgit2. We discovered various things that doesn't work as expected. This change documents the limitations we discovered in libgit2 git proxy support.

[darkowlzz]

Unrelated change. I used https://github.com/godlygeek/tabular to automatically format the table.
I can undo it and keep it simple if it'd be easier to maintain.

[darkowlzz]

@racdev and @au2001, would love to have your feedback on documenting git proxy support. Anything that'd be useful and need to be clarified?

[au2001]

racdev and au2001, would love to have your feedback on documenting git proxy support. Anything that'd be useful and need to be clarified?

@darkowlzz To help readers applying a proxy to their Flux installation, it might be a good idea to provide an example.
Here is an extract of the JSON patch I'm using (the same can be done through a strategic merge):

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- gotk-components.yaml
- gotk-sync.yaml
patches:
- patch: |
    - op: add
      path: /spec/template/spec/containers/0/env/-
      value:
        name: HTTPS_PROXY
        value: http://x.x.x.x:yyyy
    - op: add
      path: /spec/template/spec/containers/0/env/-
      value:
        name: NO_PROXY
        value: localhost,.local,.local.
  target:
    kind: Deployment
    labelSelector: app.kubernetes.io/part-of=flux
    namespace: flux-system

Note that those environment variables are applied to all Flux controllers and not just source-controller.
This is because other controllers, such as image-automation-controller if it has been installed, also use these for accessing any remote resource (i.e. Git and Helm repositories, container registries...).
Kinda off-topic: I opened the PR fluxcd/image-automation-controller#285 to apply the same fix as we did on source-controller because you cannot yet push image updates to a Git server through a proxy.

As for current known issues related to source-controller, I think it's definitely worth mentioning the CAFile/custom Transport issue: you cannot use a proxy at the same time as HTTPS self-signed certificates because of an implementation limitation in go-git (but it should work fine when using libgit2 explicitly).

I'm not sure if it's worth mentioning the caching issue we ran into while using go-git.
What it means is that you cannot change the proxy environment variables in a source-controller pod while it's running.
But as far as I know it is not possible to change environment variables on a running pod anyways, or at least it's unsupported.

[darkowlzz]

@au2001 Thanks. Self-signed cert issue with go-git is an important thing to note.

Since this is an API doc, it'd be better to not have examples of adding env vars here. But thanks for sharing the example here. Would be useful for others if they look for it.

The caching issue happens only during the lifetime of a go program. We saw that it wasn't an issue when running the tests separately. So, I don't think we need to mention anything about it, also considering that this will run in pods, as you mentioned.

[au2001]

Since this is an API doc, it'd be better to not have examples of adding env vars here.

The caching issue happens only during the lifetime of a go program. We saw that it wasn't an issue when running the tests separately. So, I don't think we need to mention anything about it, also considering that this will run in pods, as you mentioned.

@darkowlzz Alright, fine with me.
Then everything looks good to me now! Can't think of anything else worth mentioning in the API docs.