Installing Mattermost on Kubernetes

Install a production-ready Mattermost system on a Kubernetes cluster. Deploy and manage complex Mattermost environments with less IT overhead and more automation with the Mattermost Kubernetes operator.

Set Up a Kubernetes Cluster

If you do not already have a production-ready Kubernetes cluster you will need to set one up. If you already have a Kubernetes cluster you can skip to step 2.

Your Kubernetes cluster must be version 1.12 or higher.

1. Set up a Kubernetes cluster

Kubernetes can be set up in practically any environment. See the official Kubernetes setup documentation to discover how to set up a cluster in your environment.

If you are unsure about what environment you want to run Kubernetes in, we suggest using a managed service such as Amazon EKS, Azure Kubernetes Service, Google Kubernetes Engine, or DigitalOcean Kubernetes.

Make sure to also install and configure kubectl.

2. Make sure your cluster has enough resources

Running Mattermost in Kubernetes will require different resources based on your total number of users. Here are some guidelines for the resources that Mattermost will require at different scales:

User Count Node Count Memory per Node vCPU per Node
5,000 6 8 GB 4
10,000 8 16 GB 4
25,000 14 16 GB 4

Note:

  • These resources take into account all components required for Mattermost, including proxy, database and file storage
  • Resource requirements may vary depending on user usage and bot activity
  • For larger installations, it may be beneficial to use nodes for the databases that have more memory and/or are optimized for memory
  • For installations of more than 25,000 users please contact us for sizing guidelines

Make sure your Kubernetes cluster has enough nodes to run Mattermost at your desired scale.

Installing the Mattermost Operator

The Mattermost Kubernetes Operator allows you to easily deploy and manage Mattermost installations through a single Kubernetes manifest. This operator is continuously being developed and will include additional features in the future.

1. Install the MySQL operator

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

2. Install the MinIO operator

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

3. Install NGINX Ingress Controller

Follow the instructions here.

4. 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

Deploy a Mattermost Installation

Deploying a Mattermost installation is very simple and just requires creating and applying a single manifest.

1. (Enterprise only) Create your Mattermost license secret

Save the following in a file named mattermost-license-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: mattermost-license
type: Opqaue
stringData:
  license: %LICENSE_FILE_CONTENTS%

Replace %LICENSE_FILE_CONTENTS% with the contents of your Mattermost license file.

Apply it with:

$ kubectl apply -f /path/to/mattermost-license-secret.yaml

2. Create your installation manifest file

Save the following into a file named mattermost-installation.yaml:

apiVersion: mattermost.com/v1alpha1
kind: ClusterInstallation
metadata:
  name: mm-example-full
spec:
  size: 5000users
  ingressName: example.mattermost-example.com
  ingressAnnotations:
    kubernetes.io/ingress.class: nginx
  version: 5.14.0
  mattermostLicenseSecret: ""
  database:
    storageSize: 50Gi
  minio:
    storageSize: 50Gi
  elasticSearch:
    host: ""
    username: ""
    password: ""

3. Edit your installation manifest file

Depending on your desired configuration, edit the following fields in your manifest. There are a few fields that must be modified, which are marked accordingly in the table below.

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.ingressName The DNS for your Mattermost installation. Yes
spec.version The Mattermost version. No
spec.mattermostLicenseSecret The name of the Kubernetes secret containing your license (e.g. mattermost-license). Required for enterprise deployments. Yes
spec.database.storageSize The storage size for your database. Your Kubernetes cluster must have volumes this size or larger. No
spec.minio.storageSize The storage size for your file storage. Your Kubernetes cluster must have volumes this size or larger. No
spec.elasticSearch The section for Elasticsearch settings. Remove this section if you will not be using Elasticsearch. No
spec.elasticSearch.host The hostname for your Elasticsearch instance. No
spec.elasticSearch.username The username for your Elasticsearch instance. No
spec.elasticSearch.password The password for your Elasticsearch instance. No

There are more advanced fields documented here.

4. Apply your installation manifest file

To deploy your installation, apply it with:

$ kubectl create ns mattermost
$ kubectl apply -n mattermost -f /path/to/mattermost-installation.yaml

Make sure to replace /path/to/mattermost-installation.yaml with the correct path.

4. Configure DNS and Use Mattermost

After waiting 3-5 minutes for your deployment to complete, run the following to get the hostname or IP address to access Mattermost at:

$ kubectl -n mattermost get ingress

This will give you either a hostname or IP address under the ADDRESS column. Copy that address.

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.

Go to your ingressName URL in your browser and use Mattermost.