Install Mattermost on Kubernetes
Available on all plans
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.
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.
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
To install the operators using the Mattermost Operator Helm chart, follow the instructions here.
(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: 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: 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:
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.
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.
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. (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:
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.
For MySQL databases, the check is performed via HTTP call; therefore
DB_CONNECTION_CHECK_URLshould be an HTTP URL.
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:
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 (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_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: 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"
Apply the installation manifest file. Manifests are applied with
kubectl. Before running the commands make sure you are connected to your Kubernetes cluster.
Create the Mattermost namespace:$ 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:$ kubectl -n mattermost port-forward svc/[YOUR_MATTERMOST_NAME] 8065:8065
Then navigate to http://localhost:8065.