Install Mattermost on Kubernetes 

On this page

Install Mattermost on Kubernetes

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 a version that is currently supported with patch releases, 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.
Looking for a quick way to evaluate Mattermost or to try out the latest Mattermost deployment? See this article for details on creating your own Mattermost instance on Kubernetes using Minicube: https://medium.com/@Erez.Tamam/create-your-own-mattermost-instance-on-kubernetes-in-10-minutes-d13f576ed794.

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.

Install NGINX ingress controller by following the instructions here.
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. See the Kubernetes YAML file documentation within the mattermost GitHub repository for details on working with the YAML file.

Deploy Mattermost 

(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: my-mattermost-license
type: Opaque
stringData:
  license: <LICENSE_FILE_CONTENTS>

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: <INSTALLATION_NAME_HERE>                # Chose the desired installation name. Example = mm-example-full
  spec:
    size: <SIZE_VALUE_HERE>                       # Adjust to your requirements. Example = 5000users
    ingress:
      enabled: true
      host: <FULL_DOMAIN_NAME_HERE>               # Adjust to your domain. Example = example.mattermost-example.com
      annotations:
        kubernetes.io/ingress.class: nginx
    version: <VERSION_HERE>                       # Select a recent supported version of Mattermost. Example = 9.3.0
    licenseSecret: ""                             # If you created a license secret in step 1, put the secret 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

metadata.name

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

spec.size

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

spec.ingress.host

The DNS for your Mattermost installation.

spec.version

The Mattermost version. Refer to the version archive page when selecting a mattermost version.

spec.licenseSecret

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

spec.mattermostEnv

List of custom environment variables for the Mattermost instance. Only required when tweaking Mattermost configuration is required.

Additional fields are documented in the example. If you have previous experience with Kubernetes Custom Resources, you can also check the Custom Resource Definition.

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
Note

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

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

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

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: 9.3.0
  licenseSecret: my-mattermost-license
  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"

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

Create a namespace for this new Mattermost installation:
kubectl create ns mattermost
(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]
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.

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.

Note

If you just want to try it out on your local machine without configuring the domain, run the following command, and then navigate to http://localhost:8065.

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

Frequently asked questions 

What’s the difference between the Mattermost Operator and Helm Charts?

The Mattermost Operator is a self-contained set of application/product-specific instructions that runs inside Kubernetes and facilitates application management and deployment.

Helm is a tool used to deploy Kubernetes manifests to a cluster, but does not facilitate application management.

Does the Mattermost Operator replace the Helm Chart?

No. Helm is a good mechanism to deploy operators and other applications but doesn’t facilitate application management.

Is minIO the only available storage option?

No, other options and operators can be added.

Do I have to install a separate SQL server to use the Mattermost Operator?

No, you can use the operator on top of your existing deployment without setting up another database. We will shortly be providing steps for this configuration.

Can you use blue-green deployments with different database schemas?

Currently this is not supported as it introduces the possibility of missing a data entry in the database.

Are environment variables supported?

Yes. However, config.json file settings will be overridden if the $MM_SQLSETTINGS_DATASOURCE environment variable is set. See the Environment Variables configuration settings documentation for details.

Issues configuring login with SAML on Kubernetes 

For some SAML authentication configurations, 502 status code response can appear during login attempts due to requests being too large. This can be caused by the default proxy-buffer-size setting for NGINX Ingress being too low. To fix this issue, configure an appropriate buffer size (8k or 16k should be sufficient for most cases) with NGINX annotation by adding it to the Mattermost manifest under spec.ingressAnnotations:

...
spec:
...
  ingress:
  ...
    annotations:
      nginx.ingress.kubernetes.io/proxy-buffer-size: 16k
...

Use caution when changing the buffer size as it may slightly impact NGINX performance. Exact values are machine-dependent.