mirror of
https://github.com/apache/activemq-artemis.git
synced 2025-02-10 20:15:27 +00:00
3a4b421d2e
Markdown, which is currently used for user-facing documentation, is good for a lot of things. However, it's not great for the kind of complex documentation we have and our need to produce both multi-page HTML and single-page PDF output via Maven. Markdown lacks features which would make the documentation easier to read, easier to navigate, and just look better overall. The current tool-chain uses honkit and a tool called Calibre. Honkit is written in TypeScript and is installed via NPM. Calibre is a native tool so it must be installed via an OS-specific package manager. All this complexity makes building, releasing, uploading, etc. a pain. AsciiDoc is relatively simple like Markdown, but it has more features for presentation and navigation not to mention Java-based Maven tooling to generate both HTML and PDF. Migrating will improve both the appearance of the documentation as well as the processes to generate and upload it. This commit contains the following changes: - Convert all the Markdown for the User Manual, Migration Guide, and Hacking guide to AsciiDoc via kramdown [1]. - Update the `artemis-website` build to use AsciiDoctor Maven tooling. - Update `RELEASING.md` with simplified instructions. - Update Hacking Guide with simplified instructions. - Use AsciiDoc link syntax in Artemis Maven doc plugin. - Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking Guide. All docs will be HTML only except for the User Manual which will have PDF. - Move all docs up out of their respective "en" directory. This was a hold-over from when we had docs in different languages. - Migration & Hacking Guides are now single-page HTML since they are relatively short. - Refactor README.md to simplify and remove redundant content. Benefits of the change: - Much simplified tooling. No more NPM packages or native tools. - Auto-generated table of contents for every chapter. - Auto-generated anchor links for every sub-section. - Overall more appealing presentation. - All docs will use the ActiveMQ favicon. - No more manual line-wrapping! AsciiDoc recommends one sentence per line and paragraphs are separated by a blank line. - AsciiDoctor plugins for IDEA are quite good. - Resulting HTML is less than *half* of the previous size. All previous links/bookmarks should continue to work. [1] https://github.com/asciidoctor/kramdown-asciidoc
45 lines
2.0 KiB
Plaintext
45 lines
2.0 KiB
Plaintext
= Activation Sequence Tools
|
|
:idprefix:
|
|
:idseparator: -
|
|
|
|
You can use the Artemis CLI to execute activation sequence maintenance/recovery tools for xref:ha.adoc#high-availability-and-failover[Pluggable Quorum Replication].
|
|
|
|
The 2 main commands are `activation list` and `activation set`, that can be used together to recover some disaster happened to local/coordinated activation sequences.
|
|
|
|
Here is a disaster scenario built around the RI (using https://zookeeper.apache.org/[Apache ZooKeeper] and https://curator.apache.org/[Apache curator]) to demonstrate the usage of such commands.
|
|
|
|
== Troubleshooting Case: ZooKeeper Cluster disaster
|
|
|
|
A proper ZooKeeper cluster should use at least 3 nodes, but what happens if all these nodes crash loosing any activation state information required to run an Artemis replication cluster?
|
|
|
|
During the disaster ie ZooKeeper nodes no longer reachable, brokers:
|
|
|
|
* live ones shutdown (and if restarted by a script, should hang awaiting to connect to the ZooKeeper cluster again)
|
|
* replicas become passive, awaiting to connect to the ZooKeeper cluster again
|
|
|
|
Admin should:
|
|
|
|
. Stop all Artemis brokers
|
|
. Restart ZooKeeper cluster
|
|
. Search brokers with the highest local activation sequence for their `NodeID`, by running this command from the `bin` folder of the broker:
|
|
+
|
|
[,bash]
|
|
----
|
|
$ ./artemis activation list --local
|
|
Local activation sequence for NodeID=7debb3d1-0d4b-11ec-9704-ae9213b68ac4: 1
|
|
----
|
|
|
|
. From the `bin` folder of the brokers with the highest local activation sequence
|
|
+
|
|
[,bash]
|
|
----
|
|
# assuming 1 to be the highest local activation sequence obtained at the previous step
|
|
# for NodeID 7debb3d1-0d4b-11ec-9704-ae9213b68ac4
|
|
$ ./artemis activation set --remote --to 1
|
|
Forced coordinated activation sequence for NodeID=7debb3d1-0d4b-11ec-9704-ae9213b68ac4 from 0 to 1
|
|
----
|
|
|
|
. Restart all brokers: previously live ones should be able to be live again
|
|
|
|
The higher the number of ZooKeeper nodes are, the less the chance are that a disaster like this requires Admin intervention, because it allows the ZooKeeper cluster to tolerate more failures.
|