From 28658f51361ccbac92b726772c560ba9abb21517 Mon Sep 17 00:00:00 2001 From: Katie Wiersgalla <39744472+wiersgallak@users.noreply.github.com> Date: Mon, 28 Apr 2025 15:43:03 -0500 Subject: [PATCH 1/5] Update deploy-k8s-aks.rst Updates to formatting and simplification of instructions --- .../server/kubernetes/deploy-k8s-aks.rst | 66 ++++++++++--------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/source/deploy/server/kubernetes/deploy-k8s-aks.rst b/source/deploy/server/kubernetes/deploy-k8s-aks.rst index 80d31621c23..a7238b7afd6 100644 --- a/source/deploy/server/kubernetes/deploy-k8s-aks.rst +++ b/source/deploy/server/kubernetes/deploy-k8s-aks.rst @@ -7,36 +7,34 @@ You can use a supported `Azure Marketplace Container Offer `__ to install Mattermost on your existing Azure infrastructure. -.. important:: - - You are responsible for Azure costs associated with any infrastructure you spin up to host a Mattermost server, and Azure credits cannot be applied towards the purchase of a Mattermost license. +Before you begin +---------------- -**Infrastructure pre-requisites** +Before deploying, make sure you have the following: -Deploying Mattermost on Azure AKS requires the following database and cluster prerequisites. +- **An AKS cluster**: with the `Application Gateway Ingress Controller (AGIC) add-on `_ enabled or another Ingress controller deployed. -- **PostgreSQL v13.0+ database**: Mattermost requires a pre-existing PostgreSQL database within your infrastructure. We recommend using `Azure Database for PostgreSQL - Flexible Server `_. Deploy one by following `this Microsoft quick start guide `_. We recommend using Private Access for your database. -- **Running AKS cluster**: Mattermost Azure Container Offer requires a pre-existing Kubernetes Cluster with an Ingress Controller pre-installed. We recommend creating a new AKS cluster with the `AGIC add-on enabled `_. Follow `this tutorial `_ to create a new AKS cluster with the add-on enabled. +- **PostgreSQL v13.0+ database**: `Azure Database for PostgreSQL - Flexible Server with Private Access `_ is recommended. Deploy one by following `this Microsoft quick start guide `_. -.. note:: +- **Private Network Connectivity**: Verify that there is network connectivity between your AKS cluster and the PostgreSQL database. - - Connectivity should be already in place between the AKS cluster and the PostgreSQL database. - - Any pre-installed Ingress Controller within the cluster that supports the Ingress Kubernetes resource and TLS termination should work out of the box. +- **Valid DNS name and TLS certificate**: You must have access to a DNS zone and provide a valid TLS key and certificate for the Ingress Controller. -**Deployment pre-requisites** +- **Node Capacity**: At least 2 AKS nodes for high availability when deploying for 100 users or more. -Deploying Mattermost on Azure AKS requires the following deployment prerequisites. +- **License Key**: Trial or Enterprise license to test high availability and other Enterprise features. -- **Valid DNS name and TLS certificates**: Mattermost relies on strong TLS certification in order to provide all the features to users. You need to have access to a DNS zone and be able to provide a valid TLS key and certificate for the Ingress Controller. -- **Mattermost License and AKS Capacity**: (Mattermost Enterprise only) If your deployment option is for more than ``100 users``, you must have more than 2 nodes on your AKS cluster to support High Availability, and you must provide a valid Mattermost License file. Providing a license is optional at this stage. You can enable a **30 day** Mattermost trial once the server is deployed. -**Installation steps** +Installation steps +------------------ The installation process includes deploying Mattermost and updating the server. **Step 1: Deploy Mattermost** -1. Navigate to our `Azure Marketplace Container Offer `_ and get the offer. Alternatively, you can go to the ``Extensions + Applications`` section of your AKS cluster and install the Mattermost offering from there. Visit the `Microsoft cluster extensions documentation `_ to learn more. +1. Deploy Mattermost from the `Azure Marketplace Container Offer `_ and select **Get it now**. + + - Alternatively, you can go to the ``Extensions + Applications`` section of your AKS cluster and install the Mattermost offering from there. Visit the `Microsoft cluster extensions documentation `_ to learn more. 2. Choose the **Resource Group** and the **Region** of your installed AKS and PostgreSQL database. @@ -48,32 +46,30 @@ The installation process includes deploying Mattermost and updating the server. .. image:: /_static/images/azure/aks-cluster.png :alt: An example of the Azure AKS cluster setup screen. -4. Fill in the details for your PostgreSQL database. +4. Fill in the details for your PostgreSQL database. Ensure the user specified has full access. .. image:: /_static/images/azure/postgreSQL.png :alt: An example of the Azure AKS Database setup screen. -.. note:: - - - Connectivity should be already in place between the AKS cluster and the database. - - Database should already exist and the user specified must have full access. -5. Adjust deployment details. +5. Specify Deployment Details including Deployment Name and Deployment Size. Click the checkbox to Deploy Minio, a required utility for this installation that will provide filestore functionality for your Mattermost instance. .. image:: /_static/images/azure/deployment-details.png :alt: An example of the Azure AKS Deployment Details setup screen. -.. note:: - You can define a Deployment size to automatically adjust the installation. A valid Mattermost license is required for deployments of more than 100 users. - 6. Configure Mattermost installation hostname and Ingress details. The AGIC add-on is used in the following example to show the ingress annotations required. + a. You can use any pre-installed Ingress Controller in your cluster as long as it supports Kubernetes Ingress and TLS termination. .. code-block:: yaml kubernetes.io/ingress.class: azure/application-gateway appgw.ingress.kubernetes.io/ssl-redirect: "true" -7. Upload yor own TLS certificates at this stage to take advantage of all Mattermost features. +7. Additionally, we recommend considering: + + a. Enforcing a minimum TLS version (e.g., TLS 1.2). + b. Deploying a Web Application Firewall (WAF) for additional protection, if supported by your ingress controller. + c. Limiting access using Kubernetes Network Policies. .. image:: /_static/images/azure/networking-details.png :alt: An example of the Azure AKS Networking Details setup screen. @@ -86,16 +82,18 @@ The installation process includes deploying Mattermost and updating the server. kubectl -n mattermost-operator get ingress - b. Get the resulting IP address from the ``ADDRESS`` column, and use your domain registration service to create a DNS record. - c. You should be good to go. +9. Use your IP address from the ``ADDRESS`` column, and create a DNS record in your domain registration service. + +10. Access your working Mattermost installation at the URL you’ve determined in your DNS record. -Learn more about managing your Mattermost server by visiting the :doc:`Managing Mattermost ` documentation. +Learn more about administrating your Mattermost server by visiting the :doc:`Administration Guide `. -**Step 2: Upgrade Mattermost** +Upgrade Mattermost via your AKS cluster +--------------------------------------- 1. Visit the ``Extensions + Applications`` section of your AKS cluster where your Mattermost installation is deployed. 2. You can enable minor version auto upgrades since these are not updating Mattermost version -3. Expand the ``Configurarion Settings`` table and add the below configuration and the version you want to install as a value. +3. Expand the ``Configuration Settings`` table and add the below configuration and the version you want to install as a value. .. code:: @@ -104,4 +102,8 @@ Learn more about managing your Mattermost server by visiting the :doc:`Managing .. image:: /_static/images/global-azure-mattermost-version.png :alt: An example of using custom Mattermost version. -4. Select **Save** and wait for the upgrade. \ No newline at end of file +4. Select **Save** and wait for the upgrade. + +.. important:: + + You are responsible for Azure costs associated with any infrastructure you spin up to host a Mattermost server, and Azure credits cannot be applied towards the purchase of a Mattermost license. From 885c31e8c437d188b100bf8cea8077634283b00f Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Mon, 28 Apr 2025 17:18:54 -0400 Subject: [PATCH 2/5] Update source/deploy/server/kubernetes/deploy-k8s-aks.rst --- source/deploy/server/kubernetes/deploy-k8s-aks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/deploy/server/kubernetes/deploy-k8s-aks.rst b/source/deploy/server/kubernetes/deploy-k8s-aks.rst index a7238b7afd6..8daaec99fa9 100644 --- a/source/deploy/server/kubernetes/deploy-k8s-aks.rst +++ b/source/deploy/server/kubernetes/deploy-k8s-aks.rst @@ -67,7 +67,7 @@ The installation process includes deploying Mattermost and updating the server. 7. Additionally, we recommend considering: - a. Enforcing a minimum TLS version (e.g., TLS 1.2). + a. Enforcing a minimum TLS version (e.g., TLS 1.2). b. Deploying a Web Application Firewall (WAF) for additional protection, if supported by your ingress controller. c. Limiting access using Kubernetes Network Policies. From e7367b8e9444096ee6ea03506cb07de6ac7a170d Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Mon, 28 Apr 2025 17:19:06 -0400 Subject: [PATCH 3/5] Update source/deploy/server/kubernetes/deploy-k8s-aks.rst --- source/deploy/server/kubernetes/deploy-k8s-aks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/deploy/server/kubernetes/deploy-k8s-aks.rst b/source/deploy/server/kubernetes/deploy-k8s-aks.rst index 8daaec99fa9..c826d6a8dfb 100644 --- a/source/deploy/server/kubernetes/deploy-k8s-aks.rst +++ b/source/deploy/server/kubernetes/deploy-k8s-aks.rst @@ -69,7 +69,7 @@ The installation process includes deploying Mattermost and updating the server. a. Enforcing a minimum TLS version (e.g., TLS 1.2). b. Deploying a Web Application Firewall (WAF) for additional protection, if supported by your ingress controller. - c. Limiting access using Kubernetes Network Policies. + c. Limiting access using Kubernetes Network Policies. .. image:: /_static/images/azure/networking-details.png :alt: An example of the Azure AKS Networking Details setup screen. From 516fe31ef8955e450f4ac71c28f1704ad4c953a2 Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Tue, 29 Apr 2025 10:45:47 -0400 Subject: [PATCH 4/5] Formatting updates --- source/deploy/server/deploy-kubernetes.rst | 6 ++--- .../server/kubernetes/deploy-k8s-aks.rst | 23 ++++++++----------- .../deploy/server/kubernetes/deploy-k8s.rst | 3 +-- 3 files changed, 14 insertions(+), 18 deletions(-) diff --git a/source/deploy/server/deploy-kubernetes.rst b/source/deploy/server/deploy-kubernetes.rst index fef2b9da8fb..a07f7f3d8f4 100644 --- a/source/deploy/server/deploy-kubernetes.rst +++ b/source/deploy/server/deploy-kubernetes.rst @@ -56,11 +56,11 @@ Deploying Mattermost in a Kubernetes environment allows you to harness Kubernete 4. Save your Ingress and TLS YAML manifests to files (e.g., ``ingress.yaml`` and ``tls.yaml``) and apply them to your cluster using Kubernetes command-line tools. -Configure DNS by ensuring your domain name ``your-domain.com`` is properly pointed to the external IP address of your cluster or ingress controller. You can verify this using tools like nslookup or dig. +5. Configure DNS by ensuring your domain name ``your-domain.com`` is properly pointed to the external IP address of your cluster or ingress controller. You can verify this using tools like nslookup or dig. -5. After applying the Ingress, verify HTTPS Access by navigating to your domain (e.g., ``https://your-domain.com``) in a web browser to verify HTTPS access. If you encounter issues, check ingress controller logs (``kubectl logs -n ``, DNS records, and TLS configurations. +6. After applying the Ingress, verify HTTPS Access by navigating to your domain (e.g., ``https://your-domain.com``) in a web browser to verify HTTPS access. If you encounter issues, check ingress controller logs (``kubectl logs -n ``, DNS records, and TLS configurations. -6. Enable HSTS and Additional Security in your Ingress annotations. +7. Enable HSTS and Additional Security in your Ingress annotations. Additionally, consider: diff --git a/source/deploy/server/kubernetes/deploy-k8s-aks.rst b/source/deploy/server/kubernetes/deploy-k8s-aks.rst index c826d6a8dfb..119d2cfea26 100644 --- a/source/deploy/server/kubernetes/deploy-k8s-aks.rst +++ b/source/deploy/server/kubernetes/deploy-k8s-aks.rst @@ -7,8 +7,7 @@ You can use a supported `Azure Marketplace Container Offer `__ to install Mattermost on your existing Azure infrastructure. -Before you begin ----------------- +**Before you begin** Before deploying, make sure you have the following: @@ -24,14 +23,12 @@ Before deploying, make sure you have the following: - **License Key**: Trial or Enterprise license to test high availability and other Enterprise features. - -Installation steps ------------------- +**Installation steps** The installation process includes deploying Mattermost and updating the server. **Step 1: Deploy Mattermost** - + 1. Deploy Mattermost from the `Azure Marketplace Container Offer `_ and select **Get it now**. - Alternatively, you can go to the ``Extensions + Applications`` section of your AKS cluster and install the Mattermost offering from there. Visit the `Microsoft cluster extensions documentation `_ to learn more. @@ -58,12 +55,13 @@ The installation process includes deploying Mattermost and updating the server. :alt: An example of the Azure AKS Deployment Details setup screen. 6. Configure Mattermost installation hostname and Ingress details. The AGIC add-on is used in the following example to show the ingress annotations required. + a. You can use any pre-installed Ingress Controller in your cluster as long as it supports Kubernetes Ingress and TLS termination. - .. code-block:: yaml + .. code-block:: yaml - kubernetes.io/ingress.class: azure/application-gateway - appgw.ingress.kubernetes.io/ssl-redirect: "true" + kubernetes.io/ingress.class: azure/application-gateway + appgw.ingress.kubernetes.io/ssl-redirect: "true" 7. Additionally, we recommend considering: @@ -86,10 +84,9 @@ The installation process includes deploying Mattermost and updating the server. 10. Access your working Mattermost installation at the URL you’ve determined in your DNS record. -Learn more about administrating your Mattermost server by visiting the :doc:`Administration Guide `. +Learn more about administrating your Mattermost server by visiting the :doc:`Administration Guide `. -Upgrade Mattermost via your AKS cluster ---------------------------------------- +**Step 2: Upgrade Mattermost via your AKS cluster** 1. Visit the ``Extensions + Applications`` section of your AKS cluster where your Mattermost installation is deployed. 2. You can enable minor version auto upgrades since these are not updating Mattermost version @@ -106,4 +103,4 @@ Upgrade Mattermost via your AKS cluster .. important:: - You are responsible for Azure costs associated with any infrastructure you spin up to host a Mattermost server, and Azure credits cannot be applied towards the purchase of a Mattermost license. + You are responsible for Azure costs associated with any infrastructure you spin up to host a Mattermost server, and Azure credits cannot be applied towards the purchase of a Mattermost license. \ No newline at end of file diff --git a/source/deploy/server/kubernetes/deploy-k8s.rst b/source/deploy/server/kubernetes/deploy-k8s.rst index 787e3757019..d310e5fa04f 100644 --- a/source/deploy/server/kubernetes/deploy-k8s.rst +++ b/source/deploy/server/kubernetes/deploy-k8s.rst @@ -206,8 +206,7 @@ Create a file named ``mattermost-filestore-secret.yaml`` to store the credential 4. If you are using Amazon S3, it's recommended to enable server-side encryption (SSE) and SSL. Add the following environment variables to the ``mattermostEnv`` section: -TBD - + **Review Mattermost Resource Status** From 6e23a9c64816fa8ed21cc92186af2e8c30184b99 Mon Sep 17 00:00:00 2001 From: Nick Misasi Date: Wed, 30 Apr 2025 11:59:14 -0400 Subject: [PATCH 5/5] Add section for S3 encryption --- source/deploy/server/kubernetes/deploy-k8s.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/source/deploy/server/kubernetes/deploy-k8s.rst b/source/deploy/server/kubernetes/deploy-k8s.rst index d310e5fa04f..ff9e8b23018 100644 --- a/source/deploy/server/kubernetes/deploy-k8s.rst +++ b/source/deploy/server/kubernetes/deploy-k8s.rst @@ -206,7 +206,13 @@ Create a file named ``mattermost-filestore-secret.yaml`` to store the credential 4. If you are using Amazon S3, it's recommended to enable server-side encryption (SSE) and SSL. Add the following environment variables to the ``mattermostEnv`` section: - + .. code-block:: yaml + + spec: + mattermostEnv: + MM_FILESETTINGS_AMAZONS3SSL: true + MM_FILESETTINGS_AMAZONS3SSE: true + **Review Mattermost Resource Status**