docs: Adjust k8s PROXY protocol tab
- Collapsed by default `question` admonition. - `warning` admonition relocated to start of Dovecot + Postfix config tabs section. - Wrapped duplicate ports intro paragraph into `info` admonition. - Minor formatting revisions to existing content.
This commit is contained in:
polarathene
parent
8eb966dece
commit
336452c89d
|
|
@ -499,7 +499,7 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
- DMS configuration changes for Postfix and Dovecot
|
- DMS configuration changes for Postfix and Dovecot
|
||||||
- [ ] To keep support for direct connections to DMS services internally within cluster, service ports must be "duplicated" to offer an alternative port for connections using PROXY protocol
|
- [ ] To keep support for direct connections to DMS services internally within cluster, service ports must be "duplicated" to offer an alternative port for connections using PROXY protocol
|
||||||
|
|
||||||
!!! question "What is the PROXY protocol?"
|
??? question "What is the PROXY protocol?"
|
||||||
|
|
||||||
PROXY protocol is a network protocol for preserving a client’s IP address when the client’s TCP connection passes through a proxy.
|
PROXY protocol is a network protocol for preserving a client’s IP address when the client’s TCP connection passes through a proxy.
|
||||||
|
|
||||||
|
|
@ -517,14 +517,16 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
|
|
||||||
!!! example
|
!!! example
|
||||||
|
|
||||||
A complete configuration, with duplicated ports, can be found down below in the "Traefik" section. The Postfx and Dovecot configuration is identical for other proxies (like NGINX).
|
**Configure the Ingress Controller**
|
||||||
|
|
||||||
=== "Traefik"
|
=== "Traefik"
|
||||||
|
|
||||||
On Traefik's side, the configuration is very simple.
|
On Traefik's side, the configuration is very simple.
|
||||||
|
|
||||||
- Create an entrypoint for each port that you want to expose (_probably 25, 465, 587 and 993_). Each entrypoint has a `IngressRouteTCP` configure a route to the appropriate internal port that supports PROXY protocol connections.
|
- Create an entrypoint for each port that you want to expose (_probably 25, 465, 587 and 993_).
|
||||||
- The below snippet demonstrates an example for two entrypoints, `submissions` (port 465) and `imaps` (port 993).
|
- Each entrypoint should configure an [`IngressRouteTCP`][traefik-docs::k8s::ingress-route-tcp] that routes to the equivalent internal DMS `Service` port which supports PROXY protocol connections.
|
||||||
|
|
||||||
|
The below snippet demonstrates an example for two entrypoints, `submissions` (port 465) and `imaps` (port 993).
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
@ -534,13 +536,10 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
metadata:
|
metadata:
|
||||||
name: mailserver
|
name: mailserver
|
||||||
|
|
||||||
# ...
|
|
||||||
|
|
||||||
spec:
|
spec:
|
||||||
# This an optimization to get rid of additional routing steps.
|
# This an optimization to get rid of additional routing steps.
|
||||||
type: ClusterIP # previously "LoadBalancer"
|
# Previously "type: LoadBalancer"
|
||||||
|
type: ClusterIP
|
||||||
# ...
|
|
||||||
|
|
||||||
---
|
---
|
||||||
apiVersion: traefik.io/v1alpha1
|
apiVersion: traefik.io/v1alpha1
|
||||||
|
|
@ -599,6 +598,18 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
**Adjust DMS config for Dovecot + Postfix**
|
||||||
|
|
||||||
|
??? warning "Only ingress should connect to DMS with PROXY protocol"
|
||||||
|
|
||||||
|
While Dovecot will restrict connections via PROXY protocol to only clients trusted configured via `haproxy_trusted_networks`, Postfix does not have an equivalent setting. Public clients should always route through ingress to establish a PROXY protocol connection.
|
||||||
|
|
||||||
|
You are responsible for properly managing traffic inside your cluster and to **ensure that only trustworthy entities** can connect to the designated PROXY protocol ports.
|
||||||
|
|
||||||
|
With Kubernetes, this is usually the task of the CNI (_container network interface_).
|
||||||
|
|
||||||
|
The 2nd approach adds a little more complexity, but is usually what you'd need.
|
||||||
|
|
||||||
=== "Only accept connections with PROXY protocol"
|
=== "Only accept connections with PROXY protocol"
|
||||||
|
|
||||||
!!! warning "Connections to DMS within the internal cluster will be rejected"
|
!!! warning "Connections to DMS within the internal cluster will be rejected"
|
||||||
|
|
@ -607,7 +618,7 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
|
|
||||||
This can be problematic when you also need to support internal cluster traffic directly to DMS (_instead of routing indirectly through the ingress controller_).
|
This can be problematic when you also need to support internal cluster traffic directly to DMS (_instead of routing indirectly through the ingress controller_).
|
||||||
|
|
||||||
Here is an example configuration for [Postfix][docs-postfix], [Dovecot][docs-dovecot], and the adjustments to the `Deployment` config. The port names are adjusted here only for the additional context as described previously.
|
Here is an example configuration for [Postfix][docs-postfix], [Dovecot][docs-dovecot], and the required adjustments for the `Deployment` config. The port names are adjusted here only to convey the additional context described earlier.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
kind: ConfigMap
|
kind: ConfigMap
|
||||||
|
|
@ -680,12 +691,14 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
|
|
||||||
=== "Separate PROXY protocol ports for ingress"
|
=== "Separate PROXY protocol ports for ingress"
|
||||||
|
|
||||||
|
!!! info
|
||||||
|
|
||||||
Supporting internal cluster connections to DMS without using PROXY protocol requires both Postfix and Dovecot to be configured with alternative ports for each service port (_which only differ by enforcing PROXY protocol connections_).
|
Supporting internal cluster connections to DMS without using PROXY protocol requires both Postfix and Dovecot to be configured with alternative ports for each service port (_which only differ by enforcing PROXY protocol connections_).
|
||||||
|
|
||||||
- The ingress controller will route public connections to the internal alternative ports for DMS (`*-proxy` variants).
|
- The ingress controller will route public connections to the internal alternative ports for DMS (`*-proxy` variants).
|
||||||
- Internal cluster connections will instead use the original ports configured for the DMS container directly (_which are private to the cluster network_).
|
- Internal cluster connections will instead use the original ports configured for the DMS container directly (_which are private to the cluster network_).
|
||||||
|
|
||||||
In this example we'll create a copy of the original service ports with PROXY protocol enabled, and increment the port number assigned by `10000. You could run each of these commands within an active DMS instance, but it would be more convenient to persist the modification via our `user-patches.sh` feature:
|
In this example we'll create a copy of the original service ports with PROXY protocol enabled, and increment the port number assigned by `10000`. You could run each of these commands within an active DMS instance, but it would be more convenient to persist the modification via our `user-patches.sh` feature:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
#!/bin/bash
|
#!/bin/bash
|
||||||
|
|
@ -722,13 +735,7 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
!!! warning
|
The `Deployment` needs to update the `ports` section by appending these new ports:
|
||||||
|
|
||||||
You are responsible for properly managing traffic inside your cluster and to **ensure that only trustworthy entities** can connect to the designated PROXY protocol ports. With Kubernetes, this is usually the task of the container network interface.
|
|
||||||
|
|
||||||
While Dovecot provides a very basic machanims to achieve firewalling connections via `haproxy_trusted_networks`, Postfix does not provide ann equivalent at all.
|
|
||||||
|
|
||||||
Last but not least, the `ports` section in the `Deployment` needs to be changed. The following ports have to be added:
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
- name: smtp-proxy
|
- name: smtp-proxy
|
||||||
|
|
@ -751,7 +758,6 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
|
|
||||||
[github-web::docker-mailserver-helm]: https://github.com/docker-mailserver/docker-mailserver-helm
|
[github-web::docker-mailserver-helm]: https://github.com/docker-mailserver/docker-mailserver-helm
|
||||||
[metallb-web]: https://metallb.universe.tf/
|
[metallb-web]: https://metallb.universe.tf/
|
||||||
|
|
||||||
[kustomize]: https://kustomize.io/
|
[kustomize]: https://kustomize.io/
|
||||||
[cert-manager]: https://cert-manager.io/docs/
|
[cert-manager]: https://cert-manager.io/docs/
|
||||||
[docs-tls]: ../security/ssl.md
|
[docs-tls]: ../security/ssl.md
|
||||||
|
|
@ -760,6 +766,7 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
|
||||||
[docs-mailserver-behind-proxy]: ../../examples/tutorials/mailserver-behind-proxy.md
|
[docs-mailserver-behind-proxy]: ../../examples/tutorials/mailserver-behind-proxy.md
|
||||||
[docker-docs::compose::network_mode]: https://docs.docker.com/compose/compose-file/compose-file-v3/#network_mode
|
[docker-docs::compose::network_mode]: https://docs.docker.com/compose/compose-file/compose-file-v3/#network_mode
|
||||||
[dockerhub-haproxy]: https://hub.docker.com/_/haproxy
|
[dockerhub-haproxy]: https://hub.docker.com/_/haproxy
|
||||||
|
[traefik-docs::k8s::ingress-route-tcp]: https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/#kind-ingressroutetcp
|
||||||
[Kubernetes-nginx]: https://kubernetes.github.io/ingress-nginx
|
[Kubernetes-nginx]: https://kubernetes.github.io/ingress-nginx
|
||||||
[Kubernetes-nginx-expose]: https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services
|
[Kubernetes-nginx-expose]: https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services
|
||||||
[Kubernetes-network-service]: https://kubernetes.io/docs/concepts/services-networking/service
|
[Kubernetes-network-service]: https://kubernetes.io/docs/concepts/services-networking/service
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue