From d79a838f8a845032d1948a5c6fdcfeffae104114 Mon Sep 17 00:00:00 2001 From: Niraj Kumar Yadav Date: Mon, 20 Jun 2022 11:46:45 +0530 Subject: [PATCH 1/3] [QOL] Extend keyboard shortcuts to copy current address (#733) This patch also removes the obsolete fix-docs.js. That file depends of jQuery and we no longer use that. That file was also the cause of the console errors on current docs site. After this patch, users will be able to press C or Y(ank) to copy current address along with anchors to the clipboard. This feature is just an extension of multiple exisiting shortcuts like F/P/N. Another patch is in the works which would update current address so that current anchor is in the addressbar. That would make this patch more useful as you will be able to copy the adress of the location that you are currently reading in the doc and resume later or maybe share to someone. Cool, right? Signed-off-by: black-dragon74 --- docs/js/custom-features.js | 40 +++++++++++++++++++++ docs/js/fix-docs.js | 74 -------------------------------------- mkdocs.yml | 2 +- 3 files changed, 41 insertions(+), 75 deletions(-) create mode 100644 docs/js/custom-features.js delete mode 100644 docs/js/fix-docs.js diff --git a/docs/js/custom-features.js b/docs/js/custom-features.js new file mode 100644 index 0000000..a76a722 --- /dev/null +++ b/docs/js/custom-features.js @@ -0,0 +1,40 @@ +// Add ability to copy the current URL using vim like shortcuts +// There already exists navigation related shortcuts like +// F/S -- For Searching +// P/N -- For navigating to previous/next pages +// This patch just extends those features + +// Expose the internal notification API of mkdocs +// This API isn't exposed publically, IDK why +// They use it internally to show notifications when user copies a code block +// I reverse engineered it for ease of use, takes a string arg `msg` +const notifyDOM = (msg) => { + if (typeof alert$ === "undefined") { + console.error("Clipboard notification API not available"); + return; + } + + alert$.next(msg); +}; + +// Extend the keyboard shortcut features +keyboard$.subscribe((key) => { + // We want to allow the user to be able to type our modifiders in search + // Disallowing that would be hilarious + if (key.mode === "search") { + return; + } + + const keyPressed = key.type.toLowerCase(); + + // Y is added to honor vim enthusiasts (yank) + if (keyPressed === "c" || keyPressed === "y") { + const currLocation = window.location.href; + if (currLocation) { + navigator.clipboard + .writeText(currLocation) + .then(() => notifyDOM("Address copied to clipboard")) + .catch((e) => console.error(e)); + } + } +}); diff --git a/docs/js/fix-docs.js b/docs/js/fix-docs.js deleted file mode 100644 index f5a0070..0000000 --- a/docs/js/fix-docs.js +++ /dev/null @@ -1,74 +0,0 @@ -(function () { - 'use strict'; - - $(document).ready(function () { - fixSearchResults(); - fixSearch(); - warnDomain(); - }); - - /** - * Adds a TOC-style table to each page in the 'Modules' section. - */ - function fixSearchResults() { - $('#mkdocs-search-results').text('Searching...'); - } - - /** - * Warn if the domain is gluster.readthedocs.io - * - */ - function warnDomain() { - var domain = window.location.hostname; - if (domain.indexOf('readthedocs.io') != -1) { - $('div.section').prepend('

You are viewing outdated content. We have moved to docs.gluster.org.

'); - } - } - - /* - * RTD messes up MkDocs' search feature by tinkering with the search box defined in the theme, see - * https://github.com/rtfd/readthedocs.org/issues/1088. This function sets up a DOM4 MutationObserver - * to react to changes to the search form (triggered by RTD on doc ready). It then reverts everything - * the RTD JS code modified. - */ - function fixSearch() { - var target = document.getElementById('mkdocs-search-form'); - var config = {attributes: true, childList: true}; - - var observer = new MutationObserver(function(mutations) { - // if it isn't disconnected it'll loop infinitely because the observed element is modified - observer.disconnect(); - var form = $('#mkdocs-search-form'); - form.empty(); - form.attr('action', 'https://' + window.location.hostname + '/en/' + determineSelectedBranch() + '/search.html'); - $('').attr({ - type: "text", - name: "q", - placeholder: "Search docs" - }).appendTo(form); - }); - - if (window.location.origin.indexOf('readthedocs') > -1 || window.location.origin.indexOf('docs.gluster.org') > -1) { - observer.observe(target, config); - } - } - - - /** - * Analyzes the URL of the current page to find out what the selected GitHub branch is. It's usually - * part of the location path. The code needs to distinguish between running MkDocs standalone - * and docs served from RTD. If no valid branch could be determined 'dev' returned. - * - * @returns GitHub branch name - */ - function determineSelectedBranch() { - var branch = 'latest', path = window.location.pathname; - if (window.location.origin.indexOf('readthedocs') > -1) { - // path is like /en///build/ -> extract 'lang' - // split[0] is an '' because the path starts with the separator - branch = path.split('/')[2]; - } - return branch; - } - -}()); diff --git a/mkdocs.yml b/mkdocs.yml index 332042b..752122b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -275,7 +275,7 @@ nav: - Google Site Verification: ./google64817fdc11b2f6b6.html extra_javascript: - - js/fix-docs.js + - js/custom-features.js extra_css: - css/custom.css From baed3a94d88cc1d4979bbe93d3f529eba680a2fe Mon Sep 17 00:00:00 2001 From: Niraj Kumar Yadav Date: Mon, 20 Jun 2022 11:53:31 +0530 Subject: [PATCH 2/3] [nav-qol] Add support for anchor tracking in the nav bar (#752) This patch makes #733 more usable and it updates the address of the current URL to the current anchor that you are reading at. Like, mysite/mychapter#mysectiom, using which, sharing the links will lead to the same place on the page that the user 1 was reading at. Signed-off-by: black-dragon74 --- mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 752122b..c6fac4f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,8 @@ markdown_extensions: theme: name: material favicon: images/favicon.ico + features: + - navigation.tracking palette: - scheme: slate media: "(prefers-color-scheme: dark)" From 672e6ca2966e34d50313b10cc655316acac6a3b2 Mon Sep 17 00:00:00 2001 From: Johannes Kastl Date: Fri, 24 Jun 2022 11:40:36 +0200 Subject: [PATCH 3/3] Split-brain-and-ways-to-deal-with-it.md: fix missing line breaks and small typo fixes (#729) * docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md: fix missing line breaks * docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md: fix grammar typo * docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md: format 'replica 2' as code to make it more readable * docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md: fix more missing linebreaks --- .../Split-brain-and-ways-to-deal-with-it.md | 28 +++++++++++++------ 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md b/docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md index 601f8d2..85093f0 100644 --- a/docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md +++ b/docs/Administrator-Guide/Split-brain-and-ways-to-deal-with-it.md @@ -1,46 +1,55 @@ # Split brain and the ways to deal with it ### Split brain: -Split brain is a situation where two or more replicated copies of a file become divergent. When a file is in split brain, there is an inconsistency in either data or metadata of the file amongst the bricks of a replica and do not have enough information to authoritatively pick a copy as being pristine and heal the bad copies, despite all bricks being up and online. For a directory, there is also an entry split brain where a file inside it can have different gfid/file-type across the bricks of a replica. Split brain can happen mainly because of 2 reasons: -1. Due to network disconnect: -Where a client temporarily loses connection to the bricks. +Split brain is a situation where two or more replicated copies of a file become divergent. When a file is in split brain, there is an inconsistency in either data or metadata of the file amongst the bricks of a replica and do not have enough information to authoritatively pick a copy as being pristine and heal the bad copies, despite all bricks being up and online. For a directory, there is also an entry split brain where a file inside it can have different gfid/file-type across the bricks of a replica. + +Split brain can happen mainly because of 2 reasons: + +1. Due to network disconnect, where a client temporarily loses connection to the bricks. + - There is a replica pair of 2 bricks, brick1 on server1 and brick2 on server2. - Client1 loses connection to brick2 and client2 loses connection to brick1 due to network split. - Writes from client1 goes to brick1 and from client2 goes to brick2, which is nothing but split-brain. + 2. Gluster brick processes going down or returning error: + - Server1 is down and server2 is up: Writes happen on server 2. - Server1 comes up, server2 goes down (Heal not happened / data on server 2 is not replicated on server1): Writes happen on server1. - Server2 comes up: Both server1 and server2 has data independent of each other. -If we use the replica 2 volume, it is not possible to prevent split-brain without losing availability. +If we use the `replica 2` volume, it is not possible to prevent split-brain without losing availability. ### Ways to deal with split brain: In glusterfs there are ways to resolve split brain. You can see the detailed description of how to resolve a split-brain [here](../Troubleshooting/resolving-splitbrain.md). Moreover, there are ways to reduce the chances of ending up in split-brain situations. They are: -1. Replica 3 volume + +1. volume with `replica 3` 2. Arbiter volume -Both of these uses the client-quorum option of glusterfs to avoid the split-brain situations. +Both of these use the client-quorum option of glusterfs to avoid the split-brain situations. ### Client quorum: This is a feature implemented in Automatic File Replication (AFR here on) module, to prevent split-brains in the I/O path for replicate/distributed-replicate volumes. By default, if the client-quorum is not met for a particular replica subvol, it becomes read-only. The other subvols (in a dist-rep volume) will still have R/W access. [Here](arbiter-volumes-and-quorum.md#client-quorum) you can see more details about client-quorum. #### Client quorum in replica 2 volumes: -In a replica 2 volume it is not possible to achieve high availability and consistency at the same time, without sacrificing tolerance to partition. If we set the client-quorum option to auto, then the first brick must always be up, irrespective of the status of the second brick. If only the second brick is up, the subvolume becomes read-only. +In a `replica 2` volume it is not possible to achieve high availability and consistency at the same time, without sacrificing tolerance to partition. If we set the client-quorum option to auto, then the first brick must always be up, irrespective of the status of the second brick. If only the second brick is up, the subvolume becomes read-only. If the quorum-type is set to fixed, and the quorum-count is set to 1, then we may end up in split brain. + - Brick1 is up and brick2 is down. Quorum is met and write happens on brick1. - Brick1 goes down and brick2 comes up (No heal happened). Quorum is met, write happens on brick2. - Brick1 comes up. Quorum is met, but both the bricks have independent writes - split-brain. + To avoid this we have to set the quorum-count to 2, which will cost the availability. Even if we have one replica brick up and running, the quorum is not met and we end up seeing EROFS. ### 1. Replica 3 volume: -When we create a replicated or distributed replicated volume with replica count 3, the cluster.quorum-type option is set to auto by default. That means at least 2 bricks should be up and running to satisfy the quorum and allow the writes. This is the recommended setting for a replica 3 volume and this should not be changed. Here is how it prevents files from ending up in split brain: +When we create a replicated or distributed replicated volume with replica count 3, the cluster.quorum-type option is set to auto by default. That means at least 2 bricks should be up and running to satisfy the quorum and allow the writes. This is the recommended setting for a `replica 3` volume and this should not be changed. Here is how it prevents files from ending up in split brain: B1, B2, and B3 are the 3 bricks of a replica 3 volume. + 1. B1 & B2 are up and B3 is down. Quorum is met and write happens on B1 & B2. 2. B3 comes up and B2 is down. Quorum is met and write happens on B1 & B3. 3. B2 comes up and B1 goes down. Quorum is met. But when a write request comes, AFR sees that B2 & B3 are blaming each other (B2 says that some writes are pending on B3 and B3 says that some writes are pending on B2), therefore the write is not allowed and is failed with EIO. -Command to create a replica 3 volume: +Command to create a `replica 3` volume: ```sh $gluster volume create replica 3 host1:brick1 host2:brick2 host3:brick3 ``` @@ -65,6 +74,7 @@ Since the arbiter brick has only name and metadata of the files, there are some You can find more details on arbiter [here](arbiter-volumes-and-quorum.md). ### Differences between replica 3 and arbiter volumes: + 1. In case of a replica 3 volume, we store the entire file in all the bricks and it is recommended to have bricks of same size. But in case of arbiter, since we do not store data, the size of the arbiter brick is comparatively lesser than the other bricks. 2. Arbiter is a state between replica 2 and replica 3 volume. If we have only arbiter and one of the other brick is up and the arbiter brick blames the other brick, then we can not proceed with the FOPs. 4. Replica 3 gives high availability compared to arbiter, because unlike in arbiter, replica 3 has a full copy of the data in all 3 bricks.