mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2024-01-19 02:48:50 +00:00
Add in-Kubernetes usage docs
This commit is contained in:
tyranron
parent
504494e4dd
commit
6162cac0fa
377
docs/content/advanced/kubernetes.md
Normal file
377
docs/content/advanced/kubernetes.md
Normal file
|
|
@ -0,0 +1,377 @@
|
|||
## Deployment example
|
||||
|
||||
There is nothing much in deploying mailserver to Kubernetes itself. The things are pretty same as in [`docker-compose.yml`][1], but with Kubernetes syntax.
|
||||
|
||||
```yaml
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mailserver
|
||||
labels:
|
||||
app: mailserver
|
||||
spec:
|
||||
selector:
|
||||
app: mailserver
|
||||
ports:
|
||||
- name: smtp
|
||||
port: 25
|
||||
targetPort: smtp
|
||||
- name: smtp-auth
|
||||
port: 587
|
||||
targetPort: smtp-auth
|
||||
- name: imap-secure
|
||||
port: 993
|
||||
targetPort: imap-secure
|
||||
|
||||
---
|
||||
|
||||
kind: ConfigMap
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mailserver.config
|
||||
labels:
|
||||
app: mailserver
|
||||
data:
|
||||
postfix-accounts.cf: |
|
||||
user1@example.com|{SHA512-CRYPT}$6$2YpW1nYtPBs2yLYS$z.5PGH1OEzsHHNhl3gJrc3D.YMZkvKw/vp.r5WIiwya6z7P/CQ9GDEJDr2G2V0cAfjDFeAQPUoopsuWPXLk3u1
|
||||
|
||||
postfix-virtual.cf: |
|
||||
alias1@example.com user1@dexample.com
|
||||
|
||||
SigningTable: |
|
||||
*@example.com mail._domainkey.example.com
|
||||
|
||||
KeyTable: |
|
||||
mail._domainkey.example.com example.com:mail:/etc/opendkim/keys/example.com-mail.key
|
||||
|
||||
TrustedHosts: |
|
||||
127.0.0.1
|
||||
localhost
|
||||
|
||||
---
|
||||
|
||||
kind: Secret
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mailserver.opendkim.keys
|
||||
labels:
|
||||
app: mailserver
|
||||
type: Opaque
|
||||
data:
|
||||
example.com-mail.key: 'base64-encoded-DKIM-key'
|
||||
|
||||
---
|
||||
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
name: mailserver
|
||||
labels:
|
||||
app: mailserver
|
||||
spec:
|
||||
strategy:
|
||||
type: Recreate
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: mailserver
|
||||
spec:
|
||||
nodeSelector:
|
||||
has/mail-server: 'true'
|
||||
subdomain: mailserver
|
||||
containers:
|
||||
- name: mailserver
|
||||
image: tvial/docker-mailserver:2.1
|
||||
ports:
|
||||
- name: smtp
|
||||
containerPort: 25
|
||||
- name: smtp-auth
|
||||
containerPort: 587
|
||||
- name: imap-secure
|
||||
containerPort: 993
|
||||
env:
|
||||
- name: ONE_DIR
|
||||
value: '1'
|
||||
volumeMounts:
|
||||
- name: config
|
||||
subPath: postfix-accounts.cf
|
||||
mountPath: /tmp/docker-mailserver/postfix-accounts.cf
|
||||
readOnly: true
|
||||
- name: config
|
||||
subPath: postfix-virtual.cf
|
||||
mountPath: /tmp/docker-mailserver/postfix-virtual.cf
|
||||
readOnly: true
|
||||
- name: config
|
||||
subPath: SigningTable
|
||||
mountPath: /tmp/docker-mailserver/opendkim/SigningTable
|
||||
readOnly: true
|
||||
- name: config
|
||||
subPath: KeyTable
|
||||
mountPath: /tmp/docker-mailserver/opendkim/KeyTable
|
||||
readOnly: true
|
||||
- name: config
|
||||
subPath: TrustedHosts
|
||||
mountPath: /tmp/docker-mailserver/opendkim/TrustedHosts
|
||||
readOnly: true
|
||||
- name: opendkim-keys
|
||||
mountPath: /tmp/docker-mailserver/opendkim/keys
|
||||
readOnly: true
|
||||
- name: data
|
||||
mountPath: /var/mail
|
||||
- name: state
|
||||
mountPath: /var/mail-state
|
||||
volumes:
|
||||
- name: config
|
||||
configMap:
|
||||
name: mailserver.config
|
||||
- name: opendkim-keys
|
||||
secret:
|
||||
secretName: mailserver.opendkim.keys
|
||||
- name: data
|
||||
hostPath:
|
||||
path: /path/to/mailserver/data
|
||||
- name: state
|
||||
hostPath:
|
||||
path: /path/to/mailserver/state
|
||||
```
|
||||
|
||||
__Note:__
|
||||
Any sensitive data (keys, etc) should be deployed via [Secrets][50]. Other configuration just fits well into [ConfigMaps][51].
|
||||
|
||||
__Note:__
|
||||
Make sure that [Pod][52] is [assigned][59] to specific [Node][53] in case you're using volume for data directly with `hostPath`. Otherwise Pod can be rescheduled on a different Node and previous data won't be found. Except the case when you're using some shared filesystem on your Nodes.
|
||||
|
||||
|
||||
|
||||
|
||||
## Exposing to outside world
|
||||
|
||||
The hard part with Kubernetes is to expose deployed mailserver to outside world. Kubernetes provides multiple ways for doing that. Each has its downsides and complexity.
|
||||
|
||||
The major problem with exposing mailserver to outside world in Kubernetes is to [preserve real client IP][57]. Real client IP is required by mailserver for performing IP-based SPF checks and spam checks.
|
||||
|
||||
Preserving real client IP is relatively [non-trivial in Kubernetes][57] and most exposing ways do not provide it. So, it's up to you to decide which exposing way suits better your needs in a price of complexity.
|
||||
|
||||
If you do not require SPF checks for incoming mails you may disable them in [Postfix configuration][2] by dropping following line (which removes `check_policy_service unix:private/policyd-spf` option):
|
||||
```yaml
|
||||
kind: ConfigMap
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mailserver.config
|
||||
labels:
|
||||
app: mailserver
|
||||
data:
|
||||
postfix-main.cf: |
|
||||
smtpd_recipient_restrictions = permit_sasl_authenticated, permit_mynetworks, reject_unauth_destination, reject_unauth_pipelining, reject_invalid_helo_hostname, reject_non_fqdn_helo_hostname, reject_unknown_recipient_domain, reject_rbl_client zen.spamhaus.org, reject_rbl_client bl.spamcop.net
|
||||
# ...
|
||||
|
||||
---
|
||||
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
name: mailserver
|
||||
# ...
|
||||
volumeMounts:
|
||||
- name: config
|
||||
subPath: postfix-main.cf
|
||||
mountPath: /tmp/docker-mailserver/postfix-main.cf
|
||||
readOnly: true
|
||||
# ...
|
||||
```
|
||||
|
||||
|
||||
### External IPs Service
|
||||
|
||||
The simplest way is to expose mailserver as a [Service][55] with [external IPs][56].
|
||||
|
||||
```yaml
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mailserver
|
||||
labels:
|
||||
app: mailserver
|
||||
spec:
|
||||
selector:
|
||||
app: mailserver
|
||||
ports:
|
||||
- name: smtp
|
||||
port: 25
|
||||
targetPort: smtp
|
||||
# ...
|
||||
externalIPs:
|
||||
- 80.11.12.10
|
||||
```
|
||||
|
||||
##### Downsides
|
||||
|
||||
- __Real client IP is not preserved__, so SPF check of incoming mail will fail.
|
||||
|
||||
- Requirement to specify exposed IPs explicitly.
|
||||
|
||||
|
||||
### Proxy port to Service
|
||||
|
||||
The [Proxy Pod][58] helps to avoid necessity of specifying external IPs explicitly. This comes in price of complexity: you must deploy Proxy Pod on each [Node][53] you want to expose mailserver on.
|
||||
|
||||
##### Downsides
|
||||
|
||||
- __Real client IP is not preserved__, so SPF check of incoming mail will fail.
|
||||
|
||||
|
||||
### Bind to concrete Node and use host network
|
||||
|
||||
The simplest way to preserve real client IP is to use `hostPort` and `hostNetwork: true` in the mailserver [Pod][52]. This comes in price of availability: you can talk to mailserver from outside world only via IPs of [Node][53] where mailserver is deployed.
|
||||
|
||||
```yaml
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
name: mailserver
|
||||
# ...
|
||||
spec:
|
||||
hostNetwork: true
|
||||
# ...
|
||||
containers:
|
||||
# ...
|
||||
ports:
|
||||
- name: smtp
|
||||
containerPort: 25
|
||||
hostPort: 25
|
||||
- name: smtp-auth
|
||||
containerPort: 587
|
||||
hostPort: 587
|
||||
- name: imap-secure
|
||||
containerPort: 993
|
||||
hostPort: 993
|
||||
# ...
|
||||
```
|
||||
|
||||
##### Downsides
|
||||
|
||||
- Not possible to access mailserver via other cluster Nodes, only via the one mailserver deployed at.
|
||||
|
||||
|
||||
### Proxy port to Service via PROXY protocol
|
||||
|
||||
This way is ideologically the same as [using Proxy Pod](#proxy-port-to-service) but instead Proxy Pod you should use [HAProxy image][11] or [Nginx Ingress Controller][12] and proxy TCP traffic to mailserver Pod with PROXY protocol usage which does real client IP preservation.
|
||||
|
||||
This requires some additional mailserver configuration: you should enable PROXY protocol on ports that [Postfix][2] and [Dovecot][3] listen on for incoming connections.
|
||||
```yaml
|
||||
kind: ConfigMap
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: mailserver.config
|
||||
labels:
|
||||
app: mailserver
|
||||
data:
|
||||
postfix-main.cf: |
|
||||
smtpd_upstream_proxy_protocol = haproxy
|
||||
dovecot.cf: |
|
||||
service imap-login {
|
||||
inet_listener imaps {
|
||||
haproxy = yes
|
||||
}
|
||||
}
|
||||
# ...
|
||||
|
||||
---
|
||||
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
name: mailserver
|
||||
#...
|
||||
volumeMounts:
|
||||
- name: config
|
||||
subPath: postfix-main.cf
|
||||
mountPath: /tmp/docker-mailserver/postfix-main.cf
|
||||
readOnly: true
|
||||
- name: config
|
||||
subPath: dovecot.cf
|
||||
mountPath: /etc/dovecot/conf.d/zz-custom.cf
|
||||
readOnly: true
|
||||
# ...
|
||||
```
|
||||
|
||||
##### Downsides
|
||||
|
||||
- Not possible to access mailserver via inner cluster Kubernetes DNS, as PROXY protocol is required for incoming connections.
|
||||
|
||||
|
||||
|
||||
|
||||
## Let's Encrypt certificates
|
||||
|
||||
[Kube-Lego][10] may be used for a role of Let's Encrypt client. It works with Kubernetes [Ingress Resources][54] and automatically issues/manages certificates/keys for exposed services via Ingresses.
|
||||
|
||||
```yaml
|
||||
kind: Ingress
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
name: mailserver
|
||||
labels:
|
||||
app: mailserver
|
||||
annotations:
|
||||
kubernetes.io/tls-acme: 'true'
|
||||
spec:
|
||||
rules:
|
||||
- host: example.com
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
backend:
|
||||
serviceName: default-backend
|
||||
servicePort: 80
|
||||
tls:
|
||||
- secretName: mailserver.tls
|
||||
hosts:
|
||||
- example.com
|
||||
```
|
||||
|
||||
Now, you can use Let's Encrypt cert and key from `mailserver.tls` [Secret][50]
|
||||
in your [Pod][52] spec.
|
||||
|
||||
```yaml
|
||||
# ...
|
||||
env:
|
||||
- name: SSL_TYPE
|
||||
value: 'manual'
|
||||
- name: SSL_CERT_PATH
|
||||
value: '/etc/ssl/mailserver/tls.crt'
|
||||
- name: SSL_KEY_PATH
|
||||
value: '/etc/ssl/mailserver/tls.key'
|
||||
# ...
|
||||
volumeMounts:
|
||||
- name: tls
|
||||
mountPath: /etc/ssl/mailserver
|
||||
readOnly: true
|
||||
# ...
|
||||
volumes:
|
||||
- name: tls
|
||||
secret:
|
||||
secretName: mailserver.tls
|
||||
# ...
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[1]: https://github.com/tomav/docker-mailserver/blob/master/docker-compose.yml.dist
|
||||
[2]: https://github.com/tomav/docker-mailserver/wiki/Overwrite-Default-Postfix-Configuration
|
||||
[3]: https://github.com/tomav/docker-mailserver/wiki/Override-Default-Dovecot-Configuration
|
||||
[10]: https://github.com/jetstack/kube-lego
|
||||
[11]: https://hub.docker.com/_/haproxy
|
||||
[12]: https://github.com/kubernetes/ingress/tree/master/controllers/nginx#exposing-tcp-services
|
||||
[50]: https://kubernetes.io/docs/concepts/configuration/secret
|
||||
[51]: https://kubernetes.io/docs/tasks/configure-pod-container/configmap
|
||||
[52]: https://kubernetes.io/docs/concepts/workloads/pods/pod
|
||||
[53]: https://kubernetes.io/docs/concepts/architecture/nodes
|
||||
[54]: https://kubernetes.io/docs/concepts/services-networking/ingress
|
||||
[55]: https://kubernetes.io/docs/concepts/services-networking/service
|
||||
[56]: https://kubernetes.io/docs/concepts/services-networking/service/#external-ips
|
||||
[57]: https://kubernetes.io/docs/tutorials/services/source-ip
|
||||
[58]: https://github.com/kubernetes/contrib/tree/master/for-demos/proxy-to-service
|
||||
[59]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node
|
||||
Loading…
Reference in a new issue