mattermostrecipe.md

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

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 to 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 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

Then 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]

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

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

The Mattermost installation manifest contains fields which 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

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 secret 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 Mattermost Operator to use the external database, modify 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, first 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 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 successfuly, 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 http://localhost:8065.

Thus far this looks good - I assume there is further content to complete the recipe?

Hey @aspleenic, yes there is def more content to finish this out. Currently just trying to figure out the best way to describe accessing the UI.