Mattermost Recipe: Leveraging the Kubernetes Operator to deploy our Community Server

June 8, 2021

Platform

Here’s the next installment in our Mattermost Recipes series.

The goal of these posts is to provide you with solutions to specific problems, as well as a discussion about the details of the solution and some tips about how to customize it to suit your needs perfectly.

If there’s a Recipe you want us to cook up in the future, drop us a line on our forum.

Problem

While leveraging the benefits of distributed computing platforms such as Kubernetes allows for greater fault tolerance and scalability, there is also a certain level of added complexity involved in implementing these solutions. With that being said, the path to entry is not nearly as complex as it was in the past thanks to new paradigms such as the Operator model.

In this post, we’re going to give you a recipe for deploying Mattermost into your environment with the Kubernetes Operator.

Solution

In this general solution, we are going to deploy a Mattermost Community server with the Kubernetes Operator and learn how to access the Admin console and configure certain settings.

Prerequisites

Prerequisites for using the Mattermost Operator:

Kubernetes cluster in version 1.16 or higher
Kubernetes CLI kubectl installed on a local machine

Installing the Operators

1. Installing the NGINX Ingress Controller

First, we’re going to need to install an ingress controller so we can access our cluster from the outside. Because this is so specific to each individual platform, we’re just going to give you a link to instructions on doing this yourself here.

2. Installing the Mattermost Operator

Now, we’re ready to install the Mattermost Operator. This process uses kubectl and each operator is created in its own namespace. You can install and run multiple Mattermost installations in the same cluster using different namespaces.

First, create the namespace:

$ kubectl create ns mattermost-operator

Next, deploy the operator:

$ kubectl apply -n mattermost-operator -f https://raw.githubusercontent.com/mattermost/mattermost-operator/master/docs/mattermost-operator/mattermost-operator.yaml

Deploying a Mattermost Installation

In this section, we’re going to cover how to deploy a complete Mattermost installation in Kubernetes.

Manifest files contain the configurations needed for the Operator to properly set up the Mattermost installation. Create the manifest files locally in a text editor, copy and paste the contents, and save the file.

Recommended file names are provided, but your naming conventions may differ. Manifests are applied with kubectl.

Before running the commands, make sure you are connected to your Kubernetes cluster.

1. (Enterprise only) Create a Mattermost license secret

Open a text editor and create a secret manifest containing the Mattermost license.

Make sure to replace [LICENSE_FILE_CONTENTS] with the contents of your Mattermost license file.

apiVersion: v1
kind: Secret
metadata:
  name: mattermost-license
type: Opaque
stringData:
  license: [LICENSE_FILE_CONTENTS]

2. Save the file as mattermost-license-secret.yaml

The Mattermost installation manifest contains fields that must be adjusted for your configuration and environment requirements. Commonly used fields are documented here.

Open a text editor and create a Mattermost installation manifest:

apiVersion: installation.mattermost.com/v1beta1
kind: Mattermost
metadata:
  name: mm-example-full                         # Chose the desired name
spec:
  size: 5000users                               # Adjust to your requirements
  ingressName: example.mattermost-example.com   # Adjust to your domain
  ingressAnnotations:
    kubernetes.io/ingress.class: nginx
  version: 5.31.0
  licenseSecret: ""                             # If you have created secret in step 1, put its name here

Save the file as mattermost-installation.yaml.

3. Create external database secret

The database secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data:

Key	Description	Required
DB_CONNECTION_STRING	Connection string to the database	Yes
MM_SQLSETTINGS_DATASOURCEREPLICAS	Connection string to read replicas of the database	No
DB_CONNECTION_CHECK_URL	The URL used for checking that the database is accessible	No

Here’s an example secret for AWS Aurora compatible with PostgreSQL:

apiVersion: v1
data:
  DB_CONNECTION_CHECK_URL: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK
  DB_CONNECTION_STRING: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK
  MM_SQLSETTINGS_DATASOURCEREPLICAS: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLXJvLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK
kind: Secret
metadata:
  name: my-postgres-connection
type: Opaque

4. Create external filestore secret

The filestore secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data:

Key	Description	Required
accesskey	Filestore access key.	Yes
secretkey	Filestore access key.	Yes

Example secret for AWS S3:

apiVersion: v1
data:
  accesskey: QUNDRVNTX0tFWQo=
  secretkey: U1VQRVJfU0VDUkVUX0tFWQo=
kind: Secret
metadata:
  name: my-s3-iam-access-key
type: Opaque

5. Adjust installation manifest

To instruct the Mattermost Operator to use the external database, modify the Mattermost manifest by adding the following fields:

spec:
...
 database:
   external:
     secret: my-postgres-connection

And for the external filestore:

spec:
...
  fileStore:
    external:
      url: s3.amazonaws.com
      bucket: my-s3-bucket
      secret: my-s3-iam-access-key

Here’s an example Mattermost manifest configured with both external databases and filestore:

apiVersion: installation.mattermost.com/v1beta1
kind: Mattermost
metadata:
  name: mm-example-external-db
spec:
  size: 5000users
  ingressName: example.mattermost-example.com
  ingressAnnotations:
    kubernetes.io/ingress.class: nginx
  version: 5.31.0
  licenseSecret: ""
  database:
    external:
      secret: my-postgres-connection
  fileStore:
    external:
      url: s3.amazonaws.com
      bucket: my-s3-bucket
      secret: my-s3-iam-access-key
  mattermostEnv:
  - name: MM_FILESETTINGS_AMAZONS3SSE
    value: "true"
  - name: MM_FILESETTINGS_AMAZONS3SSL
    value: "true"

6. Apply the installation manifest file

To apply the installation manifest, you’ll need to create the Mattermost namespace:

$ kubectl create ns mattermost

If you’re deploying Mattermost Enterprise Edition, apply the license file by specifying the path to the file you created in step 1:

$ kubectl apply -n mattermost -f [PATH_TO_LICENCE_SECRET_MANIFEST]

Finally, apply the installation file, specifying the path to file you created in step 2:

$ kubectl apply -n mattermost -f [PATH_TO_MATTERMOST_MANIFEST]

The deployment process can be monitored in the Kubernetes user interface or in command line by running:

$ kubectl -n mattermost get mm -w

The installation should be deployed successfully when the Custom Resource reaches the stable state.

Configuring DNS and accessing Mattermost

When the deployment is complete, obtain the hostname or IP address of your Mattermost deployment using the following command:

$ kubectl -n mattermost get ingress

Copy the resulting hostname or IP address from the ADDRESS column, open your browser, and connect to Mattermost.

Use your domain registration service to create a canonical name or IP address record for the ingressName in your manifest, pointing to the address you just copied. For example, on AWS you would do this within a hosted zone in Route53.

Navigate to the ingressName URL in your browser and use Mattermost.

If you just want to try it out on your local machine without configuring the domain, run:

$ kubectl -n mattermost port-forward svc/[YOUR_MATTERMOST_NAME] 8065:8065

And navigate to https://localhost:8065.

That’s it!

For more information or to get started with the Mattermost Operator, check out the code on GitHub.