MM-68718: Document Azure Blob Storage as a file storage backend#8976
Open
agarciamontoro wants to merge 8 commits into
Open
MM-68718: Document Azure Blob Storage as a file storage backend#8976agarciamontoro wants to merge 8 commits into
agarciamontoro wants to merge 8 commits into
Conversation
Adds Azure Blob Storage to the File storage system reference: a new azureblob driver-name option and individual entries for the FileSettings.AzureStorageAccount, AzureContainer, AzurePathPrefix, AzureAccessKey, AzureEndpoint, AzureSSL, and AzureRequestTimeoutMilliseconds settings. Extends the dedicated export filestore list with the matching Export* variants. Calls out the restart-required behaviour when changing file storage settings so admins know Save in System Console isn't enough on its own. ------ AI assisted commit
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA 08315ba |
agarciamontoro
changed the title
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA 71cd497 |
Folds the full prereqs, Azure portal/CLI provisioning, System Console walk-through, Test Connection semantics, restart-required warning, verification, optional export backend, and troubleshooting sections into a dedicated configure/azure-blob-storage page. Wires the new page into the configuration-settings toctree and bullet list, and adds a seealso link from the File storage section of environment-configuration-settings so admins can find it from the reference page. ------ AI assisted commit
agarciamontoro
force-pushed
the
MM-67096-azure-blob-storage-docs
branch
from
71cd497 to
eaa2e51
Compare
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA eaa2e51 |
Combs7th
added
1: Dev Review
Contributor
|
Thank you for the docs, @agarciamontoro! Is there a dev who you can recommend we tag to be the technical reviewer for this one? |
Member
Author
|
Hey, @Combs7th, I'll assign someone as soon as this is ready for review. For now, it's just an info dump of everything in progress, I'm still waiting for some PRs to be merged. Will move the PR to ready for review and assign a dev when it's done, thanks! |
Member
Author
|
This will ship in v11.9, btw, not in v11.8 |
Adds a Migrate existing files from Amazon S3 section to the Azure Blob Storage walk-through. Covers the recommended trickle-then-cutover pattern (long rclone sync, short AzCopy maintenance window), the prerequisites for the migration host, phase-by-phase commands, verification queries (object count parity, sha256 spot-check), the rollback path, and caveats (S3 versioning, sync vs copy, prefix rewrites, cross-region cost, Storage Mover preview status). Updates the migration note under step 4 and the troubleshooting entry for missing pre-cutover files to cross-reference the new section. ------ AI assisted commit
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA 9c68289 |
Adds the AzureCloud setting documentation (commercial/government/custom) to both the environment configuration reference and the Azure walkthrough, rewrites the AzureEndpoint entry to reflect its new role as the full Blob service URL valid only when AzureCloud is custom, and removes the stale note that said sovereign clouds aren't configured through the endpoint override. Adds ExportAzureCloud to the dedicated export filestore key list. ------ AI assisted commit
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA b14dc0d |
Restructures Step 3 of the Azure Blob Storage walk-through to cover both shared-key and the new default_credential authentication mode. The default_credential subsection walks an admin through picking the identity source that matches the host (managed identity on Azure VM/App Service/AKS, workload identity, service principal, az login) and granting Storage Blob Data Contributor on the storage account. Updates Step 4 to describe the new "Azure authentication" dropdown in the System Console, including the conditional visibility of the Azure Storage account key field. Adds AuthorizationPermissionMismatch to the troubleshooting table and documents the propagation delay that follows a fresh role assignment. Adds FileSettings.AzureAuthMode to the environment-configuration reference and to the ExportAzure* list under the dedicated export filestore section. ------ AI assisted commit
This was referenced May 26, 2026
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA ad4a3f4 |
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA d7490b2 |
Contributor
📝 WalkthroughWalkthroughThis pull request adds comprehensive documentation for Azure Blob Storage support in Mattermost, including a new configuration guide and corresponding environment/configuration setting references for the ChangesAzure Blob Storage Documentation Support
🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
source/administration-guide/configure/azure-blob-storage.rst (1)
12-14: ⚡ Quick winAdd a quick resource-creation/verification pointer in prerequisites.
For novice admins, requiring a pre-created storage account/container without a direct creation/verification step can stall setup. Add one short line that tells them where to create or how to confirm both exist before continuing.
As per coding guidelines, "List prerequisites clearly at the top of documentation sections" and "Flag any step that assumes knowledge a novice IT administrator with 1-2 years of experience likely doesn't have."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@source/administration-guide/configure/azure-blob-storage.rst` around lines 12 - 14, Update the prerequisites bullet list in source/administration-guide/configure/azure-blob-storage.rst to add a single-line pointer that tells novices how to create or verify the storage account and container (e.g., "Create or verify a storage account and container via the Azure portal or az storage account/container create --help") so readers know where to perform those actions before proceeding; modify the existing bullets (the ones listing "An Azure subscription..." and the Azure portal/CLI note) to include that brief creation/verification pointer and ensure the wording is concise and actionable for admins with 1–2 years' experience.source/administration-guide/configure/environment-configuration-settings.rst (1)
2038-2040: ⚡ Quick winUse an
importantadmonition for the restart prerequisite.This is a required post-change action for correctness, not optional context. Please promote this from
.. note::to.. important::.Suggested minimal diff
-.. note:: +.. important:: After saving a new file storage system, restart every Mattermost server in the deployment for the change to take effect. The file storage backend is initialized at startup and isn't rebuilt automatically when ``FileSettings`` change at runtime.As per coding guidelines, “Use
importantadmonition for prerequisites, constraints, or high-impact information that materially affects correctness, supportability, compliance, or success.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@source/administration-guide/configure/environment-configuration-settings.rst` around lines 2038 - 2040, Change the RST admonition directive from ".. note::" to ".. important::" for the paragraph that begins "After saving a new file storage system, restart every Mattermost server..." so the restart prerequisite is presented as high-impact/required information; update the directive header and ensure indentation and content remain unchanged under the ".. important::" block (refer to the existing ".. note::" and the "FileSettings" mention to locate the exact stanza).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@source/administration-guide/configure/azure-blob-storage.rst`:
- Around line 141-144: Replace the ".. note::" admonition that begins the
paragraph about switching the file driver (the block that warns "Switching the
file driver does **not** migrate existing files..." and mentions azcopy and S3
migration) with a ".. warning::" admonition so the same text is surfaced as a
warning; keep the existing content and formatting unchanged except for the
admonition directive change to ensure this migration caveat is prominently
flagged.
- Around line 47-50: Replace the low-severity admonition with a warning: change
the directive ".. note::" to ".. warning::" for the shared-key guidance (the
block starting with the shared key rotation text) so the risk of account
compromise is presented at the correct severity; ensure the admonition header
and indentation remain valid for the existing paragraph content.
In
`@source/administration-guide/configure/environment-configuration-settings.rst`:
- Around line 2661-2663: The guidance that “Allows insecure connections... set
to false when pointing at a local emulator without TLS” is missing a security
warning; update the paragraph for the Azure TLS-disabling option (the setting
described as “false” / disabling TLS) to include a prominent warning admonition
(use a “warning” admonition block) that this configuration is for local
development/testing only, must never be used in production or over untrusted
networks, and that production deployments must use TLS, secure credentials, and
network controls; keep the existing note about local emulators but prepend the
explicit test-only/never-production warning and a brief remediation line
recommending enabling TLS and environment-specific configuration.
---
Nitpick comments:
In `@source/administration-guide/configure/azure-blob-storage.rst`:
- Around line 12-14: Update the prerequisites bullet list in
source/administration-guide/configure/azure-blob-storage.rst to add a
single-line pointer that tells novices how to create or verify the storage
account and container (e.g., "Create or verify a storage account and container
via the Azure portal or az storage account/container create --help") so readers
know where to perform those actions before proceeding; modify the existing
bullets (the ones listing "An Azure subscription..." and the Azure portal/CLI
note) to include that brief creation/verification pointer and ensure the wording
is concise and actionable for admins with 1–2 years' experience.
In
`@source/administration-guide/configure/environment-configuration-settings.rst`:
- Around line 2038-2040: Change the RST admonition directive from ".. note::" to
".. important::" for the paragraph that begins "After saving a new file storage
system, restart every Mattermost server..." so the restart prerequisite is
presented as high-impact/required information; update the directive header and
ensure indentation and content remain unchanged under the ".. important::" block
(refer to the existing ".. note::" and the "FileSettings" mention to locate the
exact stanza).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: d664def8-441e-4cd3-83b2-9e09e0082658
📒 Files selected for processing (2)
source/administration-guide/configure/azure-blob-storage.rstsource/administration-guide/configure/environment-configuration-settings.rst
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Contributor
|
Newest code from mattermost has been published to preview environment for Git SHA 93b6d5d |
lieut-data
reviewed
Jun 1, 2026
Member
lieut-data
left a comment
lieut-data
left a comment
There was a problem hiding this comment.
This is great! A few comments for discussion below.
| Mattermost supports two ways for the server to authenticate to Azure. Pick the one that fits how the server runs: | ||
|
|
||
| - **Shared key**: the server signs each request with the :ref:`Storage Account access key <administration-guide/configure/environment-configuration-settings:azure storage account key>`. Works anywhere Mattermost runs (on-premises, non-Azure cloud, local development) because it does not depend on the host having an Azure identity. The trade-off is that the key is a long-lived secret stored in ``config.json``. | ||
| - **Default credential (Microsoft Entra ID)**: the server obtains a token from Microsoft Entra ID and signs requests with it. No long-lived secret in Mattermost configuration. This is the recommended mode for deployments running on Azure, where the host environment already provides an identity (managed identity on Azure VM / App Service / AKS, workload identity for federated workloads, or a service principal). |
Member
There was a problem hiding this comment.
Out of curiosity, does the Microsoft Entra ID ever rotate while the server is still running? That is, could our ability to read/write disappear mysteriously after some timeout?
|
|
||
| .. note:: | ||
|
|
||
| Treat the shared key as a secret -- anyone with it has full access to the account. Azure provides two keys so you can rotate without downtime: update Mattermost to ``key2``, regenerate ``key1``, then swap on the next rotation cycle. Plan a rotation cadence that matches your organisation's policy. |
Member
There was a problem hiding this comment.
"full access to the account" -- is there a way to generate a shared key with access limited to read/writing the specific resource group? Or is that what we mean by the account?
| #. ``ManagedIdentityCredential`` -- the platform-provided managed identity. | ||
| #. ``AzureCLICredential`` -- the signed-in ``az`` session, useful for local development. | ||
|
|
||
| Whichever identity the SDK selects, **that** identity needs **Storage Blob Data Contributor** (or a custom role with the equivalent ``read/write/list/delete`` data-plane actions) on the storage account or container. Without it, ``TestConnection`` returns ``AuthorizationPermissionMismatch``. |
Member
There was a problem hiding this comment.
If this process fails on server startup, do we (correctly) refuse to start the server or signal that this has failed in some other, catastrophic way? (Maybe all reads/writes error out?)
|
|
||
| .. warning:: | ||
|
|
||
| **Restart required.** The Mattermost server caches the file storage backend at startup and does not re-create it when the file storage configuration changes. After saving, restart every Mattermost server in the deployment (``systemctl restart mattermost``, recycle the container, or roll the deployment in your cluster) for the new driver to take effect. **Test Connection** works before the restart because it builds a temporary backend from the submitted form values. |
Member
There was a problem hiding this comment.
As an aside, I've always wondered if we should support an /api/v4/restart endpoint to automate this...
| .. warning:: | ||
|
|
||
| Switching the file driver does **not** migrate existing files. If you are moving an existing deployment from Amazon S3, see `Migrate existing files from Amazon S3`_ below before changing the driver. For migrations from local disk, copy the directory contents into the Azure container using ``azcopy`` (`docs <https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10>`__). In either case, files uploaded before the switch are unreachable once the driver changes unless they are present at the same key in the destination. | ||
| Step 3: Verify |
| (Optional) Configure the export backend | ||
| --------------------------------------- | ||
|
|
||
| Compliance and data exports can be stored separately from regular file uploads. The **File Storage (Exports)** section directly below **File Storage** in the System Console mirrors the fields above and accepts the same Azure credentials. Customers typically point exports at a different container (or a different account) so the export retention policy can differ from regular uploads. |
Member
There was a problem hiding this comment.
In theory, could I store one on AWS and the other on Azure?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the new Azure Blob Storage filestore backend. Two layers:
Reference (
source/administration-guide/configure/environment-configuration-settings.rst):azureblobdriver-name option.ExportAzure*keys.seealsopointer from the File storage section to the walk-through page below.Walk-through (
source/administration-guide/configure/azure-blob-storage.rst, new):Ticket Link
Fixes https://mattermost.atlassian.net/browse/MM-68718