Deploying an Axigen Cluster on Kubernetes Platforms with AxiHelm

The following guide will show you how to deploy an Axigen Mail Server cluster by using AxiHelm. We will go through:

1. Gathering the prerequisites

2. Performing the installation 

3. Upgrading the deployment

4. Uninstalling the deployment

5. Configuring all the elements

About AxiHelm

AxiHelm is a Helm Chart responsible with deploying a clustered Axigen Mail server on Kubernetes platforms.

1. Prerequisites

a. CLI Tools

The following command-line tools are needed in order to install and configure AxiHelm:

• helm

• kubectl

Make sure the kubectl command uses the desired Kubernetes cluster and namespace:

b. License

A valid Axigen license file is required to be stored in a ConfigMap, which by default should be named axigen-license. Therefore, once you have your axigen_lk.bin license, create the needed ConfigMap:

c. Private Image Registry Credentials

If using Axigen Docker images from private repository, a Secret with valid Docker credentials must be created. To create a Secret named axigen-repo which contains privileges to pull images from the docker.example.io Docker registry, run:

d. Cluster Manager Service Account

The Axigen Cluster Manager (shortened axiclumgr) requires a custom ServiceAccount with specific Kubernetes permissions. All the resources required for this must be created with the following command:

e. DNS

If outside access is desired, make sure to correctly configure the cluster to allow external access and set up the needed DNS records for the domain.

2. Installation

Firstly, add the Axigen Helm Chart Repository:

Then, update the chart repositories in order to download the latest release:

Although configuration values passed to the helm binary can be specified as command-line arguments, since these can get quite complex, we recommend to store configuration options as a YAML file and then pass it to helm.

The following custom.yaml values file can be used for a minimal AxiHelm deployment:

The image.imageRegistry instructs the helm chart where to get the images from (Axigen’s Docker Hub), while the server.clusterKey string is a mandatory secret value used for cluster
synchronization. Using a private registry is possible (set image.imageRegistry to a fully qualified hostname of you private registry) - but all the docker images used by the chart must be pushed there before the deployment. If using an authenticated private registry, you must create a secret for it (see the above section Private Image Registry Credentials) and include it in the imagePullSecrets array in custom.yaml.

Finally, to deploy AxiHelm, setting up a domain named mail.domain.tld, run the helm install command with the desired domain name, along with the path of the custom values file and the Axigen Helm chart available at axigen/axigen:

Check that the deployed pods are up and running with:

3. Upgrades

To upgrade an existing AxiHelm deployment, add or remove the desired values in the custom.yaml file, and run:

4. Uninstall

To uninstall an AxiHelm deployment, run helm uninstall with the release name:

5. Configuration

a. Kubernetes StorageClass

By default, the pods will use the StorageClass marked as default for persistent storage. If the cluster does not have a default StorageClass, or if another one is desired, specify its name in the values file:

b. Enabling Unsecure Services

By default, only SSL services are enabled. If you wish to also enable unsecure services (WebMail - port 80, Submission - port 587, IMAP - port 143, POP3 - port 110), set server.enableNonSSLsvc to true in the values file.

c. SSL Certificates

An SSL certificate, which will be used for all SSL services, can be configured by first creating a Secret containing the certificate (named ssl-cert.pem):

Then specify the secret name (in this case ssl-cert) in the server.sslCertSecret key in the values file.

An SSL certificate to be used for administrative services (WebAdmin and CLI) can also be configured by creating a Secret from the desired certificate (names ssl-admin.pem):

Then specify the secret name (in this case ssl-admin) in the server.adminSSLCertSecret key in the values file.

d. Configure Smart Host Routing

The default setup is to use DNS MX record when messages needs to be delivered to external recipients.

In case the delivery needs to be done via a SMTP Smart Host, then this could be configured via the following values:

e. Configure Message Signing

Message signing is done via smtpFilters.script on each BE node and has 2 components:

• private key: a file that has to be deployed in /var/opt/axigen/sign.privkey.pem

• public key: a DNS TXT record that corresponds to the signing selector

f. Disable Enforcement of From Header

By default, the email address included in the From header is enforced to be in sync with the values allowed by the account used when the session was authenticated (like main email address, account’s aliases etc). In case this impersonation protection need to be disabled, this could be done by setting domain.enforceMessageFrom to false:

g. The Report-Abuse Header

For all authenticated messages, a special header could be added (called X-Report-Abuse) so the final recipient could report unsolicited messages (usually via an email address or by accesing a web URL). The way to configure this header is by setting domain.reportAbuse:

h. DKIM Message Signing

Generate the Certificate and Save Private and Public Keys

Generate the Needed ConfigMap:

Create the Generated ConfigMap

Update Application Values

• Set domain.signKeyConfigMap to the generated configmap (in this case sign-key-001)

• Set domain.signSelector to the DNS record where you have set the public key (for example mail-2020)

i. Kubernetes Services Type

By default, all application Services created by AxiHelm are of type ClusterIP. This is configured by the network.serviceType value, with supported options of LoadBalancer, NodePort, ExternalName or ClusterIP.

For example, to only use Services of type NodePort, set the following in the values file: