On this page
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.
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.
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
(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
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:
The name of your Mattermost as it will be shown in Kubernetes. The shorter the better.
The size of your installation. This can be ‘100users’, ‘1000users, ‘5000users’, ‘10000users’, or ‘25000users’.
The DNS for your Mattermost installation.
The Mattermost version. Refer to the version archive page when selecting a mattermost version.
The name of the Kubernetes secret containing your license (e.g. mattermost-license). Required for Enterprise deployments.
List of custom environment variables for the Mattermost instance. Only required when tweaking Mattermost configuration is required.
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:
Connection string to the database.
Connection string to read replicas of the database.
The URL used for checking that the database is accessible.
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
For PostgreSQL databases, the connection is checked with pg_isready so the
DB_CONNECTION_CHECK_URLis 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:
Filestore access key.
Filestore secret key.
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_AMAZONS3SSLenvironment 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
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
ADDRESScolumn, open your browser, and connect to Mattermost.
Use your domain registration service to create a canonical name or IP address record for the
ingress.hostin 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.hostURL in your browser and use Mattermost.
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
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.
No. Helm is a good mechanism to deploy operators and other applications but doesn’t facilitate application management.
No, other options and operators can be added.
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.
Currently this is not supported as it introduces the possibility of missing a data entry in the database.
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.
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
Use caution when changing the buffer size as it may slightly impact NGINX performance. Exact values are machine-dependent.