From b30d4f4400c047ede78978cf22f0c8ecee6cfce4 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 5 May 2026 18:35:52 -0500 Subject: [PATCH 1/6] Add FIPS migration guide for existing deployments Adds a step-by-step guide for migrating an existing Docker or Kubernetes Mattermost deployment to the FIPS-compliant container image, separate from the existing FIPS overview which covers new deployments. Links the new page from the existing FIPS overview note and registers it via a hidden toctree on the containers deployment page. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../server/containers/fips-migration.rst | 133 ++++++++++++++++++ .../server/containers/fips-stig.rst | 2 +- .../server/deploy-containers.rst | 7 + 3 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 source/deployment-guide/server/containers/fips-migration.rst diff --git a/source/deployment-guide/server/containers/fips-migration.rst b/source/deployment-guide/server/containers/fips-migration.rst new file mode 100644 index 00000000000..75c90263c3d --- /dev/null +++ b/source/deployment-guide/server/containers/fips-migration.rst @@ -0,0 +1,133 @@ +Migrate an existing deployment to FIPS-compliant containers +============================================================ + +.. include:: ../../../_static/badges/all-commercial.rst + :start-after: :nosearch: + +From Mattermost v11, each release ships in two image variants: a standard Enterprise build (``mattermost/mattermost-enterprise-edition``) and a FIPS-compliant build (``mattermost/mattermost-enterprise-fips-edition``). Migrating an existing deployment to the FIPS image is primarily a matter of replacing the image and restarting Mattermost. No data migration is required, and rollback is symmetric. + +This guide covers migrating an existing Mattermost Server deployment running on Docker or Kubernetes. FIPS images are only supported for Docker- and Kubernetes-based deployments; Linux package and tarball installations can't be migrated to FIPS in place. + +Mattermost's FIPS offering also covers the Mattermost Operator and a self-hosted Push Proxy. Migrating those components is out of scope for this guide. + +For background on what the FIPS build is and how it's constructed, see the :doc:`FIPS overview `. + +Before you begin +---------------- + +1. **Back up your database and configuration.** Always take a full backup before changing the image. See the :doc:`backup and disaster recovery ` documentation. + +2. **Confirm your deployment type.** FIPS images are supported on Docker, Docker Compose, and Kubernetes only. If you're running Mattermost from a Linux package or tarball, you can't migrate in place. + +3. **Check your Mattermost version.** FIPS images are available from v11.0 onward and use the same release tags as the standard Enterprise images. Plan to migrate to the matching FIPS tag for your current version. + +4. **Plan for additional plugins.** The FIPS image includes Boards, Playbooks, and Agents prepackaged and running in FIPS mode. Any additional plugins you've installed will continue to run inside the FIPS image, but they run in non-FIPS mode. This is expected behavior, not a configuration error. + +5. **PostgreSQL password length.** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, rotate it and update the connection string in your Mattermost configuration before migrating. + +6. **Plan for downtime.** The migration requires pulling the new image and restarting the Mattermost container or pod. + +Migrate a Kubernetes deployment +------------------------------- + +These steps assume your deployment is managed by the Mattermost Operator using a ``Mattermost`` custom resource. + +1. Edit the ``Mattermost`` custom resource to point at the FIPS image. You can edit the live resource directly: + + .. code-block:: sh + + kubectl edit mattermost + + Or update your manifest file and re-apply it. + +2. In ``spec.image``, change the value from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. Keep ``spec.version`` aligned with your current release tag. For example: + + .. code-block:: yaml + + spec: + image: mattermost/mattermost-enterprise-fips-edition + version: 11.6.1 + +3. If you edited a manifest file, apply it: + + .. code-block:: sh + + kubectl apply -f .yaml + +4. Watch the rollout to confirm the new pods come up healthy: + + .. code-block:: sh + + kubectl rollout status deployment/ + +5. Verify the running pods are using the FIPS image: + + .. code-block:: sh + + kubectl describe pod | grep Image + +Migrate a Docker or Docker Compose deployment +--------------------------------------------- + +These steps are written for the official `Mattermost Docker deployment `_. If you're using a custom Docker setup, adapt the container and service names accordingly. + +1. Stop the Mattermost container: + + .. code-block:: sh + + docker compose stop mattermost + +2. Edit ``docker-compose.yml``. In the ``mattermost`` service, change the ``image:`` value from ``mattermost/mattermost-enterprise-edition:`` to ``mattermost/mattermost-enterprise-fips-edition:``. Keep the same release tag. For example: + + .. code-block:: yaml + + services: + mattermost: + image: mattermost/mattermost-enterprise-fips-edition:11.6.1 + +3. Pull the FIPS image: + + .. code-block:: sh + + docker compose pull mattermost + +4. Recreate the Mattermost container so the new image is applied: + + .. code-block:: sh + + docker compose up -d mattermost + +5. Verify the running container is using the FIPS image: + + .. code-block:: sh + + docker inspect mattermost --format '{{.Config.Image}}' + +After migration +--------------- + +1. Confirm Mattermost starts cleanly. Tail the logs and watch for startup errors: + + .. code-block:: sh + + kubectl logs -f deployment/ + + Or, on Docker: + + .. code-block:: sh + + docker compose logs -f mattermost + +2. Sign in and verify core functionality (sending messages, file uploads, search). + +3. Confirm the prepackaged plugins (Boards, Playbooks, Agents) load successfully. In the System Console, go to **Plugins > Plugin Management** and confirm they're enabled and healthy. + +4. If you have additional plugins installed, confirm they still load. They'll run in non-FIPS mode inside the FIPS image — this is expected. + +Roll back +--------- + +If the migration doesn't go as planned, rolling back is symmetric: revert the image reference and redeploy. No data migration is involved. + +- **Kubernetes:** Edit the ``Mattermost`` custom resource and change ``spec.image`` back to ``mattermost/mattermost-enterprise-edition``. Re-apply or save, and watch the rollout. +- **Docker / Docker Compose:** Restore the original ``image:`` value in ``docker-compose.yml`` and run ``docker compose pull mattermost`` followed by ``docker compose up -d mattermost``. diff --git a/source/deployment-guide/server/containers/fips-stig.rst b/source/deployment-guide/server/containers/fips-stig.rst index a78b7e48305..28546888aa2 100644 --- a/source/deployment-guide/server/containers/fips-stig.rst +++ b/source/deployment-guide/server/containers/fips-stig.rst @@ -26,4 +26,4 @@ All application-level code uses only FIPS-approved algorithms, ensuring that cry .. note:: - The Mattermost FIPS image includes only prepackaged Boards, Playbooks, and Agents. Additional plugins can be added to the Mattermost FIPS image, but they will run in non-FIPS mode. - - Existing Docker or Kubernetes-based deployments can change the image from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. + - Existing Docker or Kubernetes-based deployments can change the image from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. See :doc:`Migrate an existing deployment to FIPS-compliant containers ` for step-by-step instructions. diff --git a/source/deployment-guide/server/deploy-containers.rst b/source/deployment-guide/server/deploy-containers.rst index a47a145f6e1..f8425b6ecf1 100644 --- a/source/deployment-guide/server/deploy-containers.rst +++ b/source/deployment-guide/server/deploy-containers.rst @@ -103,3 +103,10 @@ Additionally, consider: - Set up proper firewall rules to restrict unauthorized access and monitor traffic using tools like Fail2Ban or Wazuh. By following these steps, your Mattermost deployment using Docker containers will be accessible securely over HTTPS with efficient proxying through NGINX. Implementing the additional security recommendations will further protect your environment against evolving threats. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Migrate an existing deployment to FIPS-compliant containers From 0edcf7613fd4c4b72a125fc7a82b38033c7e01aa Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 5 May 2026 18:48:22 -0500 Subject: [PATCH 2/6] Restrict FIPS migration guide to Entry/Enterprise/Enterprise Advanced MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIPS is a Kubernetes/Docker-only offering and follows the same plan availability as Kubernetes deployments — not available on Professional. Swap the badge from all-commercial to entry-ent to match the existing Kubernetes deployment page. Co-Authored-By: Claude Opus 4.7 (1M context) --- source/deployment-guide/server/containers/fips-migration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/deployment-guide/server/containers/fips-migration.rst b/source/deployment-guide/server/containers/fips-migration.rst index 75c90263c3d..fd43b925abf 100644 --- a/source/deployment-guide/server/containers/fips-migration.rst +++ b/source/deployment-guide/server/containers/fips-migration.rst @@ -1,7 +1,7 @@ Migrate an existing deployment to FIPS-compliant containers ============================================================ -.. include:: ../../../_static/badges/all-commercial.rst +.. include:: ../../../_static/badges/entry-ent.rst :start-after: :nosearch: From Mattermost v11, each release ships in two image variants: a standard Enterprise build (``mattermost/mattermost-enterprise-edition``) and a FIPS-compliant build (``mattermost/mattermost-enterprise-fips-edition``). Migrating an existing deployment to the FIPS image is primarily a matter of replacing the image and restarting Mattermost. No data migration is required, and rollback is symmetric. From 4ec3a6ee13cc57f001a682ef35e8689a2fc884ce Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 5 May 2026 21:32:54 -0500 Subject: [PATCH 3/6] Address review feedback on FIPS migration guide - Make Kubernetes commands namespace-aware and workload-agnostic. Use kubectl -n [namespace] consistently and replace deployment- targeted rollout/log commands with pod-level equivalents that don't assume the workload kind or naming derived from the CR name. - Switch the Docker section to the .env-based image swap supported by the official mattermost/docker deployment (MATTERMOST_IMAGE / MATTERMOST_IMAGE_TAG) instead of editing docker-compose.yml directly. Use a placeholder rather than a hardcoded version. - Rewrite the FIPS overview cross-link to point readers explicitly at the FIPS/STIG tab on Deploy Mattermost using Containers. - Expand the v11.7 14-character Postgres password prerequisite with pointers to where the password is stored in each supported deployment (.env for Docker, the database Secret referenced by the Mattermost CR for Operator deployments). Co-Authored-By: Claude Opus 4.7 (1M context) --- .../server/containers/fips-migration.rst | 53 +++++++++++-------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/source/deployment-guide/server/containers/fips-migration.rst b/source/deployment-guide/server/containers/fips-migration.rst index fd43b925abf..610bcac7523 100644 --- a/source/deployment-guide/server/containers/fips-migration.rst +++ b/source/deployment-guide/server/containers/fips-migration.rst @@ -10,7 +10,7 @@ This guide covers migrating an existing Mattermost Server deployment running on Mattermost's FIPS offering also covers the Mattermost Operator and a self-hosted Push Proxy. Migrating those components is out of scope for this guide. -For background on what the FIPS build is and how it's constructed, see the :doc:`FIPS overview `. +For background on what the FIPS build is and how it's constructed, see the **FIPS/STIG** tab on :doc:`Deploy Mattermost using Containers `. Before you begin ---------------- @@ -23,7 +23,7 @@ Before you begin 4. **Plan for additional plugins.** The FIPS image includes Boards, Playbooks, and Agents prepackaged and running in FIPS mode. Any additional plugins you've installed will continue to run inside the FIPS image, but they run in non-FIPS mode. This is expected behavior, not a configuration error. -5. **PostgreSQL password length.** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, rotate it and update the connection string in your Mattermost configuration before migrating. +5. **PostgreSQL password length.** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, rotate it in PostgreSQL first, then update wherever your deployment stores the password before migrating: in the official Docker deployment, the ``POSTGRES_PASSWORD`` value in ``.env``; in Operator-managed Kubernetes deployments, the database Secret referenced by your ``Mattermost`` custom resource (commonly under ``spec.database.external.secret``). Restart Mattermost so the new credentials take effect — the migration itself recreates the container, so this can happen as part of the image swap rather than as a separate restart. 6. **Plan for downtime.** The migration requires pulling the new image and restarting the Mattermost container or pod. @@ -32,15 +32,23 @@ Migrate a Kubernetes deployment These steps assume your deployment is managed by the Mattermost Operator using a ``Mattermost`` custom resource. -1. Edit the ``Mattermost`` custom resource to point at the FIPS image. You can edit the live resource directly: +In the steps below, replace ``[namespace]`` with the namespace your Mattermost installation runs in. If you omit ``-n [namespace]``, ``kubectl`` uses your current context's default namespace. + +1. Find the name of your Mattermost custom resource: + + .. code-block:: sh + + kubectl -n [namespace] get mattermost + +2. Edit the ``Mattermost`` custom resource to point at the FIPS image. You can edit the live resource directly: .. code-block:: sh - kubectl edit mattermost + kubectl -n [namespace] edit mattermost [installation-name] Or update your manifest file and re-apply it. -2. In ``spec.image``, change the value from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. Keep ``spec.version`` aligned with your current release tag. For example: +3. In ``spec.image``, change the value from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. Keep ``spec.version`` aligned with your current release tag. For example: .. code-block:: yaml @@ -48,28 +56,28 @@ These steps assume your deployment is managed by the Mattermost Operator using a image: mattermost/mattermost-enterprise-fips-edition version: 11.6.1 -3. If you edited a manifest file, apply it: +4. If you edited a manifest file, apply it: .. code-block:: sh - kubectl apply -f .yaml + kubectl -n [namespace] apply -f .yaml -4. Watch the rollout to confirm the new pods come up healthy: +5. Watch the Mattermost pods until the new ones reach ``Running`` and the old ones terminate: .. code-block:: sh - kubectl rollout status deployment/ + kubectl -n [namespace] get pods -w -5. Verify the running pods are using the FIPS image: +6. Verify the running pods are using the FIPS image: .. code-block:: sh - kubectl describe pod | grep Image + kubectl -n [namespace] get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' Migrate a Docker or Docker Compose deployment --------------------------------------------- -These steps are written for the official `Mattermost Docker deployment `_. If you're using a custom Docker setup, adapt the container and service names accordingly. +These steps are written for the official `Mattermost Docker deployment `_, which selects the Mattermost image and tag through ``.env`` variables (``MATTERMOST_IMAGE`` and ``MATTERMOST_IMAGE_TAG``) referenced from ``docker-compose.yml`` as ``mattermost/${MATTERMOST_IMAGE}:${MATTERMOST_IMAGE_TAG}``. If you're using a custom Docker setup that hardcodes the image in ``docker-compose.yml`` or uses different variable names, adapt these steps accordingly. 1. Stop the Mattermost container: @@ -77,13 +85,12 @@ These steps are written for the official `Mattermost Docker deployment `` to ``mattermost/mattermost-enterprise-fips-edition:``. Keep the same release tag. For example: +2. Edit your ``.env`` file. Change ``MATTERMOST_IMAGE`` from ``mattermost-enterprise-edition`` to ``mattermost-enterprise-fips-edition``. Leave ``MATTERMOST_IMAGE_TAG`` set to your current release tag — FIPS images are published under the same tags as the standard Enterprise images. - .. code-block:: yaml + .. code-block:: text - services: - mattermost: - image: mattermost/mattermost-enterprise-fips-edition:11.6.1 + MATTERMOST_IMAGE=mattermost-enterprise-fips-edition + MATTERMOST_IMAGE_TAG= 3. Pull the FIPS image: @@ -91,11 +98,11 @@ These steps are written for the official `Mattermost Docker deployment + kubectl -n [namespace] logs -f [pod-name] - Or, on Docker: + On Docker: .. code-block:: sh @@ -130,4 +137,4 @@ Roll back If the migration doesn't go as planned, rolling back is symmetric: revert the image reference and redeploy. No data migration is involved. - **Kubernetes:** Edit the ``Mattermost`` custom resource and change ``spec.image`` back to ``mattermost/mattermost-enterprise-edition``. Re-apply or save, and watch the rollout. -- **Docker / Docker Compose:** Restore the original ``image:`` value in ``docker-compose.yml`` and run ``docker compose pull mattermost`` followed by ``docker compose up -d mattermost``. +- **Docker / Docker Compose:** Restore the original ``MATTERMOST_IMAGE`` value in ``.env`` (``mattermost-enterprise-edition``) and run ``docker compose pull mattermost`` followed by ``docker compose up -d --force-recreate mattermost``. From ff5f1e5b1ea7dbcd3be9bbc29a18defdabf265a1 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Wed, 6 May 2026 14:45:04 -0500 Subject: [PATCH 4/6] Restructure Postgres password prerequisite into sub-steps Break the dense v11.7 14-character password prerequisite into a/b/c sub-steps so the sequencing is unambiguous: rotate the password in Postgres, then update where the deployment stores it, then proceed to the image swap. Add a one-line ALTER USER example so novice admins have a starting point. Resolve the contradictory restart guidance: the migration's container recreate applies the new credentials, so no separate restart is needed. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../server/containers/fips-migration.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/source/deployment-guide/server/containers/fips-migration.rst b/source/deployment-guide/server/containers/fips-migration.rst index 610bcac7523..1af72d33bf4 100644 --- a/source/deployment-guide/server/containers/fips-migration.rst +++ b/source/deployment-guide/server/containers/fips-migration.rst @@ -23,7 +23,17 @@ Before you begin 4. **Plan for additional plugins.** The FIPS image includes Boards, Playbooks, and Agents prepackaged and running in FIPS mode. Any additional plugins you've installed will continue to run inside the FIPS image, but they run in non-FIPS mode. This is expected behavior, not a configuration error. -5. **PostgreSQL password length.** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, rotate it in PostgreSQL first, then update wherever your deployment stores the password before migrating: in the official Docker deployment, the ``POSTGRES_PASSWORD`` value in ``.env``; in Operator-managed Kubernetes deployments, the database Secret referenced by your ``Mattermost`` custom resource (commonly under ``spec.database.external.secret``). Restart Mattermost so the new credentials take effect — the migration itself recreates the container, so this can happen as part of the image swap rather than as a separate restart. +5. **PostgreSQL password length.** Beginning with Mattermost v11.7, the Postgres password used by the Mattermost server must be at least 14 characters when running the FIPS image. If your current password is shorter, complete these steps before swapping the image: + + a. Rotate the password in PostgreSQL. For example, connecting as a Postgres superuser and replacing ``mmuser`` and ```` to match your deployment: + + .. code-block:: sql + + ALTER USER mmuser WITH PASSWORD ''; + + b. Update the password where your deployment stores it: in the official Docker deployment, the ``POSTGRES_PASSWORD`` value in ``.env``; in Operator-managed Kubernetes deployments, the database Secret referenced by your ``Mattermost`` custom resource (commonly under ``spec.database.external.secret``). + + c. Proceed to the image swap procedure for your deployment type below. Recreating the container as part of the migration applies the new credentials — no separate restart is required. 6. **Plan for downtime.** The migration requires pulling the new image and restarting the Mattermost container or pod. From a8b1afc2b3d27008cdee0a6a2eb3d5c4390fc635 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 14 Jul 2026 16:03:19 -0500 Subject: [PATCH 5/6] Address review feedback on FIPS migration guide - Retitle to "...FIPS-compliant images" (guide covers K8s too, not just containers) - Move page up to server level (peer of the deployment methods it spans); register in server-deployment-planning toctree, drop the deploy-containers entry - Use angle-bracket placeholders ( etc.) per repo convention - Rename section to "Verify the migration" for action-based parity - Tighten scope and Operator/Push Proxy out-of-scope wording Co-Authored-By: Claude Opus 4.8 (1M context) --- .../server/containers/fips-stig.rst | 2 +- .../server/deploy-containers.rst | 7 ----- .../{containers => }/fips-migration.rst | 28 +++++++++---------- .../server/server-deployment-planning.rst | 2 ++ 4 files changed, 17 insertions(+), 22 deletions(-) rename source/deployment-guide/server/{containers => }/fips-migration.rst (86%) diff --git a/source/deployment-guide/server/containers/fips-stig.rst b/source/deployment-guide/server/containers/fips-stig.rst index 28546888aa2..83fe3f952d6 100644 --- a/source/deployment-guide/server/containers/fips-stig.rst +++ b/source/deployment-guide/server/containers/fips-stig.rst @@ -26,4 +26,4 @@ All application-level code uses only FIPS-approved algorithms, ensuring that cry .. note:: - The Mattermost FIPS image includes only prepackaged Boards, Playbooks, and Agents. Additional plugins can be added to the Mattermost FIPS image, but they will run in non-FIPS mode. - - Existing Docker or Kubernetes-based deployments can change the image from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. See :doc:`Migrate an existing deployment to FIPS-compliant containers ` for step-by-step instructions. + - Existing Docker or Kubernetes-based deployments can change the image from ``mattermost/mattermost-enterprise-edition`` to ``mattermost/mattermost-enterprise-fips-edition``. See :doc:`Migrate an existing deployment to FIPS-compliant images ` for step-by-step instructions. diff --git a/source/deployment-guide/server/deploy-containers.rst b/source/deployment-guide/server/deploy-containers.rst index f8425b6ecf1..a47a145f6e1 100644 --- a/source/deployment-guide/server/deploy-containers.rst +++ b/source/deployment-guide/server/deploy-containers.rst @@ -103,10 +103,3 @@ Additionally, consider: - Set up proper firewall rules to restrict unauthorized access and monitor traffic using tools like Fail2Ban or Wazuh. By following these steps, your Mattermost deployment using Docker containers will be accessible securely over HTTPS with efficient proxying through NGINX. Implementing the additional security recommendations will further protect your environment against evolving threats. - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Migrate an existing deployment to FIPS-compliant containers diff --git a/source/deployment-guide/server/containers/fips-migration.rst b/source/deployment-guide/server/fips-migration.rst similarity index 86% rename from source/deployment-guide/server/containers/fips-migration.rst rename to source/deployment-guide/server/fips-migration.rst index 1af72d33bf4..faa25f93e1c 100644 --- a/source/deployment-guide/server/containers/fips-migration.rst +++ b/source/deployment-guide/server/fips-migration.rst @@ -1,14 +1,14 @@ -Migrate an existing deployment to FIPS-compliant containers -============================================================ +Migrate an existing deployment to FIPS-compliant images +======================================================= -.. include:: ../../../_static/badges/entry-ent.rst +.. include:: ../../_static/badges/entry-ent.rst :start-after: :nosearch: From Mattermost v11, each release ships in two image variants: a standard Enterprise build (``mattermost/mattermost-enterprise-edition``) and a FIPS-compliant build (``mattermost/mattermost-enterprise-fips-edition``). Migrating an existing deployment to the FIPS image is primarily a matter of replacing the image and restarting Mattermost. No data migration is required, and rollback is symmetric. -This guide covers migrating an existing Mattermost Server deployment running on Docker or Kubernetes. FIPS images are only supported for Docker- and Kubernetes-based deployments; Linux package and tarball installations can't be migrated to FIPS in place. +This guide covers migrating an existing Mattermost Server deployment running on Docker or Kubernetes. Linux package and tarball installations have no FIPS-compliant equivalent. -Mattermost's FIPS offering also covers the Mattermost Operator and a self-hosted Push Proxy. Migrating those components is out of scope for this guide. +Mattermost's FIPS offering also covers the Mattermost Operator controller and a self-hosted Push Proxy. Migrating those components to their FIPS variants is out of scope for this guide. For background on what the FIPS build is and how it's constructed, see the **FIPS/STIG** tab on :doc:`Deploy Mattermost using Containers `. @@ -42,19 +42,19 @@ Migrate a Kubernetes deployment These steps assume your deployment is managed by the Mattermost Operator using a ``Mattermost`` custom resource. -In the steps below, replace ``[namespace]`` with the namespace your Mattermost installation runs in. If you omit ``-n [namespace]``, ``kubectl`` uses your current context's default namespace. +In the steps below, replace ```` with the namespace your Mattermost installation runs in. If you omit ``-n ``, ``kubectl`` uses your current context's default namespace. 1. Find the name of your Mattermost custom resource: .. code-block:: sh - kubectl -n [namespace] get mattermost + kubectl -n get mattermost 2. Edit the ``Mattermost`` custom resource to point at the FIPS image. You can edit the live resource directly: .. code-block:: sh - kubectl -n [namespace] edit mattermost [installation-name] + kubectl -n edit mattermost Or update your manifest file and re-apply it. @@ -70,19 +70,19 @@ In the steps below, replace ``[namespace]`` with the namespace your Mattermost i .. code-block:: sh - kubectl -n [namespace] apply -f .yaml + kubectl -n apply -f .yaml 5. Watch the Mattermost pods until the new ones reach ``Running`` and the old ones terminate: .. code-block:: sh - kubectl -n [namespace] get pods -w + kubectl -n get pods -w 6. Verify the running pods are using the FIPS image: .. code-block:: sh - kubectl -n [namespace] get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' + kubectl -n get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' Migrate a Docker or Docker Compose deployment --------------------------------------------- @@ -120,14 +120,14 @@ These steps are written for the official `Mattermost Docker deployment logs -f On Docker: diff --git a/source/deployment-guide/server/server-deployment-planning.rst b/source/deployment-guide/server/server-deployment-planning.rst index 2076afad08e..72792b88ca2 100644 --- a/source/deployment-guide/server/server-deployment-planning.rst +++ b/source/deployment-guide/server/server-deployment-planning.rst @@ -12,6 +12,7 @@ This section provides comprehensive guidance on deploying and managing your Matt Deploy with Kubernetes Deploy with Linux Deploy with Containers + Migrate to FIPS-compliant images Pre-authentication secrets Deployment Solution Programs @@ -19,6 +20,7 @@ This section provides comprehensive guidance on deploying and managing your Matt * :doc:`Deploy with Kubernetes ` - Scalable deployment on various Kubernetes platforms with high availability support. * :doc:`Deploy with Linux ` - Direct installation on Linux servers for full control over the deployment. * :doc:`Deploy with Containers ` - Docker-based deployment suitable for smaller installations. +* :doc:`Migrate to FIPS-compliant images ` - Switch an existing Docker or Kubernetes deployment to the FIPS-compliant Mattermost images. * :doc:`Pre-authentication secrets ` - Configure reverse proxy validation for mobile and desktop applications using pre-authentication headers. * :doc:`Deployment Solution Programs ` - Automated deployment tools and orchestration solutions. From 80dbf93d8e4b15b5f828adf2abdbd3fda4c9d0b8 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Wed, 15 Jul 2026 11:16:40 -0500 Subject: [PATCH 6/6] Clarify pod readiness check in FIPS Kubernetes migration steps Wait for pods to report Ready (not just Running) and scope pod queries with the app=mattermost label selector. Co-Authored-By: Claude Opus 4.8 (1M context) --- source/deployment-guide/server/fips-migration.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/deployment-guide/server/fips-migration.rst b/source/deployment-guide/server/fips-migration.rst index faa25f93e1c..fc30eae94a5 100644 --- a/source/deployment-guide/server/fips-migration.rst +++ b/source/deployment-guide/server/fips-migration.rst @@ -72,17 +72,17 @@ In the steps below, replace ```` with the namespace your Mattermost i kubectl -n apply -f .yaml -5. Watch the Mattermost pods until the new ones reach ``Running`` and the old ones terminate: +5. Watch the Mattermost pods until the new ones report ``Ready`` and the old ones terminate. A pod showing ``Running`` isn't necessarily serving traffic yet — wait until its ``READY`` column shows all containers ready (for example, ``1/1``): .. code-block:: sh - kubectl -n get pods -w + kubectl -n get pods -l app=mattermost -w 6. Verify the running pods are using the FIPS image: .. code-block:: sh - kubectl -n get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' + kubectl -n get pods -l app=mattermost -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}' Migrate a Docker or Docker Compose deployment ---------------------------------------------