docs: update blue green update document #1081
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1081 +/- ##
==========================================
- Coverage 76.27% 76.04% -0.23%
==========================================
Files 69 69
Lines 6250 6250
==========================================
- Hits 4767 4753 -14
- Misses 1245 1255 +10
- Partials 238 242 +4 ☔ View full report in Codecov by Sentry. |
Rory-Z
force-pushed
the
docs/update-blue-grees
branch
from
55ba0e0
to
3bbf6ef
Compare
WalkthroughThe pull request involves updates to the documentation for the blue-green deployment strategy of the EMQX cluster. Changes include enhanced clarity in the task objectives, background, and solution sections, with a focus on creating new Pods instead of clusters. The upgrade process has been reformatted for readability, and state diagrams have replaced previous diagrams to illustrate the upgrade steps. Configuration examples have been updated, and a new monitoring section has been added to provide tools for tracking connection metrics during the upgrade. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant EMQX Cluster
participant New Pods
participant Old Pods
User->>EMQX Cluster: Initiate Upgrade
EMQX Cluster->>New Pods: Create New Pods
New Pods->>EMQX Cluster: Join Existing Cluster
EMQX Cluster->>User: Redirect Traffic to New Pods
User->>Old Pods: Gradually Remove Old Pods
Old Pods->>EMQX Cluster: Evacuate Connections
EMQX Cluster->>User: Upgrade Complete
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (5)
docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md (2)
28-88: LGTM: Improved solution section with state diagramThe solution section now provides a clearer outline of the blue-green upgrade process. The addition of the state diagram significantly enhances the understanding of the upgrade steps.
Consider replacing hard tabs with spaces in the Mermaid diagram code for consistent formatting across different editors and platforms. For example:
- state Step1 { + state Step1 {🧰 Tools
🪛 Markdownlint
38-38: Column: 1
Hard tabs(MD010, no-hard-tabs)
85-85: Column: 1
Hard tabs(MD010, no-hard-tabs)
Line range hint
224-285: LGTM: New monitoring section with helpful commandsThe new section on monitoring the upgrade process is a valuable addition. It provides clear commands for checking the status of the EMQX cluster and node evacuation process, along with detailed explanations of the output fields.
Consider adding a brief explanation of how users can interpret the
statefield in the node evacuation status output. For example:`state`: 节点疏散阶段。 + 可能的值包括 "evacuating"（正在疏散）, "waiting_takeover"（等待接管）等，表示当前疏散的进度。This addition would help users better understand the evacuation process.
docs/en_US/tasks/configure-emqx-blueGreenUpdate.md (3)
29-89: LGTM: Enhanced solution explanation with visual representationThe expanded solution section with step-by-step explanation and the addition of the mermaid diagram greatly improve the document's clarity. The visual representation of the upgrade process is particularly helpful for understanding the complex steps involved.
Consider applying these minor formatting improvements to the mermaid code block:
- Remove the extra blank lines (lines 39, 59, 67, 74, 81) within the mermaid diagram to maintain consistency.
- Align the indentation of the state definitions (e.g., lines 40-48, 56-86) to improve readability.
🧰 Tools
🪛 Markdownlint
39-39: Column: 1
Hard tabs(MD010, no-hard-tabs)
86-86: Column: 1
Hard tabs(MD010, no-hard-tabs)
Line range hint
91-224: LGTM: Comprehensive configuration examples and explanationsThe configuration update strategy section provides clear YAML examples for both
apps.emqx.io/v2beta1andapps.emqx.io/v1beta4versions, along with helpful explanations of the parameters. The use of tabs to separate different versions improves readability.In the deployment command for the v2beta1 version (line 125), consider removing the colon after "as" to improve readability:
-Save the above content as: `emqx-update.yaml`, execute the following command to deploy EMQX, in this example, just deploy EMQX core node cluster without replicant node: +Save the above content as `emqx-update.yaml`, execute the following command to deploy EMQX, in this example, just deploy EMQX core node cluster without replicant node:🧰 Tools
🪛 LanguageTool
[uncategorized] ~123-~123: Loose punctuation mark.
Context: ...n (unit: count/second)。sessEvictRate: MQTT Session evacuation rate, only supp...(UNLIKELY_OPENING_PUNCTUATION)
[typographical] ~125-~125: Do not use a colon (:) before a series that is introduced by a preposition (‘as’). Remove the colon or add a noun or a noun phrase after the preposition.
Context: ... count/second)。 Save the above content as:emqx-update.yaml, execute the followi...(RP_COLON)
Line range hint
225-290: LGTM: Well-documented upgrade process with clear examplesThe upgrade process section provides comprehensive instructions for connecting to the EMQX cluster, triggering the upgrade, and monitoring its progress. The inclusion of JSON output examples is particularly helpful for understanding the status of nodes and the evacuation process.
In the code block for checking node evacuations status (lines 244-268), consider removing the extra blank line at the beginning to maintain consistency with other code blocks in the document:
- - $ kubectl get emqx emqx-ee -o json | jq ".status.nodeEvacuationsStatus" +$ kubectl get emqx emqx-ee -o json | jq ".status.nodeEvacuationsStatus"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
- docs/en_US/tasks/configure-emqx-blueGreenUpdate.md (3 hunks)
- docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md (3 hunks)
🧰 Additional context used
🪛 Markdownlint
docs/en_US/tasks/configure-emqx-blueGreenUpdate.md
39-39: Column: 1
Hard tabs(MD010, no-hard-tabs)
86-86: Column: 1
Hard tabs(MD010, no-hard-tabs)
docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md
38-38: Column: 1
Hard tabs(MD010, no-hard-tabs)
85-85: Column: 1
Hard tabs(MD010, no-hard-tabs)
🪛 LanguageTool
docs/en_US/tasks/configure-emqx-blueGreenUpdate.md
[typographical] ~125-~125: Do not use a colon (:) before a series that is introduced by a preposition (‘as’). Remove the colon or add a noun or a noun phrase after the preposition.
Context: ... count/second)。 Save the above content as:emqx-update.yaml, execute the followi...(RP_COLON)
🔇 Additional comments (5)
docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md (3)
Line range hint
1-27: LGTM: Improved introduction and background sectionsThe enhanced introduction and expanded background section provide a clearer context for the blue-green deployment strategy. The content is well-structured and informative, effectively highlighting the limitations of traditional rolling updates.
🧰 Tools
🪛 Markdownlint
38-38: Column: 1
Hard tabs(MD010, no-hard-tabs)
85-85: Column: 1
Hard tabs(MD010, no-hard-tabs)
Line range hint
89-223: LGTM: Updated configuration examplesThe configuration examples for both
apps.emqx.io/v2beta1 EMQXandapps.emqx.io/v1beta4 EmqxEnterprisehave been clearly updated. The examples now include parameters for managing connection and session eviction rates, which are crucial for the blue-green update strategy. The use of tabs for different EMQX versions improves readability and user experience.
Line range hint
286-301: LGTM: Informative Grafana monitoring sectionThe Grafana monitoring section effectively illustrates the benefits of the blue-green deployment strategy. The included graph and its explanation clearly demonstrate how the upgrade process maintains a stable connection count, highlighting the smooth transition and minimal impact on the service.
🧰 Tools
🪛 Markdownlint
38-38: Column: 1
Hard tabs(MD010, no-hard-tabs)
85-85: Column: 1
Hard tabs(MD010, no-hard-tabs)
docs/en_US/tasks/configure-emqx-blueGreenUpdate.md (2)
Line range hint
1-28: LGTM: Improved clarity in introduction and backgroundThe updates to the task objective and background sections provide a clearer context for the blue-green deployment strategy. The explanation of the problems with traditional rolling updates is well-articulated and helps readers understand the need for this approach.
🧰 Tools
🪛 Markdownlint
39-39: Column: 1
Hard tabs(MD010, no-hard-tabs)
86-86: Column: 1
Hard tabs(MD010, no-hard-tabs)
92-92: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
Line range hint
293-309: LGTM: Valuable addition of Grafana Monitoring sectionThe new Grafana Monitoring section is a valuable addition to the document. It provides visual insights into the upgrade process through a monitoring graph and clear explanations of the graph components. This section effectively demonstrates the smooth transition of connections during the blue-green deployment, reinforcing the benefits of this upgrade strategy.
🧰 Tools
🪛 Markdownlint
39-39: Column: 1
Hard tabs(MD010, no-hard-tabs)
86-86: Column: 1
Hard tabs(MD010, no-hard-tabs)
92-92: Punctuation: '.'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
Rory-Z
force-pushed
the
docs/update-blue-grees
branch
from
3bbf6ef
to
e41816a
Compare
Signed-off-by: Rory Z <[email protected]>
Rory-Z
force-pushed
the
docs/update-blue-grees
branch
from
e41816a
to
d43a316
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (8)
docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md (2)
28-88: LGTM with minor formatting suggestionsThe solution section clearly outlines the steps for blue-green deployment, and the mermaid diagram provides an excellent visual representation of the process. However, there are some minor formatting issues in the mermaid diagram.
Consider applying the following changes to improve the formatting:
- Remove the hard tabs at the beginning of lines 38 and 85.
- Ensure consistent indentation throughout the mermaid diagram for better readability.
Example:
- state Step1 { + state Step1 { [*] --> CreateNewPods CreateNewPods: Create new pods CreateNewPods --> NewPodsJoinTheCluster NewPodsJoinTheCluster: New pods join the cluster NewPodsJoinTheCluster --> WaitNewPodsReady WaitNewPodsReady: Wait new pods ready WaitNewPodsReady --> LBServiceSelectNewPods LBServiceSelectNewPods: Redirect the Service to the new Pods and remove the old Pods from the Service LBServiceSelectNewPods --> [*] }🧰 Tools
🪛 Markdownlint
38-38: Column: 1
Hard tabs(MD010, no-hard-tabs)
85-85: Column: 1
Hard tabs(MD010, no-hard-tabs)
Line range hint
224-293: LGTM with minor formatting suggestionsThe upgrade process section provides clear steps and example commands for upgrading the EMQX cluster. The inclusion of commands to check cluster status and node evacuation status is particularly helpful.
Consider applying the following changes to improve the formatting of the code blocks:
- Add language identifiers to the code blocks for better syntax highlighting. For example:
- ``` + ```bash kubectl get emqx emqx-ee -o json | jq '.status.coreNodesStatus' { "currentReplicas": 2, "currentRevision": "54fc496fb4", "readyReplicas": 4, "replicas": 2, "updateReplicas": 2, "updateRevision": "5d87d4c6bd" }2. Ensure consistent indentation for the JSON output in the code blocks. </blockquote></details> <details> <summary>docs/en_US/tasks/configure-emqx-blueGreenUpdate.md (6)</summary><blockquote> Line range hint `1-11`: **LGTM! Clear introduction and task objective.** The updated introduction and task objective provide a clear context for the document. The added tip about supported versions is helpful for users. Consider adding a brief explanation of what blue-green deployment is for readers who might be unfamiliar with the concept. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> 39-39: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 86-86: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 92-92: Punctuation: '.' Trailing punctuation in heading (MD026, no-trailing-punctuation) </blockquote></details> </details> --- Line range hint `23-89`: **Great improvement in the solution section.** The updated solution section provides a clear and detailed explanation of the blue-green deployment process. The breakdown of steps and the addition of the state diagram significantly enhance the reader's understanding of the upgrade process. Consider adding a brief legend or explanation for the state diagram to help readers unfamiliar with mermaid syntax better understand the flow. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> 39-39: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 86-86: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 92-92: Punctuation: '.' Trailing punctuation in heading (MD026, no-trailing-punctuation) </blockquote></details> </details> --- Line range hint `91-225`: **Comprehensive configuration update strategy section.** The inclusion of specific YAML configurations for both `apps.emqx.io/v2beta1` and `apps.emqx.io/v1beta4` versions, along with detailed parameter explanations, greatly enhances the usability of this document. The updated deployment and status-checking commands are also helpful. Consider adding a brief note about the differences between the two versions (`v2beta1` and `v1beta4`) to help users choose the appropriate configuration for their needs. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 LanguageTool</summary><blockquote> [uncategorized] ~123-~123: Loose punctuation mark. Context: ...n (unit: count/second)。 `sessEvictRate`: MQTT Session evacuation rate, only supp... (UNLIKELY_OPENING_PUNCTUATION) --- [typographical] ~125-~125: Do not use a colon (:) before a series that is introduced by a preposition (‘as’). Remove the colon or add a noun or a noun phrase after the preposition. Context: ... count/second)。 Save the above content as: `emqx-update.yaml`, execute the followi... (RP_COLON) </blockquote></details> </details> --- Line range hint `225-301`: **Clear and detailed upgrade process instructions.** The step-by-step instructions for upgrading the EMQX cluster, including commands for triggering the upgrade, checking node status, and monitoring the evacuation process, are very helpful. The added explanation of node evacuation status parameters enhances understanding of the process. Consider adding a troubleshooting subsection or common issues that users might encounter during the upgrade process, along with their solutions. --- Line range hint `304-322`: **Excellent addition of the Grafana Monitoring section.** The inclusion of a monitoring section with a graph illustrating connection metrics during the upgrade process is a valuable addition. It provides users with a visual representation of the upgrade's impact on connections and helps demonstrate the effectiveness of the blue-green deployment strategy. Consider adding information on how users can set up similar monitoring for their own deployments, including any necessary Grafana dashboard configurations or Prometheus metrics to collect. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> 39-39: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 86-86: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 92-92: Punctuation: '.' Trailing punctuation in heading (MD026, no-trailing-punctuation) </blockquote></details> </details> --- `125-125`: **Minor typographical correction needed.** Remove the colon after "as" in the following sentence: "Save the above content as: `emqx-update.yaml`, execute the following command to deploy EMQX" Suggested correction: "Save the above content as `emqx-update.yaml`, execute the following command to deploy EMQX" <details> <summary>🧰 Tools</summary> <details> <summary>🪛 LanguageTool</summary><blockquote> [typographical] ~125-~125: Do not use a colon (:) before a series that is introduced by a preposition (‘as’). Remove the colon or add a noun or a noun phrase after the preposition. Context: ... count/second)。 Save the above content as: `emqx-update.yaml`, execute the followi... (RP_COLON) </blockquote></details> </details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: CodeRabbit UI** **Review profile: CHILL** <details> <summary>📥 Commits</summary> Files that changed from the base of the PR and between 3bbf6ef9cffa8258b26b7cca0692024c1f246093 and d43a3165f350859088e7c175a6ae2a73c60f1356. </details> <details> <summary>📒 Files selected for processing (2)</summary> * docs/en_US/tasks/configure-emqx-blueGreenUpdate.md (3 hunks) * docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md (3 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> <details> <summary>docs/en_US/tasks/configure-emqx-blueGreenUpdate.md</summary><blockquote> 39-39: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 86-86: Column: 1 Hard tabs (MD010, no-hard-tabs) </blockquote></details> <details> <summary>docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md</summary><blockquote> 38-38: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 85-85: Column: 1 Hard tabs (MD010, no-hard-tabs) </blockquote></details> </blockquote></details> <details> <summary>🪛 LanguageTool</summary><blockquote> <details> <summary>docs/en_US/tasks/configure-emqx-blueGreenUpdate.md</summary><blockquote> [typographical] ~125-~125: Do not use a colon (:) before a series that is introduced by a preposition (‘as’). Remove the colon or add a noun or a noun phrase after the preposition. Context: ... count/second)。 Save the above content as: `emqx-update.yaml`, execute the followi... (RP_COLON) </blockquote></details> </blockquote></details> </details> <details> <summary>🔇 Additional comments (4)</summary><blockquote> <details> <summary>docs/zh_CN/tasks/configure-emqx-blueGreenUpdate.md (3)</summary><blockquote> Line range hint `1-27`: **LGTM: Clear introduction and background** The introduction and background sections provide a clear context for the blue-green deployment strategy, explaining its purpose and the limitations of traditional rolling updates. This sets a good foundation for the rest of the document. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> 38-38: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 85-85: Column: 1 Hard tabs (MD010, no-hard-tabs) </blockquote></details> </details> --- Line range hint `89-223`: **LGTM: Comprehensive configuration examples** The configuration examples for both `apps.emqx.io/v2beta1 EMQX` and `apps.emqx.io/v1beta4 EmqxEnterprise` are well-structured and provide clear explanations of the configuration parameters. This section offers valuable guidance for users implementing blue-green deployments. --- Line range hint `294-310`: **LGTM: Informative Grafana monitoring section** The Grafana monitoring section provides a valuable visualization of the connection metrics during the upgrade process. The explanation of the graph and its implications effectively demonstrates the benefits of the blue-green deployment strategy, highlighting the minimal impact on total connections during the upgrade. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> 38-38: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 85-85: Column: 1 Hard tabs (MD010, no-hard-tabs) </blockquote></details> </details> </blockquote></details> <details> <summary>docs/en_US/tasks/configure-emqx-blueGreenUpdate.md (1)</summary><blockquote> Line range hint `13-21`: **Excellent background information.** The expanded background section effectively highlights the limitations of traditional rolling updates, providing a clear rationale for using blue-green deployment. This context helps users understand the importance of the solution presented in this document. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint</summary><blockquote> 39-39: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 86-86: Column: 1 Hard tabs (MD010, no-hard-tabs) --- 92-92: Punctuation: '.' Trailing punctuation in heading (MD026, no-trailing-punctuation) </blockquote></details> </details> </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
In this document, just deployment only core nodes cluster, should I change cluster to core + repl cluster ? |
but I can see replicant node in the flow
|
Summary by CodeRabbit