Install Mattermost on Kubernetes 

plans-img Available on all plans

deployment-img self-hosted deployments

You can install and deploy a production-ready Mattermost system on a Kubernetes cluster using the Mattermost Kubernetes Operator in practically any environment with less IT overhead and more automation.

You’ll need a Kubernetes cluster running version 1.16 or higher, Kubernetes CLI kubectl installed on local machine, and a basic understanding of Kubernetes concepts (such as deployments, pods) and actions (such as applying manifests, viewing pod logs). Running Mattermost in Kubernetes requires resources based on your total number of users. See the Mattermost Kubernetes Operator documentation to learn more about the minimum Kubernetes cluster resources Mattermost requires at different scales.

Tip

If you’re unsure about which environment you want to use for your Kubernetes cluster, we suggest using a managed service such as as Amazon EKS, Azure Kubernetes Service, Google Kubernetes Engine, or DigitalOcean Kubernetes.

Install the operators

Operators are installed using 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.

  1. Install NGINX ingress controller by following the instructions here.

  2. Install the Mattermost Operator:

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

Tip

To install the operators using the Mattermost Operator Helm chart, follow the instructions here.

Deploy Mattermost

  1. (Mattermost Enterprise only) Create a Mattermost license secret by opening a text editor and creating a secret manifest containing the Mattermost license. Replace [LICENSE_FILE_CONTENTS] below with the contents of your Mattermost license file. Save the file as mattermost-license-secret.yaml.

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

  1. Create an installation manifest file locally in a text editor by copying and pasting contenst from the Mattermost installation manifest, and adjusting fields for your configuration and environment.

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

Save the file as mattermost-installation.yaml. While recommended file names are provided, your naming conventions may differ.

Some of the most commonly-used fields include:

Field

Description

Must Edit

metadata.name

The name of your Mattermost as it will be shown in Kubernetes. The shorter the better.

Yes

spec.size

The size of your installation. This can be ‘100users’, ‘1000users, ‘5000users’, ‘10000users’, or ‘25000users’.

Yes

spec.ingress.host

The DNS for your Mattermost installation.

Yes

spec.version

The Mattermost version.

No

spec.licenseSecret

The name of the Kubernetes secret containing your license (e.g. mattermost-license). Required for Enterprise deployments.

No

spec.mattermostEnv

List of custom environment variables for the Mattermost instance.

No

Additional fields are documented in the example.

If you have previous experience with Kubernetes Custom Resources

you can also check the Custom Resource Definition.

  1. Create external database secret. (Skip if using MySQL and MinIO operators).

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

Note

  • For PostgreSQL databases, the connection is checked with pg_isready so the DB_CONNECTION_CHECK_URL is the same as connection string.

  • For MySQL databases, the check is performed via HTTP call; therefore DB_CONNECTION_CHECK_URL should be an HTTP URL.

  1. Create external filestore secret (Skip if using MySQL and MinIO operators).

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

  1. Adjust installation manifest (Skip if using MySQL and MinIO operators).

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

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

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

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

Additionally when using Amazon S3, set the MM_FILESETTINGS_AMAZONS3SSE and MM_FILESETTINGS_AMAZONS3SSL environment variables to true:

spec:
...
  mattermostEnv:
    ...
    - name: MM_FILESETTINGS_AMAZONS3SSE
      value: "true"
    - name: MM_FILESETTINGS_AMAZONS3SSL
      value: "true"

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
  ingress:
    enabled: true
    host: example.mattermost-example.com
    annotations:
      kubernetes.io/ingress.class: nginx
  version: 6.0.1
  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"

  1. Apply the installation manifest file. Manifests are applied with kubectl. Before running the commands make sure you are connected to your Kubernetes cluster.

  1. Create the Mattermost namespace:

$ kubectl create ns mattermost

  1. (Mattermost Enterprise only) 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]

  1. Apply the installation file by specifying the path to the 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.

  1. Configure DNS and use 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 ingress.host 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 ingress.host 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

Then navigate to http://localhost:8065.