Merge branch 'mk/changing-secondary-url' into 'master'

Docs: Help sysadmins ensure correct Geo node URL

See merge request gitlab-org/gitlab!18963

doc/administration/geo/replication/configuration.md

@@ -187,14 +187,18 @@ keys must be manually replicated to the **secondary** node.
 1. Visit the **primary** node's **Admin Area > Geo**
    (`/admin/geo/nodes`) in your browser.
 1. Click the **New node** button.
-1. Add the **secondary** node. Use the **exact** name you inputed for `gitlab_rails['geo_node_name']` as the Name and the full URL as the URL.  **Do NOT** check the
-   **This is a primary node** checkbox.
-
    ![Add secondary node](img/adding_a_secondary_node.png)
+1. Fill in **Name** with the `gitlab_rails['geo_node_name']` in
+   `/etc/gitlab/gitlab.rb`. These values must always match *exactly*, character
+   for character.
+1. Fill in **URL** with the `external_url` in `/etc/gitlab/gitlab.rb`. These
+   values must always match, but it doesn't matter if one ends with a `/` and
+   the other doesn't.
+1. **Do NOT** check the **This is a primary node** checkbox.
 1. Optionally, choose which groups or storage shards should be replicated by the
    **secondary** node. Leave blank to replicate all. Read more in
    [selective synchronization](#selective-synchronization).
-1. Click the **Add node** button.
+1. Click the **Add node** button to add the **secondary** node.
 1. SSH into your GitLab **secondary** server and restart the services:
 
    ```sh

doc/administration/geo/replication/troubleshooting.md

@@ -115,11 +115,19 @@ Any **secondary** nodes should point only to read-only instances.
 
 #### Can Geo detect the current node correctly?
 
-Geo uses the defined node from the **Admin Area > Geo** screen, and tries to match
-it with the value defined in the `/etc/gitlab/gitlab.rb` configuration file.
-The relevant line looks like: `external_url "http://gitlab.example.com"`.
+Geo finds the current machine's name in `/etc/gitlab/gitlab.rb` by first looking
+for `gitlab_rails['geo_node_name']`. If it is not defined, then it defaults to
+the external URL defined in e.g. `external_url "http://gitlab.example.com"`. To
+get a machine's name, run:
 
-To check if the node on the current machine is correctly detected type:
+```sh
+sudo gitlab-rails runner "puts GeoNode.current_node_name"
+```
+
+This name is used to look up the node with the same **Name** in
+**Admin Area > Geo**.
+
+To check if current machine is correctly finding its node:
 
 ```sh
 sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect"
@@ -511,6 +519,20 @@ to [cleanup orphan artifact files](../../../raketasks/cleanup.md#remove-orphan-a
 On a Geo **secondary** node, this command will also clean up all Geo
 registry record related to the orphan files on disk.
 
+## Fixing sign in errors
+
+### Message: The redirect URI included is not valid
+
+If you are able to log in to the **primary** node, but you receive this error
+when attempting to log into a **secondary**, you should check that the Geo
+node's URL matches its external URL.
+
+1. On the primary, visit **Admin Area > Geo**.
+1. Find the affected **secondary** and click **Edit**.
+1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb`
+   in `external_url "https://gitlab.example.com"` on the frontend server(s) of
+   the **secondary** node.
+
 ## Fixing common errors
 
 This section documents common errors reported in the Admin UI and how to fix them.