https://github.com/mattermost/mattermost-operator
Mattermost Operator for Kubernetes
https://github.com/mattermost/mattermost-operator
golang hacktoberfest kubernetes mattermost
Last synced: 3 months ago
JSON representation
Mattermost Operator for Kubernetes
- Host: GitHub
- URL: https://github.com/mattermost/mattermost-operator
- Owner: mattermost
- License: apache-2.0
- Created: 2019-03-07T15:14:20.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2026-02-16T18:04:01.000Z (4 months ago)
- Last Synced: 2026-02-16T19:19:05.024Z (4 months ago)
- Topics: golang, hacktoberfest, kubernetes, mattermost
- Language: Go
- Homepage:
- Size: 43.6 MB
- Stars: 134
- Watchers: 28
- Forks: 82
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - mattermost-operator
README
# Mattermost Operator for Kubernetes  [](https://community.mattermost.com/core/channels/cloud)
[](https://mattermost.com)
## Summary
[Mattermost](https://mattermost.com) is an open source platform for secure collaboration across the entire software development lifecycle. It's written in Golang and React and runs as a single Linux binary with MySQL or PostgreSQL.
This repo contains a Kubernetes Operator for Mattermost to simplify deploying and managing your Mattermost instance.
The Mattermost server source code is available at https://github.com/mattermost/mattermost-server.
## Install
See the installation instructions at https://docs.mattermost.com/install/install-kubernetes.html.
## Custom Resource Documentation
You can review the full list of CRD configuration options [here](./docs/mattermost_v1beta1_crd.md).
## Migrate to Mattermost Custom Resource
In version `v2.0.0` of the Mattermost Operator, several breaking changes will be introduced. Some of the more significant ones are:
- The name of the Custom Resource changed from `ClusterInstallation` to `Mattermost`.
- Support for `BlueGreen` and `Canary` deployments was dropped.
- Layout of some fields changed.
To prepare for the new release all `ClusterInstallation` Custom Resources need to be migrated to `Mattermost`.
Mattermost Operator in version `v1.12.0` provides a mechanism to make the migration easier.
To run the migration see [the automatic migration guide](./docs/migration.md).
## Restore an existing Mattermost MySQL Database
To restore an existing Mattermost MySQL Database into a new Mattermost installation using the Mattermost Operator you will need to follow these steps:
Use Case: An existing AWS RDS Database
- First you need to dump the data using mysqldump
- Create an EC2 instance and install MySQL
- Restore the dump in this new database
- Install `Percona XtraBackup`
- Perform the backup using the `Percona XtraBackup`
- `xtrabackup --innodb_file_per_table=1 --innodb_flush_log_at_trx_commit=2 --innodb_flush_method=O_DIRECT --innodb_log_files_in_group=2 --log_bin=/var/lib/mysql/mysql-bin --open_files_limit=65535 --innodb_buffer_pool_size=512M --innodb_log_file_size=128M --server-id=100 --backup=1 --slave-info=1 --stream=xbstream --host=127.0.0.1 --user=USER --password=PASSWORD --target-dir=~/xtrabackup_backupfiles/ | gzip - > BACKNAME.gz`
- Upload to an AWS S3 bucket
- Create a Mattermost Cluster, for example:
```
apiVersion: mattermost.com/v1alpha1
kind: ClusterInstallation
metadata:
name: example-clusterinstallation
spec:
ingressName: example.mattermost-example.dev
```
- Create the Restore/Backup secret with the AWS credentials
```
apiVersion: v1
kind: Secret
metadata:
name: restore-secret
type: Opaque
stringData:
AWS_ACCESS_KEY_ID: XXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY: XXXXXXXXXXXX/XXXXXXXXXXXX
AWS_REGION: us-east-1
S3_PROVIDER: AWS
```
- Create the mattermost restore manifest to deploy
```
apiVersion: mattermost.com/v1alpha1
kind: MattermostRestoreDB
metadata:
name: example-mattermostrestoredb
spec:
initBucketURL: s3://my-sample/my-backup.gz
mattermostClusterName: example-clusterinstallation
mattermostDBName: mattermostdb
mattermostDBPassword: supersecure
mattermostDBUser: mmuser
restoreSecret: restore-secret
```
If you have an machine running MySQL you just need to perform the `Percona XtraBackup` step
## Developer Flow
To test the operator locally. We recommend [Kind](https://kind.sigs.k8s.io/), however, you can use Minikube or Minishift as well.
### Prerequisites
To develop locally you will need the [Operator SDK](https://github.com/operator-framework/operator-sdk).
First, checkout and install the operator-sdk CLI:
```bash
mkdir -p $GOPATH/src/github.com/operator-framework
cd $GOPATH/src/github.com/operator-framework
git clone https://github.com/operator-framework/operator-sdk
cd operator-sdk
git checkout master
make install
```
If you made changes to any structs representing Custom Resources make sure to regenerate code and manifests:
```
make generate manifests
```
If generation produced any unexpected changes, clean old binaries and rerun the generation:
```
make clean generate manifests
```
> If the manifest generation is making changes to package paths this is [a known bug](https://github.com/kubernetes/gengo/issues/147) while running the previous command outside `GOPATH` or by having the `GOPATH` flag unset. Make sure you clone the repository in the appropriate folder (see below) and that your `GOPATH` environment variable is set.
### Building mattermost-operator
To start contributing to mattermost-operator you need to clone this repo to your local workspace.
```bash
mkdir -p $GOPATH/src/github.com/mattermost
cd $GOPATH/src/github.com/mattermost
git clone https://github.com/mattermost/mattermost-operator
cd mattermost-operator
git checkout master
make build
```
### Testing locally with Kind
Developing and testing local changes to Mattermost Operator is fairly simple. For that you can deploy Kind cluster.
> **NOTE:**
> You don't need to push the mattermost-operator image to DockerHub or any other registry if testing with kind. You can load the image, built with `make build-image`, directly to the Kind cluster by running the following:
> ```bash
> kind load docker-image mattermost/mattermost-operator:test
> ```
To spin up an appropriate Kind cluster and deploy dependencies, run:
```bash
make kind-start mysql-minio-operators
```
After Kind cluster is up and running, build Mattermost Operator image, load it to Kind cluster and deploy it. For that, run:
```bash
make build-image kind-load-image deploy
```
### Accessing Mattermost Installation on Kind
After you create Mattermost installation using Mattermost Operator on Kind cluster,
port-forward the service to access it:
```bash
kubectl port-forward svc/[MATTERMOST_NAME] 8065:8065
```
### Running Operator locally against K8s cluster
Mattermost Operator can be run on local machine against remote a Kubernetes cluster to rapidly test changes during the development.
To run Operator locally:
- Make sure you are connected to a Kubernetes cluster.
- Install Custom Resources by running: `kubectl apply -f ./config/crd/bases`.
- Install MinIO and MySQL operators: `make mysql-minio-operators`.
- Make sure Mattermost Operator **is not** running in the cluster or scale it down to 0 replicas to avoid unexpected behaviour.
- Run Operator binary: `go run .`
Be aware that running Operator locally does not verify Kubernetes manifests, RBAC rules, leader election etc.
## Notes
### Installation Size
The `spec.Size` field was modified to be treated as a write-only field.
After adjusting values according to the size, the value of `spec.Size` is erased.
Replicas and resource requests/limits values can be overridden manually but setting new Size will override those values again regardless if set by the previous Size or adjusted manually.
## Release
To release a new version of Mattermost Operator you need to:
- Have the repository up-to-date
- Have the remote upstream configured
- Have a clean repo, not pending commits and changes
As a first step of release process generate deployment manifests:
```
make yaml
```
We have a script that changes some files, commit those changes and then tag the main branch.
To run you can issue the following command:
```bash
./scripts/release.sh --tag=
```
where:
- `` can be 1.10.1 for example
## Why the Mattermost Operator Uses a ClusterRole
The Mattermost Operator is designed to manage and orchestrate multiple Mattermost installations within a Kubernetes cluster.
To enable this, it requires **cluster-wide permissions**, which are granted through a `ClusterRole`.
### Design Philosophy
The operator follows a **high-privilege controller model** built around the **principle of least privilege for managed applications**.
- The operator itself requires elevated privileges at the cluster level to create and manage resources across namespaces.
- Each Mattermost installation it provisions is isolated using its own **`ServiceAccount`** and **namespace-scoped `Role`**, ensuring that each deployment operates with minimal privileges.
This approach balances **security** and **convenience** — administrators do not need to manually create RBAC policies for each Mattermost instance.
This allows the operator to:
1. **Multi-Namespace Deployments**
The operator supports multiple Mattermost instances deployed across different namespaces (e.g., `dev`, `staging`, `prod`) using a single operator instance.
This enables platform teams to offer *Mattermost-as-a-Service* to multiple internal teams.
2. **Cluster-Scoped Resources**
Some Kubernetes resources managed by the operator (such as `IngressClass`) are **cluster-scoped** and cannot be managed with namespace-limited roles.
3. **Cross-Namespace Integrations**
The operator can provision and manage external dependencies — such as **MySQL clusters** or **MinIO instances** — that may reside in different namespaces.
Managing these cross-namespace resources requires cluster-level permissions.
4. **Namespace Metadata Access**
The operator needs to read and interact with namespace metadata to properly configure DNS names, routing, and service discovery across installations.
5. **Operational Flexibility**
Operating at the cluster level simplifies management workflows.
Platform administrators can deploy, update, and monitor multiple Mattermost instances without deploying a separate operator in each namespace.