Add proxy config docs (canonical#389)

* Add proxy config docs

* add examples for proxy config of charms

docs/src/charm/howto/index.md

@@ -16,6 +16,7 @@ Overview <self>
 
 charm
 etcd
+proxy
 contribute
 
 ```

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.
+```
+
+<!-- LINKS -->
+
+[Juju model]: https://juju.is/docs/juju/model

docs/src/charm/reference/index.md

@@ -13,6 +13,8 @@ Overview <self>
 
 releases
 charms
+proxy
+architecture
 community
 
 ```

docs/src/charm/reference/proxy.md

@@ -0,0 +1,2 @@
+```{include} /snap/reference/proxy.md
+```

docs/src/snap/howto/index.md

@@ -18,7 +18,10 @@ install/index
 networking/index
 storage
 external-datastore
+cos-lite
+proxy
 contribute
+support
 ```
 
 ---

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].
+
+<!-- LINKS -->
+
+[documentation for adding proxy configuration via Juju]: /charm/howto/proxy

docs/src/snap/reference/index.md

@@ -16,6 +16,7 @@ commands
 troubleshooting
 community
 architecture
+proxy
 roadmap
 ```
 

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.
+
+<!-- LINKS -->
+
+[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