Merge branch 'docker-mailserver:master' into master

j-heffron · web-flow · commit 36a68db3b0a9 · 2025-11-07T08:00:47.000Z
diff --git a/.github/workflows/on-push-lint-charts.yml b/.github/workflows/on-push-lint-charts.yml
@@ -13,7 +13,7 @@ on:
 
 env:
   KUBE_SCORE_VERSION: 1.17.0
-  HELM_VERSION: v3.13.2
+  HELM_VERSION: v3.19.0
 
 concurrency:
   group: ${{ github.ref }}
@@ -29,7 +29,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Helm
-        uses: azure/setup-helm@v3
+        uses: azure/setup-helm@v4.3.0
         with:
           version: ${{ env.HELM_VERSION }}
 
@@ -64,7 +64,7 @@ jobs:
     strategy:
       matrix:
         # Choose from https://hub.docker.com/r/kindest/node/tags
-        KubeVersion: [ 1.30.10, 1.31.6, 1.32.2]
+        KubeVersion: [ 1.32.8, 1.33.4, 1.34.0]
 
     steps:
       - name: Checkout
diff --git a/TESTING.md b/TESTING.md
@@ -34,9 +34,6 @@ To run locally:
 
 *ct* can also test a chart by deploying it to a temporary namespace in a Kubernetes cluster, and waiting for indications that the deployment has been successful. This is a good way to test how the deployment behaves "for real".
 
-
-
-
 ct lint --config=.ci/ct-config.yaml
 
 Create a KinD cluster, by running `kind create cluster`:
diff --git a/charts/docker-mailserver/Chart.yaml b/charts/docker-mailserver/Chart.yaml
@@ -1,8 +1,8 @@
 apiVersion: v2
-appVersion: "15.0.2"
+appVersion: "15.1.0"
 description: A fullstack but simple mailserver (smtp, imap, antispam, antivirus, ssl...) using Docker.
 name: docker-mailserver
-version: 4.2.1
+version: 5.1.0
 sources:
 - https://github.com/docker-mailserver/docker-mailserver-helm
 maintainers:
