173 lines
6.5 KiB
Markdown
173 lines
6.5 KiB
Markdown
|
# Geo configuration (source) **[PREMIUM ONLY]**
|
||
|
|
||
|
NOTE: **Note:**
|
||
|
This documentation applies to GitLab source installations. In GitLab 11.5, this documentation was deprecated and will be removed in a future release.
|
||
|
Please consider [migrating to GitLab Omnibus install](https://docs.gitlab.com/omnibus/update/convert_to_omnibus.html). For installations
|
||
|
using the Omnibus GitLab packages, follow the
|
||
|
[**Omnibus Geo nodes configuration**][configuration] guide.
|
||
|
|
||
|
## Configuring a new **secondary** node
|
||
|
|
||
|
NOTE: **Note:**
|
||
|
This is the final step in setting up a **secondary** node. Stages of the setup
|
||
|
process must be completed in the documented order. Before attempting the steps
|
||
|
in this stage, [complete all prior stages](index.md#using-gitlab-installed-from-source-deprecated).
|
||
|
|
||
|
The basic steps of configuring a **secondary** node are to:
|
||
|
|
||
|
- Replicate required configurations between the **primary** and **secondary** nodes.
|
||
|
- Configure a tracking database on each **secondary** node.
|
||
|
- Start GitLab on the **secondary** node.
|
||
|
|
||
|
You are encouraged to first read through all the steps before executing them
|
||
|
in your testing/production environment.
|
||
|
|
||
|
NOTE: **Note:**
|
||
|
**Do not** set up any custom authentication on **secondary** nodes, this will be handled by the **primary** node.
|
||
|
|
||
|
NOTE: **Note:**
|
||
|
**Do not** add anything in the **secondary** node's admin area (**Admin Area > Geo**). This is handled solely by the **primary** node.
|
||
|
|
||
|
### Step 1. Manually replicate secret GitLab values
|
||
|
|
||
|
GitLab stores a number of secret values in the `/home/git/gitlab/config/secrets.yml`
|
||
|
file which *must* match between the **primary** and **secondary** nodes. Until there is
|
||
|
a means of automatically replicating these between nodes (see [gitlab-org/gitlab-ee#3789]), they must
|
||
|
be manually replicated to **secondary** nodes.
|
||
|
|
||
|
1. SSH into the **primary** node, and execute the command below:
|
||
|
|
||
|
```sh
|
||
|
sudo cat /home/git/gitlab/config/secrets.yml
|
||
|
```
|
||
|
|
||
|
This will display the secrets that need to be replicated, in YAML format.
|
||
|
|
||
|
1. SSH into the **secondary** node and login as the `git` user:
|
||
|
|
||
|
```sh
|
||
|
sudo -i -u git
|
||
|
```
|
||
|
|
||
|
1. Make a backup of any existing secrets:
|
||
|
|
||
|
```sh
|
||
|
mv /home/git/gitlab/config/secrets.yml /home/git/gitlab/config/secrets.yml.`date +%F`
|
||
|
```
|
||
|
|
||
|
1. Copy `/home/git/gitlab/config/secrets.yml` from the **primary** node to the **secondary** node, or
|
||
|
copy-and-paste the file contents between nodes:
|
||
|
|
||
|
```sh
|
||
|
sudo editor /home/git/gitlab/config/secrets.yml
|
||
|
|
||
|
# paste the output of the `cat` command you ran on the primary
|
||
|
# save and exit
|
||
|
```
|
||
|
|
||
|
1. Ensure the file permissions are correct:
|
||
|
|
||
|
```sh
|
||
|
chown git:git /home/git/gitlab/config/secrets.yml
|
||
|
chmod 0600 /home/git/gitlab/config/secrets.yml
|
||
|
```
|
||
|
|
||
|
1. Restart GitLab
|
||
|
|
||
|
```sh
|
||
|
service gitlab restart
|
||
|
```
|
||
|
|
||
|
Once restarted, the **secondary** node will automatically start replicating missing data
|
||
|
from the **primary** node in a process known as backfill. Meanwhile, the **primary** node
|
||
|
will start to notify the **secondary** node of any changes, so that the **secondary** node can
|
||
|
act on those notifications immediately.
|
||
|
|
||
|
Make sure the **secondary** node is running and accessible. You can login to
|
||
|
the **secondary** node with the same credentials as used for the **primary** node.
|
||
|
|
||
|
### Step 2. Manually replicate the **primary** node's SSH host keys
|
||
|
|
||
|
Read [Manually replicate the **primary** node's SSH host keys](configuration.md#step-2-manually-replicate-the-primary-nodes-ssh-host-keys)
|
||
|
|
||
|
### Step 3. Add the **secondary** GitLab node
|
||
|
|
||
|
1. Navigate to the **primary** node's **Admin Area > Geo**
|
||
|
(`/admin/geo/nodes`) in your browser.
|
||
|
1. Add the **secondary** node by providing its full URL. **Do NOT** check the
|
||
|
**This is a primary node** checkbox.
|
||
|
1. Optionally, choose which namespaces 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. SSH into your GitLab **secondary** server and restart the services:
|
||
|
|
||
|
```sh
|
||
|
service gitlab restart
|
||
|
```
|
||
|
|
||
|
Check if there are any common issue with your Geo setup by running:
|
||
|
|
||
|
```sh
|
||
|
bundle exec rake gitlab:geo:check
|
||
|
```
|
||
|
|
||
|
1. SSH into your GitLab **primary** server and login as root to verify the
|
||
|
**secondary** node is reachable or there are any common issue with your Geo setup:
|
||
|
|
||
|
```sh
|
||
|
bundle exec rake gitlab:geo:check
|
||
|
```
|
||
|
|
||
|
Once reconfigured, the **secondary** node will automatically start
|
||
|
replicating missing data from the **primary** node in a process known as backfill.
|
||
|
Meanwhile, the **primary** node will start to notify the **secondary** node of any changes, so
|
||
|
that the **secondary** node can act on those notifications immediately.
|
||
|
|
||
|
Make sure the **secondary** node is running and accessible.
|
||
|
You can log in to the **secondary** node with the same credentials as used for the **primary** node.
|
||
|
|
||
|
### Step 4. Enabling Hashed Storage
|
||
|
|
||
|
Read [Enabling Hashed Storage](configuration.md#step-4-enabling-hashed-storage).
|
||
|
|
||
|
### Step 5. (Optional) Configuring the secondary to trust the primary
|
||
|
|
||
|
You can safely skip this step if your **primary** node uses a CA-issued HTTPS certificate.
|
||
|
|
||
|
If your **primary** node is using a self-signed certificate for *HTTPS* support, you will
|
||
|
need to add that certificate to the **secondary** node's trust store. Retrieve the
|
||
|
certificate from the **primary** node and follow your distribution's instructions for
|
||
|
adding it to the **secondary** node's trust store. In Debian/Ubuntu, you would follow these steps:
|
||
|
|
||
|
```sh
|
||
|
sudo -i
|
||
|
cp <primary_node_certification_file> /usr/local/share/ca-certificates
|
||
|
update-ca-certificates
|
||
|
```
|
||
|
|
||
|
### Step 6. Enable Git access over HTTP/HTTPS
|
||
|
|
||
|
Geo synchronizes repositories over HTTP/HTTPS, and therefore requires this clone
|
||
|
method to be enabled. Navigate to **Admin Area > Settings**
|
||
|
(`/admin/application_settings`) on the **primary** node, and set
|
||
|
`Enabled Git access protocols` to `Both SSH and HTTP(S)` or `Only HTTP(S)`.
|
||
|
|
||
|
### Step 7. Verify proper functioning of the secondary node
|
||
|
|
||
|
Read [Verify proper functioning of the secondary node][configuration-verify-node].
|
||
|
|
||
|
## Selective synchronization
|
||
|
|
||
|
Read [Selective synchronization][configuration-selective-replication].
|
||
|
|
||
|
## Troubleshooting
|
||
|
|
||
|
Read the [troubleshooting document][troubleshooting].
|
||
|
|
||
|
[gitlab-org/gitlab-ee#3789]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3789
|
||
|
[configuration]: configuration.md
|
||
|
[configuration-selective-replication]: configuration.md#selective-synchronization
|
||
|
[configuration-verify-node]: configuration.md#step-7-verify-proper-functioning-of-the-secondary-node
|
||
|
[troubleshooting]: troubleshooting.md
|