From f2711d3290200dce1b9412feabb021033b422da8 Mon Sep 17 00:00:00 2001 From: Nick Veitch Date: Wed, 1 May 2024 17:56:33 +0100 Subject: [PATCH] Add proxy config docs (#389) * Add proxy config docs * add examples for proxy config of charms --- docs/src/charm/howto/index.md | 1 + docs/src/charm/howto/proxy.md | 33 ++++++++++++++++++++++ docs/src/charm/reference/index.md | 2 ++ docs/src/charm/reference/proxy.md | 2 ++ docs/src/snap/howto/index.md | 3 ++ docs/src/snap/howto/proxy.md | 47 +++++++++++++++++++++++++++++++ docs/src/snap/reference/index.md | 1 + docs/src/snap/reference/proxy.md | 41 +++++++++++++++++++++++++++ 8 files changed, 130 insertions(+) create mode 100644 docs/src/charm/howto/proxy.md create mode 100644 docs/src/charm/reference/proxy.md create mode 100644 docs/src/snap/howto/proxy.md create mode 100644 docs/src/snap/reference/proxy.md diff --git a/docs/src/charm/howto/index.md b/docs/src/charm/howto/index.md index 448eeb95a..40fc11ea9 100644 --- a/docs/src/charm/howto/index.md +++ b/docs/src/charm/howto/index.md @@ -16,6 +16,7 @@ Overview charm etcd +proxy contribute ``` diff --git a/docs/src/charm/howto/proxy.md b/docs/src/charm/howto/proxy.md new file mode 100644 index 000000000..abfd79de6 --- /dev/null +++ b/docs/src/charm/howto/proxy.md @@ -0,0 +1,33 @@ +# Configuring proxy settings for K8s + +Canonical Kubernetes packages a number of utilities (eg curl, helm) which need +to fetch resources they expect to find on the internet. In a constrained +network environment, such access is usually controlled through proxies. + +## Adding proxy configuration for the k8s charms + +For the charm deployments of Canonical Kubernetes, Juju manages proxy +configuration through the [Juju model]. + +For example, assume we have a proxy running at `http://squid.internal:3128` and +we are using the networks `10.0.0.0/8`,`192.168.0.0/16` and `172.16.0.0/12`. In +this case we would configure the model in which the charms are to run with +Juju: + +``` +juju model-config \ + juju-http-proxy=http://squid.internal:3128 \ + juju-https-proxy=http://squid.internal:3128 \ + juju-no-proxy=10.0.8.0/24,192.168.0.0/16,127.0.0.1,10.152.183.0/24 +``` + +```{note} The **10.152.183.0/24** CIDR needs to be covered in the juju-no-proxy + list as it is the Kubernetes service CIDR. Without this any pods will not be + able to reach the cluster's kubernetes-api. You should also exclude the range + used by pods (which defaults to **10.1.0.0/16**) and any required + local networks. +``` + + + +[Juju model]: https://juju.is/docs/juju/model diff --git a/docs/src/charm/reference/index.md b/docs/src/charm/reference/index.md index a97b301b6..b4520ab3c 100644 --- a/docs/src/charm/reference/index.md +++ b/docs/src/charm/reference/index.md @@ -13,6 +13,8 @@ Overview releases charms +proxy +architecture community ``` diff --git a/docs/src/charm/reference/proxy.md b/docs/src/charm/reference/proxy.md new file mode 100644 index 000000000..e4dfd0e16 --- /dev/null +++ b/docs/src/charm/reference/proxy.md @@ -0,0 +1,2 @@ +```{include} /snap/reference/proxy.md +``` \ No newline at end of file diff --git a/docs/src/snap/howto/index.md b/docs/src/snap/howto/index.md index 1560eb6e7..48195e137 100644 --- a/docs/src/snap/howto/index.md +++ b/docs/src/snap/howto/index.md @@ -18,7 +18,10 @@ install/index networking/index storage external-datastore +cos-lite +proxy contribute +support ``` --- diff --git a/docs/src/snap/howto/proxy.md b/docs/src/snap/howto/proxy.md new file mode 100644 index 000000000..43786eb40 --- /dev/null +++ b/docs/src/snap/howto/proxy.md @@ -0,0 +1,47 @@ +# Configure proxy settings for K8s + +Canonical Kubernetes packages a number of utilities (eg curl, helm) which need +to fetch resources they expect to find on the internet. In a constrained +network environment, such access is usually controlled through proxies. + +On Ubuntu and other Linux operating systems, proxies are configured through +system-wide environment variables defined in the `/etc/environment` file. + +## Adding proxy configuration for the k8s snap + +Edit the `/etc/environment` file and add the relevant URLs + +```{note} It is important to add whatever address ranges are used by the + cluster itself to the `NO_PROXY` and `no_proxy` variables. +``` + +For example, assume we have a proxy running at `http://squid.internal:3128` and +we are using the networks `10.0.0.0/8`,`192.168.0.0/16` and `172.16.0.0/12`. We +would edit the environment (`/etc/environment`) file to include these lines: + +``` +HTTPS_PROXY=http://squid.internal:3128 +HTTP_PROXY=http://squid.internal:3128 +NO_PROXY=10.0.0.0/8,192.168.0.0/16,127.0.0.1,172.16.0.0/12 +https_proxy=http://squid.internal:3128 +http_proxy=http://squid.internal:3128 +no_proxy=10.0.0.0/8,192.168.0.0/16,127.0.0.1,172.16.0.0/12 +``` + +Note that you may need to restart for these settings to take effect. + +```{note} The **10.152.183.0/24** CIDR needs to be covered in the juju-no-proxy + list as it is the Kubernetes service CIDR. Without this any pods will not be + able to reach the cluster's kubernetes-api. You should also exclude the range + used by pods (which defaults to **10.1.0.0/16**) and any required + local networks. +``` + +## Adding proxy configuration for the k8s charms + +Proxy confiuration is handled by Juju when deploying the `k8s` charms. Please +see the [documentation for adding proxy configuration via Juju]. + + + +[documentation for adding proxy configuration via Juju]: /charm/howto/proxy diff --git a/docs/src/snap/reference/index.md b/docs/src/snap/reference/index.md index 0eb533102..cb16ad790 100644 --- a/docs/src/snap/reference/index.md +++ b/docs/src/snap/reference/index.md @@ -16,6 +16,7 @@ commands troubleshooting community architecture +proxy roadmap ``` diff --git a/docs/src/snap/reference/proxy.md b/docs/src/snap/reference/proxy.md new file mode 100644 index 000000000..fc51b180c --- /dev/null +++ b/docs/src/snap/reference/proxy.md @@ -0,0 +1,41 @@ +# Proxy environment variables + +Canonical Kubernetes uses the standard system-wide environment variables to +control access through proxies. + +On Ubuntu and other Linux operating systems, proxies are configured through +system-wide environment variables defined in the `/etc/environment` file. + +- **HTTPS_PROXY** +- **HTTP_PROXY** +- **NO_PROXY** +- **https_proxy** +- **http_proxy** +- **no_proxy** + +## No-proxy CIDRS + +When configuring proxies, it is important to note that there are always some +CIDRs which need to be excluded and added to the `no-proxy` lists. For +Canonical Kubernetes these are: + +- The range used by Kubernetes services (defaults to **10.152.183.0/24**) +- The range used by the Kubernetes pods (defaults to **10.1.0.0/16**) + +And it is also important to exclude the local network to maintain access to any +local traffic. + +## Configuring + +For the `k8s` snap, proxy configuration is controlled by editing the +`etc/environment` file mentioned above. There is an example in the +[How to guide for configuring proxies for the k8s snap][]. + +For charms deployed by Juju, proxies are managed by configuring the model. See +the [How to guide for configuring proxies for k8s charms][] for an example of +how to set these. + + + +[How to guide for configuring proxies for the k8s snap]: /snap/howto/proxy +[How to guide for configuring proxies for k8s charms]: /charm/howto/proxy