diff --git a/charts/docker-mailserver/README.md b/charts/docker-mailserver/README.md
@@ -37,17 +37,68 @@ Kubernetes cluster. docker-mailserver is a production-ready, fullstack mail serv
 - A [Kubernetes](https://kubernetes.io/releases/) cluster with persistent storage and access to email [ports](https://docker-mailserver.github.io/docker-mailserver/latest/config/security/understanding-the-ports/#overview-of-email-ports)
 - A custom domain name (for example, example.com)
 - Correctly configured [DNS](https://docker-mailserver.github.io/docker-mailserver/latest/usage/#minimal-dns-setup)
+- [Cert Manager](https://cert-manager.io/docs/) or a similar tool to create and renew TLS certificates
 
 ## Getting Started
 
 Setting up docker-mailserver requires generating a number of configuration [files](https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/optional-config/). To make this easier, docker-mailserver includes a `setup` command that can generate these files.
 
-To get started, first add the helm repo and install docker-mailserver:
+To get started, first configure the firewall on your cluster to allow connections to ports 25 (imap), 465 (submissions), 587 (submission) and 993 (imaps) from any IP address.
 
+If you have a LoadBalancer service routing traffic to your ingress controller, configure it to pass through the mail ports. 
+
+Then, configure your ingress controller (or Gateway) to [pass through the email ports](https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/kubernetes/#using-the-proxy-protocol).
+
+Next, manually create a TLS Certificate, setting `metadata.name` and `spec.secretName` to the same value.  Also set the fully-qualified domain name for your mail server in `spec.dnsNames` and `spec.issuerRef.name` to the name of an Issuer or ClusterIssuer, and `spec.issuerRef.kind` to `Issuer` or `ClusterIssuer`.
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+
+metadata:
+  name: mail-tls-certificate-rsa
+
+spec:
+  secretName: mail-tls-certificate-rsa
+  isCA: false
+  privateKey:
+    algorithm: RSA
+    encoding: PKCS1
+    size: 2048
+  dnsNames: [mail.example.com]
+  issuerRef:
+    name: letsencrypt-production
+    kind: Issuer
+```
+```console
+kubectl apply -f certificate.yaml --namespace mail
+```
+
+Then add the helm repo:
 ```console
 helm repo add docker-mailserver https://docker-mailserver.github.io/docker-mailserver-helm
+```
+
+Create a Helm values file. See the comments in [values.yaml](https://github.com/docker-mailserver/docker-mailserver-helm/blob/master/charts/docker-mailserver/values.yaml) to understand all the options, or create a minimal file like this (where `mail-tls-certificate-rsa` is the name of the certificate you previously created and `example.com` is the name of your domain):
+```yaml
+## Specify the name of a TLS secret that contains a certificate and private key for your email domain.
+## See https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets
+certificate: mail-tls-certificate-rsa
 
-helm upgrade --install docker-mailserver docker-mailserver/docker-mailserver --namespace mail --create-namespace
+deployment:
+  env:
+    OVERRIDE_HOSTNAME: example.com       # You must OVERRIDE this!
+```
+If you're using the HAProxy ingress controller, configure it to send PROXY Protocol to the docker-mailserver ports, by appending this to your values file:
+```yaml
+service:
+  annotations:
+    haproxy.org/send-proxy-protocol: proxy-v2
+```
+
+Then install docker-mailserver using the values file:
+
+```console
+helm upgrade --install docker-mailserver docker-mailserver/docker-mailserver --namespace mail --create-namespace -f values.yaml
 ```
 
 Next open a command prompt to the running container.
@@ -78,6 +129,8 @@ cat /tmp/docker-mailserver/postfix-accounts.cf
 
 This path is [mapped](#persistence) to a Kubernetes Volume.
 
+Optionally (but reccomended), create a [`NetworkPolicy`](https://kubernetes.io/docs/concepts/services-networking/network-policies/) that only allows appropriate pods to connect to the DMS pod.
+
 ## Configuration
 
 Assuming you still have a command prompt [open](#getting-started) in the running container, run the setup command to see additional configuration options:
@@ -148,38 +201,50 @@ Once you acquire a certificate, you will need to store it in a TLS secret in the
 certificate: my-certificate-secret
 ```
 
-The chart will then automatically copy the certificate and private key to the `/tmp/dms/custom-certs` director in the container and correctly set the `SSL_CERT_PATH` and `SSL_KEY_PATH` environment variables.
+The chart will then automatically copy the certificate and private key to the `/tmp/dms/custom-certs` directory in the container and correctly set the `SSL_CERT_PATH` and `SSL_KEY_PATH` environment variables.
 
 ## Ports
 
-If you are running on a bare-metal Kubernetes cluster, you will have to expose ports to the internet to receive and send emails. In addition, you need to make sure that `docker-mailserver`` receives the correct client IP address so that spam filtering works.
+If you are running on a bare-metal Kubernetes cluster, you will have to expose ports to the internet to receive and send emails. In addition, you need to make sure that `docker-mailserver` receives the correct client IP address so that spam filtering works.
 
-This can get a bit complicated, as explained in the `docker-mailserver` [documentation](https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/kubernetes/#exposing-your-mail-server-to-the-outside-world).
+This can get a bit complicated, as explained in the `docker-mailserver` [documentation][dms-docs::k8s::network-config].
 
-One approach to preserving the client IP address is to use the PROXY protocol, which is explained in the [documentation](https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/kubernetes/#proxy-port-to-service-via-proxy-protocol).
+One approach to preserving the client IP address is to [use the PROXY protocol][dms-docs::k8s::proxy-protocol].
 
-The Helm chart supports the use of the proxy protocol via the `proxyProtocol` key. To enable it set the `proxyProtocol.enable` key to true. You will also want to set the `trustedNetworks` key.
+The Helm chart supports the use of the proxy protocol via the `proxyProtocol` key. By default `proxyProtocol.enable` is true, and `trustedNetworks` is set to the private IP network ranges, as are typically used inside a cluster.
 
 ```yaml
 proxyProtocol:
   enabled: true
   # List of sources (in CIDR format, space-separated) to permit PROXY protocol from
-  trustedNetworks: "10.0.0.0/8 192.168.0.0/16 172.16.0.0/16"
+  trustedNetworks: "10.0.0.0/8 192.168.0.0/16 172.16.0.0/12"
 ```
 
+Additionally, you will need to enable `proxyProtocol` for your loadbalancer.
+- If you are using a cloud service they will most likely have documentation on how to do this for their loadbalancer.
+- If you are using k3s then this is [currently impossible][k3s-klipperlb-pp] with the default components.
+
+For security, you should narrow `trustedNetworks` to the actual range of IP addresses used by your ingress controller pods, and be certain to exclude any IP ranges gatewayed from IPv6 to v4 or vice versa.
+Also note that any compromised container in the cluster could use the PROXY protocol to evade some security measures, so set a `NetworkPolicy` that only allows the appropriate pods to connect to the DMS pod.
+
 Enabling the PROXY protocol will create an additional port for each protocol (by adding 10,000 to the standard port value) that is configured to understand the PROXY protocol. Thus:
 
-| Protocol    |  Port   |  PROXY Port |
-| ----------  | ------- | ----------- |
-| submissions |   465   |    10465    |
-| submission  |   587   |    10587    |
-| imap        |   143   |    10143    |
-| imaps       |   993   |    10993    |
-| pop3        |   110   |    10110    |
-| pop3s       |   995   |    10995    |
+| Protocol    | Regular Port | PROXY Protocol Port |
+| ----------  |--------------|---------------------|
+| smtp        | 25           | 12525               |
+| submissions | 465          | 10465               |
+| submission  | 587          | 10587               |
+| imap        | 143          | 10143               |
+| imaps       | 993          | 10993               |
+| pop3        | 110          | 10110               |
+| pop3s       | 995          | 10995               |
 
 If you do not enable the PROXY protocol and your mail server is not exposed using a load-balancer service with an external traffic policy in "Local" mode, then all incoming mail traffic will look like it comes from a local Kubernetes cluster IP.
 
+[dms-docs::k8s::network-config]: https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/kubernetes/#exposing-your-mail-server-to-the-outside-world
+[dms-docs::k8s::proxy-protocol]: https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/kubernetes/#proxy-port-to-service-via-proxy-protocol
+[k3s-klipperlb-pp]: https://github.com/docker-mailserver/docker-mailserver-helm/issues/176#issuecomment-3097915161
+
 ## Persistence
 
 Docker-mailserver assumes there are [four](https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/optional-config/#volumes) mounted volumes:
@@ -231,7 +296,7 @@ DMS utilizes neither group-only chown as nfsnobody/root, fsGroup applied to all
 Quirks from the generic section also apply to NFS-backed PersistentVolumes.
 
 ## Upgrading to Version 5
-Version 5.0 upgrades docker-mailserver to version 15. This version of the chart *does* include backwards incompatible changes
+Version 5.0 of the chart *does* include backwards incompatible changes.
 
 ### PersistentVolumeClaims
 
diff --git a/charts/docker-mailserver/templates/deployment.yaml b/charts/docker-mailserver/templates/deployment.yaml
@@ -128,6 +128,10 @@ spec:
 
           resources:
 {{ toYaml .Values.deployment.resources | indent 12 }}
+          {{- if and .Values.deployment.resizePolicy (semverCompare ">=1.33-0" .Capabilities.KubeVersion.Version) }}
+          resizePolicy:
+{{ toYaml .Values.deployment.resizePolicy | indent 12 }}
+          {{- end }}
           securityContext:
             {{- if eq .Values.deployment.env.ENABLE_FAIL2BAN 1.0 }}
             capabilities:
@@ -250,7 +254,7 @@ spec:
             - name: managesieve
               containerPort: 4190  
           {{- if .Values.proxyProtocol.enabled }}
-            - name: managesieve-proxy
+            - name: msieve-proxy
               containerPort: 14190
           {{- end }}   
         {{- end }}  
@@ -268,10 +272,14 @@ spec:
 
           ports:
             - containerPort: 9154
-              name: http
+              name: metrics
               protocol: TCP
           resources:
-{{ toYaml .Values.metrics.resources | indent 12 }}          
+{{ toYaml .Values.metrics.resources | indent 12 }}
+          {{- if and .Values.metrics.resizePolicy (semverCompare ">=1.33-0" .Capabilities.KubeVersion.Version) }}
+          resizePolicy:
+{{ toYaml .Values.metrics.resizePolicy | indent 12 }}
+          {{- end }}          
           securityContext:
 {{ toYaml .Values.deployment.containerSecurityContext | indent 12 }}
 
diff --git a/charts/docker-mailserver/templates/service.yaml b/charts/docker-mailserver/templates/service.yaml
@@ -129,25 +129,22 @@ spec:
       targetPort: managesieve
       port: 4190  
     {{- if .Values.proxyProtocol.enabled }}
-    - name: managesieve-proxy
-      targetPort: managesieve-proxy
+    - name: msieve-proxy
+      targetPort: msieve-proxy
       port: 14190
     {{- end }}   
   {{- end }}   
  
   {{- if .Values.metrics.enabled }}
     - name: metrics
-      port: 9154
-      targetPort: 9154       
+      port: {{ .Values.monitoring.service.port }}
+      targetPort: metrics       
   {{- end }}
 
   type: {{ default "ClusterIP" .Values.service.type }}
-  {{- if eq .Values.service.type "LoadBalancer" }}
-    {{- if .Values.service.loadBalancer.publicIp }}
-  loadBalancerIP: {{ .Values.service.loadBalancer.publicIp }}
-      {{- if .Values.service.loadBalancer.allowedIps }}
-  loadBalancerSourceRanges:
-  {{ .Values.service.loadBalancer.allowedIps | toYaml | indent 4 }}
-      {{- end }}
-    {{- end }}
+  {{- if .Values.service.clusterIp }}
+  clusterIP: {{ .Values.service.clusterIp }}
+  {{- end }}
+  {{- if .Values.service.trafficDistribution }}
+  trafficDistribution: {{ .Values.service.trafficDistribution }}
   {{- end }}
diff --git a/charts/docker-mailserver/tests/__snapshot__/configmap_test.yaml.snap b/charts/docker-mailserver/tests/__snapshot__/configmap_test.yaml.snap
@@ -2,7 +2,7 @@ manifest should match snapshot:
   1: |
     apiVersion: v1
     data:
-      dovecot.cf: |2
+      dovecot.cf: |
         haproxy_trusted_networks = 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12
         service imap-login {
             inet_listener imap {
@@ -14,13 +14,13 @@ manifest should match snapshot:
                 ssl = yes
             }
 
-            inet_listener imap_proxy {
+            inet_listener imap_proxyprotocol {
                 haproxy = yes
                 port = 10143
                 ssl = no
             }
 
-            inet_listener imaps_proxy {
+            inet_listener imaps_proxyprotocol {
                 haproxy = yes
                 port = 10993
                 ssl = yes
@@ -51,47 +51,27 @@ manifest should match snapshot:
     data:
       user-patches.sh: |
         #!/bin/bash
-        # Make sure to keep this file in sync with https://github.com/docker-mailserver/docker-mailserver/blob/master/target/postfix/master.cf!
-        cat <<EOS >> /etc/postfix/master.cf
+        # NOTE: Keep in sync with upstream advice:
+        # https://github.com/docker-mailserver/docker-mailserver/blob/v15.0.0/docs/content/examples/tutorials/mailserver-behind-proxy.md?plain=1#L238-L268
 
-        # Submission with proxy
-        10587     inet  n       -       n       -       -       smtpd
-          -o syslog_name=postfix/submission
-          -o smtpd_tls_security_level=encrypt
-          -o smtpd_sasl_auth_enable=yes
-          -o smtpd_sasl_type=dovecot
-          -o smtpd_reject_unlisted_recipient=no
-          -o smtpd_sasl_authenticated_header=yes
-          -o smtpd_client_restrictions=permit_sasl_authenticated,reject
-          -o smtpd_relay_restrictions=permit_sasl_authenticated,reject
-          -o smtpd_sender_restrictions=\$mua_sender_restrictions
-          -o smtpd_discard_ehlo_keywords=
-          -o milter_macro_daemon_name=ORIGINATING
-          -o cleanup_service_name=sender-cleanup
-          -o smtpd_upstream_proxy_protocol=haproxy
+        # Duplicate the config for the submission(s) service ports (587 / 465) with adjustments for the PROXY ports (10587 / 10465) and `syslog_name` setting:
+        postconf -Mf submission/inet | sed -e s/^submission/10587/ -e 's/submission/submission-proxyprotocol/' >> /etc/postfix/master.cf
+        postconf -Mf submissions/inet | sed -e s/^submissions/10465/ -e 's/submissions/submissions-proxyprotocol/' >> /etc/postfix/master.cf
+        # Enable PROXY Protocol support for these new service variants:
+        postconf -P 10587/inet/smtpd_upstream_proxy_protocol=haproxy
+        postconf -P 10465/inet/smtpd_upstream_proxy_protocol=haproxy
 
-        # Submissions with proxy
-        10465     inet  n       -       n       -       -       smtpd
-          -o syslog_name=postfix/submissions
-          -o smtpd_tls_wrappermode=yes
-          -o smtpd_sasl_auth_enable=yes
-          -o smtpd_sasl_type=dovecot
-          -o smtpd_reject_unlisted_recipient=no
-          -o smtpd_sasl_authenticated_header=yes
-          -o smtpd_client_restrictions=permit_sasl_authenticated,reject
-          -o smtpd_relay_restrictions=permit_sasl_authenticated,reject
-          -o smtpd_sender_restrictions=\$mua_sender_restrictions
-          -o smtpd_discard_ehlo_keywords=
-          -o milter_macro_daemon_name=ORIGINATING
-          -o cleanup_service_name=sender-cleanup
-          -o smtpd_upstream_proxy_protocol=haproxy
+        # Create a variant for port 25 too (NOTE: Port 10025 is already assigned in DMS to Amavis):
+        postconf -Mf smtp/inet | sed -e s/^smtp/12525/ >> /etc/postfix/master.cf
+        # Enable PROXY Protocol support:
+        # - Uses a different setting as port 25 is handled via the postscreen service
+        # - Optionally configure a `syslog_name` to distinguish in logs:
+        postconf -P \
+          12525/inet/postscreen_upstream_proxy_protocol=haproxy \
+          12525/inet/syslog_name=postfix/smtpd-proxyprotocol
 
-        # Smtp with proxy
-        12525     inet  n       -       n       -       1       postscreen
-          -o syslog_name=postfix/smtp-proxy
-          -o postscreen_upstream_proxy_protocol=haproxy
-          -o postscreen_cache_map=btree:$data_directory/postscreen_10025_cache
-        EOS
+        # Add the `proxy:` prefix to share this cache between each running postscreen service via `proxymap`:
+        postconf 'postscreen_cache_map = proxy:btree:$data_directory/postscreen_cache'
     kind: ConfigMap
     metadata:
       labels:
diff --git a/charts/docker-mailserver/values.yaml b/charts/docker-mailserver/values.yaml
