Update elasticsearch-setup.rst for clustering#8757
Conversation
Note that I have no experience of deploying an Elasticsearch cluster, so these updates were created by Claude.
|
Newest code from mattermost has been published to preview environment for Git SHA 497d27c |
Updated after initial testing
|
Newest code from mattermost has been published to preview environment for Git SHA e3dc6a1 |
Further tweaks for accuracy
|
Newest code from mattermost has been published to preview environment for Git SHA 00f6390 |
Errors found in original doc
More fixes from original doc
|
Newest code from mattermost has been published to preview environment for Git SHA 19c27ba |
|
Newest code from mattermost has been published to preview environment for Git SHA 6db9c12 |
Adding more context for less experienced Linux admins
|
Newest code from mattermost has been published to preview environment for Git SHA 33ab58b |
Claude's an idiot!
|
Newest code from mattermost has been published to preview environment for Git SHA 0bc6082 |
Claude was hallucinating
|
Newest code from mattermost has been published to preview environment for Git SHA 2f3115c |
Added important detail about CA certificates for Elasticsearch v8
|
Newest code from mattermost has been published to preview environment for Git SHA 24dcb1b |
Final tweaks - ready for review
|
Newest code from mattermost has been published to preview environment for Git SHA 3cee54a |
esethna
left a comment
esethna
left a comment
There was a problem hiding this comment.
Thanks John! I made a few high level comments. A few other thoughts:
- Can you confirm you've run through the instructions as written for ES 8 end-to-end?
- Who can we get from the MM team to act as a technical SME for review?
|
@esethna I won't have the bandwidth to look into these comments for the foreseeable future, plus I no longer have the EC2 instances that I used at the time. Since it appears that these are mainly just doc changes, maybe you can make them directly yourself? |
|
This PR has been automatically labelled "stale" because it hasn't had recent activity. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
|
Newest code from mattermost has been published to preview environment for Git SHA 86c0cb2 |
📝 WalkthroughWalkthroughThe Elasticsearch setup guide was rewritten to cover single-node deployments, optional multi-node clusters, Elasticsearch 7.x and 8.x differences, operational validation, and Mattermost TLS and cluster configuration. ChangesElasticsearch scaling guide
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 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/scale/elasticsearch-setup.rst`:
- Around line 104-115: Update the Elasticsearch 8.x connection test in the setup
instructions to use curl with --cacert and the Elasticsearch CA certificate
instead of -k. If retaining an insecure fallback, explicitly label it as
temporary diagnostic-only and not suitable for validating production
connectivity.
- Around line 70-71: Update the Elasticsearch setup documentation around the
http.host and transport.host settings and the referenced port requirements to
document firewall restrictions: limit port 9300 to Elasticsearch nodes, and
limit port 9200 to Mattermost and authorized administrators, explicitly
excluding public internet access.
- Line 191: Add a prominent warning near the action.destructive_requires_name
setting explaining that, although Mattermost requires it for wildcard
operations, it permits destructive wildcard and _all index requests; instruct
users to enable it only on an authenticated, tightly restricted Elasticsearch
service. Apply the same warning at the additional occurrence of this setting.
- Around line 452-460: Update the CA certificate transfer instructions to use an
authorized administrative account with read access instead of remote root in the
scp command, then install the copied certificate locally with sudo install using
the required destination, owner, and file mode. Preserve the required ca.pem
filename and /opt/mattermost/data/elasticsearch/ destination.
- Around line 26-44: Update the Elasticsearch installation options referenced by
this guide to remove the Elasticsearch v9 link, keeping only versions covered by
the page’s verification and TLS instructions for 7.x and 8.x.
- Around line 458-460: Reword the note in the Elasticsearch setup documentation
to present ca.pem as an example rather than a required filename. State that the
configured relative CA path must match the certificate’s actual filename, while
retaining the example location and nearby cert.pem convention.
- Around line 288-302: Update the Elasticsearch 8.x instructions around the
additional-node configuration to direct administrators to remove
cluster.initial_master_nodes from every node after the initial bootstrap, rather
than keeping or updating it. Apply the same removal guidance to the
corresponding 7.x setup section, including any conflicting notes that suggest
retaining the setting.
- Around line 346-355: Update the “Disable memory swapping” section to either
rename it to accurately describe memory locking or, preferably, add instructions
for disabling swap at runtime with swapoff and persistently removing or
disabling swap entries in /etc/fstab. Keep the existing bootstrap.memory_lock
configuration for memory locking and clearly distinguish it from OS-level swap
removal.
- Around line 479-480: Update the Elasticsearch setup instructions to use a
dedicated service account with only the permissions required by Mattermost,
replacing the references to the elastic superuser in the Server Username and
Server Password steps. Ensure the surrounding guidance directs administrators to
create or provide those least-privilege credentials.
🪄 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: 9bf5011f-e4fd-4eef-8cdd-8d15e24dab52
📒 Files selected for processing (1)
source/administration-guide/scale/elasticsearch-setup.rst
| 3. Confirm Elasticsearch is working on the server. For Elasticsearch 7.x: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| curl localhost:9200 | ||
|
|
||
| 4. Get your network interface name by running the following command: | ||
| For Elasticsearch 8.x, TLS is enabled by default: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| sudo curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200 | ||
|
|
||
| .. note:: | ||
|
|
||
| Elasticsearch 8.x generates a password for the ``elastic`` superuser during installation. If you did not save it, reset it by running: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== file outline ==\n'
ast-grep outline source/administration-guide/scale/elasticsearch-setup.rst --view expanded || true
printf '\n== relevant lines ==\n'
nl -ba source/administration-guide/scale/elasticsearch-setup.rst | sed -n '1,140p'
printf '\n== version mentions ==\n'
rg -n "9\.x|8\.x|7\.x|Elasticsearch 9|Elasticsearch 8|Elasticsearch 7|v9|v8|v7" source/administration-guide/scale/elasticsearch-setup.rstRepository: mattermost/docs
Length of output: 249
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path("source/administration-guide/scale/elasticsearch-setup.rst")
text = p.read_text()
for i, line in enumerate(text.splitlines(), 1):
if any(x in line for x in ["9.x", "8.x", "7.x", "Elasticsearch 9", "Elasticsearch 8", "Elasticsearch 7", "v9", "v8", "v7"]):
print(f"{i}: {line}")
PYRepository: mattermost/docs
Length of output: 3456
Remove Elasticsearch v9 from the install option The install step links to Elasticsearch v9, but the rest of this page only covers 7.x and 8.x. Readers who pick v9 won’t have matching verification, clustering, or Mattermost TLS guidance. Either remove the v9 link or add a complete 9.x flow here.
🤖 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/scale/elasticsearch-setup.rst` around lines 26 -
44, Update the Elasticsearch installation options referenced by this guide to
remove the Elasticsearch v9 link, keeping only versions covered by the page’s
verification and TLS instructions for 7.x and 8.x.
| http.host: 0.0.0.0 | ||
| transport.host: 0.0.0.0 |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Document firewall scope before binding all interfaces
Binding HTTP and transport traffic to 0.0.0.0, while stating that all nodes need ports 9200 and 9300, encourages unnecessarily broad exposure. Port 9200 is the client HTTP API; port 9300 is inter-node transport. Specify that 9300 is restricted to Elasticsearch nodes, and 9200 is restricted to Mattermost and authorised administrators—not the public internet. (elastic.co)
Also applies to: 130-135
🤖 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/scale/elasticsearch-setup.rst` around lines 70 -
71, Update the Elasticsearch setup documentation around the http.host and
transport.host settings and the referenced port requirements to document
firewall restrictions: limit port 9300 to Elasticsearch nodes, and limit port
9200 to Mattermost and authorized administrators, explicitly excluding public
internet access.
Source: Coding guidelines
| 12. Test the connection from your Mattermost server to Elasticsearch by running the following command from the Mattermost server, replacing the example IP address with your Elasticsearch server's IP address. For Elasticsearch 7.x: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| curl 10.0.1.10:9200 | ||
|
|
||
| For Elasticsearch 8.x: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| curl -k -u elastic https://10.0.1.10:9200 | ||
|
|
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Do not use curl -k as the normal TLS check
-k disables certificate verification and normalises an insecure connection test. Use --cacert with the Elasticsearch CA certificate, or clearly label this as a temporary diagnostic-only fallback that must not be used to validate production connectivity. Elastic’s installation guidance uses --cacert. (elastic.co)
🤖 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/scale/elasticsearch-setup.rst` around lines 104 -
115, Update the Elasticsearch 8.x connection test in the setup instructions to
use curl with --cacert and the Elasticsearch CA certificate instead of -k. If
retaining an insecure fallback, explicitly label it as temporary diagnostic-only
and not suitable for validating production connectivity.
Source: Coding guidelines
| discovery.seed_hosts: ["10.0.1.10", "10.0.1.11", "10.0.1.12"] | ||
|
|
||
| # Mattermost requirement | ||
| action.destructive_requires_name: false |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Warn about the destructive wildcard setting
Mattermost requires action.destructive_requires_name: false for wildcard operations, but this also permits destructive wildcard or _all index requests. Add a prominent warning that this setting must only be used on an authenticated, tightly restricted Elasticsearch service. (docs.mattermost.com)
Also applies to: 286-286
🤖 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/scale/elasticsearch-setup.rst` at line 191, Add a
prominent warning near the action.destructive_requires_name setting explaining
that, although Mattermost requires it for wildcard operations, it permits
destructive wildcard and _all index requests; instruct users to enable it only
on an authenticated, tightly restricted Elasticsearch service. Apply the same
warning at the additional occurrence of this setting.
Source: Coding guidelines
| As with the first node, check for and update any existing ``cluster.initial_master_nodes`` entry rather than adding a duplicate. For additional nodes, this line can be removed entirely or updated to match the first node's value. | ||
|
|
||
| 10. Start Elasticsearch on the additional node: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| sudo systemctl daemon-reload | ||
| sudo systemctl enable elasticsearch.service | ||
| sudo systemctl start elasticsearch.service | ||
|
|
||
| 11. Repeat steps 6 through 10 for each remaining node, adjusting ``node.name`` and ``network.host`` accordingly. Generate a new enrollment token on the first node if the previous one has expired. | ||
|
|
||
| .. note:: | ||
|
|
||
| The ``cluster.initial_master_nodes`` setting is only used during the very first bootstrap of the cluster. Once the cluster is formed, this setting is ignored. Some administrators choose to remove it after initial cluster formation to prevent accidental re-bootstrapping. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant sections around the cited lines.
sed -n '250,360p' source/administration-guide/scale/elasticsearch-setup.rst
printf '\n--- search occurrences ---\n'
rg -n "cluster\.initial_master_nodes|bootstrap|enrollment token|initial master" source/administration-guide/scale/elasticsearch-setup.rstRepository: mattermost/docs
Length of output: 7558
🌐 Web query:
Elastic cluster.initial_master_nodes remove after cluster formed self-managed documentation
💡 Result:
For self-managed Elasticsearch clusters, the cluster.initial_master_nodes setting must be removed from the configuration of every node immediately after the cluster has successfully formed [1][2][3]. This setting is designed exclusively for the initial bootstrapping phase of a brand-new cluster [4][5][6]. Once the cluster is formed, the setting should never be configured again for that cluster, including during node restarts, full-cluster restarts, or when adding new nodes to an existing cluster [1][2][4]. The primary reasons for removing this setting are: 1. Data Loss Risk: If you leave cluster.initial_master_nodes in place after the cluster has formed, a future misconfiguration could cause the nodes to attempt to bootstrap a new, separate cluster alongside your existing one [1][2]. This can result in split-brain scenarios and potential data loss that may be impossible to recover from [1][2]. 2. Best Practices: After the initial bootstrap, discovery should be managed using discovery.seed_hosts or discovery.seed_providers, which are the correct mechanisms for ongoing node discovery and cluster maintenance [2][3]. If you inadvertently leave this setting in your configuration, you should shut down the nodes, remove the setting from the configuration files on all nodes, and then restart the cluster [1][2]. Do not configure this setting on master-ineligible nodes, nodes joining an existing cluster, or during routine maintenance activities [2][4][5].
Citations:
- 1: https://www.elastic.co/docs/deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster
- 2: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/modules-discovery-bootstrap-cluster.html
- 3: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/bootstrap-checks-discovery-configuration.html
- 4: https://www.elastic.co/docs/reference/elasticsearch/configuration-reference/discovery-cluster-formation-settings
- 5: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/modules-discovery-settings.html
- 6: https://discuss.elastic.co/t/discovery-seed-hosts-and-cluster-initial-master-nodes/330945
Remove cluster.initial_master_nodes after bootstrap
The 8.x steps should not suggest keeping or updating cluster.initial_master_nodes on additional nodes. Once the cluster has formed, remove it from every node; leaving it in place can lead to accidental re-bootstrap during future restarts or recovery. Apply the same fix to the 7.x section as well.
🤖 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/scale/elasticsearch-setup.rst` around lines 288 -
302, Update the Elasticsearch 8.x instructions around the additional-node
configuration to direct administrators to remove cluster.initial_master_nodes
from every node after the initial bootstrap, rather than keeping or updating it.
Apply the same removal guidance to the corresponding 7.x setup section,
including any conflicting notes that suggest retaining the setting.
| Disable memory swapping | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Memory swapping can cause Elasticsearch nodes to respond slowly or disconnect from the cluster entirely. It is strongly recommended to disable swapping on all cluster nodes. | ||
|
|
||
| To enable memory locking, add or uncomment the following line in ``elasticsearch.yml`` on each node: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| bootstrap.memory_lock: true |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '330,380p' source/administration-guide/scale/elasticsearch-setup.rst
printf '\n---\n'
rg -n "swap|memory_lock|bootstrap\.memory_lock" source/administration-guide/scale/elasticsearch-setup.rstRepository: mattermost/docs
Length of output: 2020
🌐 Web query:
Elastic Elasticsearch memory locking does not disable swap bootstrap.memory_lock LimitMEMLOCK swap documentation
💡 Result:
Elasticsearch's bootstrap.memory_lock setting and the LimitMEMLOCK configuration serve to lock the JVM heap in RAM using mlockall (on Linux/Unix) or VirtualLock (on Windows), but they do not inherently disable swapping for the operating system or for memory outside the JVM heap [1][2]. Key clarifications regarding your query: 1. Scope of Memory Locking: The bootstrap.memory_lock setting specifically attempts to lock the Elasticsearch process address space (primarily the JVM heap) into physical memory to prevent it from being swapped out [1][2]. It is not a system-wide instruction to disable swap [1]. 2. Off-Heap Memory and Swap: Even when bootstrap.memory_lock is successfully enabled (mlockall is active), some platforms may still swap off-heap memory [1][2]. Because of this, Elastic officially recommends disabling all swap files or partitions at the operating system level as the preferred method to prevent swapping [1][3]. Memory locking should be considered a secondary option for environments where disabling swap is not possible [4]. 3. Role of LimitMEMLOCK: The LimitMEMLOCK configuration in systemd is a necessary system-level permission that allows the Elasticsearch process to lock its memory [1][5]. If the process lacks this permission, the memory lock request will fail, and if the bootstrap.memory_lock setting is enabled, Elasticsearch will fail to start (or trigger bootstrap check errors) to protect the node from performance degradation caused by swapping [6][7]. Setting LimitMEMLOCK=infinity does not disable swap; it only provides the authorization for Elasticsearch to attempt memory locking [1][8]. In summary, memory locking is a measure to protect the heap, not a tool to disable OS swap [1][2]. To fully ensure that no memory is swapped, you must disable swap at the OS level [1].
Citations:
- 1: https://www.elastic.co/docs/deploy-manage/deploy/self-managed/setup-configuration-memory
- 2: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/setup-configuration-memory.html
- 3: https://discuss.elastic.co/t/use-of-bootstrap-memory-lock/368236
- 4: Set LimitMEMLOCK in systemd service file elastic/elasticsearch#22734
- 5: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/setting-system-settings.html
- 6: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/bootstrap-checks-memory-lock.html
- 7: https://www.elastic.co/docs/deploy-manage/deploy/self-managed/bootstrap-checks
- 8: https://www.elastic.co/docs/deploy-manage/deploy/self-managed/setting-system-settings
Rename this section or add the missing swap-off steps
bootstrap.memory_lock and LimitMEMLOCK lock Elasticsearch memory in RAM, but they do not disable OS swap. If the goal is to prevent swapping entirely, add the swapoff and persistent /etc/fstab steps; otherwise, rename the section to reflect that it only enables memory locking.
🤖 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/scale/elasticsearch-setup.rst` around lines 346 -
355, Update the “Disable memory swapping” section to either rename it to
accurately describe memory locking or, preferably, add instructions for
disabling swap at runtime with swapoff and persistently removing or disabling
swap entries in /etc/fstab. Keep the existing bootstrap.memory_lock
configuration for memory locking and clearly distinguish it from OS-level swap
removal.
| 3. Copy the CA certificate from the Elasticsearch node to the Mattermost server. Run this from the Mattermost server, replacing the example IP address with the private IP of any Elasticsearch 8.x node: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| sudo scp root@10.0.1.10:/etc/elasticsearch/certs/http_ca.crt /opt/mattermost/data/elasticsearch/ca.pem | ||
|
|
||
| .. note:: | ||
|
|
||
| The file must be named ``ca.pem`` and placed in ``/opt/mattermost/data/elasticsearch/``. Mattermost expects the certificate at this specific path. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Avoid requiring remote root SSH access for CA transfer
sudo scp root@... assumes that remote root login is enabled, which is commonly prohibited and conflicts with least privilege. Transfer the certificate using an authorised administrative account with read access, then install it locally with sudo install and the required owner and mode.
🤖 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/scale/elasticsearch-setup.rst` around lines 452 -
460, Update the CA certificate transfer instructions to use an authorized
administrative account with read access instead of remote root in the scp
command, then install the copied certificate locally with sudo install using the
required destination, owner, and file mode. Preserve the required ca.pem
filename and /opt/mattermost/data/elasticsearch/ destination.
Source: Coding guidelines
| .. note:: | ||
|
|
||
| The file must be named ``ca.pem`` and placed in ``/opt/mattermost/data/elasticsearch/``. Mattermost expects the certificate at this specific path. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Map the target file and nearby configuration docs.
git ls-files 'source/administration-guide/scale/elasticsearch-setup.rst' \
'source/administration-guide/configure/environment-configuration-settings.rst' \
'source/administration-guide/configure/environment-configuration-settings.md' \
'docs/administration-guide/configure/environment-configuration-settings.md' \
'docs/administration-guide/configure/environment-configuration-settings.rst' \
'source/**/environment-configuration-settings.*' \
| sed 's#^`#FILE`: #'
# Show the relevant section around the cited lines.
echo '--- elasticsearch-setup.rst excerpt ---'
sed -n '440,475p' source/administration-guide/scale/elasticsearch-setup.rst
# Find mentions of ca.pem / cert.pem / CA path / relative path in nearby docs.
echo '--- search results ---'
rg -n --hidden --glob 'source/**/*.rst' --glob 'source/**/*.md' \
'(ca\.pem|cert\.pem|CA path|relative path|certificate at this specific path|elasticsearch.*cert)' \
source/administration-guide | sed -n '1,200p'Repository: mattermost/docs
Length of output: 4480
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the relevant config doc if present.
fd -a 'environment-configuration-settings.(rst|md)$' source docs . 2>/dev/null | sed -n '1,50p'Repository: mattermost/docs
Length of output: 345
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1316,1336p' source/administration-guide/configure/environment-configuration-settings.rstRepository: mattermost/docs
Length of output: 1632
Use ca.pem as an example, not a requirement
The file must be named ca.pem is too strong here. Mattermost takes a configurable CA path, and the nearby settings doc uses cert.pem as the example. Reword this to “in this example, name the file ca.pem” and note that the configured relative path must match the actual filename.
🤖 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/scale/elasticsearch-setup.rst` around lines 458 -
460, Reword the note in the Elasticsearch setup documentation to present ca.pem
as an example rather than a required filename. State that the configured
relative CA path must match the certificate’s actual filename, while retaining
the example location and nearby cert.pem convention.
| 3. Set the **Server Username** to ``elastic``. | ||
| 4. Set the **Server Password** to the ``elastic`` superuser password from your Elasticsearch installation. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- elasticsearch-setup.rst around lines 450-500 ---'
sed -n '450,500p' source/administration-guide/scale/elasticsearch-setup.rst
printf '%s\n' '\n--- search for Server Username / elastic references in Elasticsearch docs ---'
rg -n "Server Username|elastic superuser|\\belastic\\b|service account|least-privilege" source/administration-guide/scale source -g '*.rst' -g '*.md'
printf '%s\n' '\n--- enterprise-search doc around any Elasticsearch auth guidance ---'
fd -a 'enterprise-search.rst' source
fd -a 'enterprise-search*.rst' sourceRepository: mattermost/docs
Length of output: 24608
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- enterprise-search.rst around lines 160-220 ---'
sed -n '160,220p' source/administration-guide/scale/enterprise-search.rst
printf '%s\n' '\n--- common-configure-mattermost-for-enterprise-search.rst ---'
cat -n source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst
printf '%s\n' '\n--- elasticsearch-setup.rst around lines 1-140 and 200-250 ---'
sed -n '1,140p' source/administration-guide/scale/elasticsearch-setup.rst
printf '%s\n' '\n---'
sed -n '200,250p' source/administration-guide/scale/elasticsearch-setup.rstRepository: mattermost/docs
Length of output: 17562
Use a dedicated Elasticsearch service account here
elastic is a superuser, so this should use a dedicated account with only the Elasticsearch permissions Mattermost needs. That keeps the admin blast radius small if these credentials are exposed.
🤖 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/scale/elasticsearch-setup.rst` around lines 479 -
480, Update the Elasticsearch setup instructions to use a dedicated service
account with only the permissions required by Mattermost, replacing the
references to the elastic superuser in the Server Username and Server Password
steps. Ensure the surrounding guidance directs administrators to create or
provide those least-privilege credentials.
Source: Coding guidelines
deprecation changes to the docs are not part of this PRs scope
|
All these comments from CodeRabbit require a complete rebuild of the ES environment to test. We'll need to find somebody with the bandwidth to do this. |
|
Closing, as this isn't something Mattermost should be documenting, as we don't supply Elasticsearch! |
3 participants
Note that I have no experience of deploying an Elasticsearch cluster, so these updates were created by Claude.
Summary
Ticket Link