Skip to content

G
gitlab-ce
Commit 02fe5f6d authored by Ernst van Nierop's avatar Ernst van Nierop Committed by Nick Thomas
Browse files
Options

Simplifying the configuration page

parent 1d055140
Hide whitespace changes
Inline Side-by-side
Showing with 81 additions and 182 deletions
doc/gitlab-geo/configuration.md
View file @ 02fe5f6d
......@@ -5,62 +5,42 @@ This is the documentation for the Omnibus GitLab packages. For installations
from source, follow the [**GitLab Geo nodes configuration for installations
from source**](configuration_source.md) guide.
## Configuring a new secondary node
>**Note:**
Stages of the setup process must be completed in the documented order.
Before attempting the steps in this stage, [complete all prior stages][toc].
This is the final step in setting up a secondary Geo node. Stages of the
setup process must be completed in the documented order.
Before attempting the steps in this stage, [complete all prior stages](README.md#using-omnibus-gitlab).
The basic steps of configuring a secondary node are:
This is the final step you need to follow in order to setup a Geo node.
1. replicate required configurations between the primary and the secondaries;
1. configure a second, tracking database on each secondary;
1. start GitLab on the secondary node's machine.
You are encouraged to first read through all the steps before executing them
in your testing/production environment.
## Setting up GitLab
>**Notes:**
- **Do not** setup any custom authentication in the secondary nodes, this will be
handled by the primary node.
- **Do not** add anything in the secondaries Geo nodes admin area
(**Admin Area ➔ Geo Nodes**). This is handled solely by the primary node.
After having installed GitLab Enterprise Edition in the instance that will serve
as a Geo node and set up the [database replication](database.md), the next steps
can be summed up to:
1. Replicate some required configurations between the primary and the secondaries
1. Configure a second, tracking database on each secondary
1. Start GitLab on the secondary node's machine
### Prerequisites
This is the last step of configuring a Geo secondary node. Make sure you have
followed the first two steps of the [Setup instructions](README.md#setup-instructions):
1. You have already installed on the secondary server the same version of
GitLab Enterprise Edition that is present on the primary server.
1. You have set up the database replication.
1. Your secondary node is allowed to communicate via HTTP/HTTPS with
your primary node (make sure your firewall is not blocking that).
1. Your nodes must have an NTP service running to synchronize the clocks.
You can use different timezones, but the hour relative to UTC can't be more
than 60 seconds off from each node.
### Step 1. Copying the database encryption key
GitLab stores a unique encryption key in disk that we use to safely store
sensitive data in the database. Any secondary node must have the
**exact same value** for `db_key_base` as defined in the primary one.
GitLab stores a unique encryption key on disk that is used to encrypt
sensitive data stored in the database. All secondary nodes must have the
**exact same value** for `db_key_base` as defined on the primary node.
1. SSH into the **primary** node and login as root:
1. SSH into the **primary** node, and execute the command below
to display the current encryption key:
```bash
sudo gitlab-rake geo:db:show_encryption_key
```
sudo -i
```
1. Execute the command below to display the current encryption key and copy it:
```
gitlab-rake geo:db:show_encryption_key
```
Copy the encryption key to bring it to the secondary node in the following steps.
1. SSH into the **secondary** node and login as root:
......@@ -81,18 +61,22 @@ sensitive data in the database. Any secondary node must have the
gitlab-ctl reconfigure
```
Once reconfigured, the secondary will start automatically
Once reconfigured, the secondary will automatically start
replicating missing data from the primary in a process known as backfill.
Meanwhile, the primary node will start to notify changes to the secondary, which
will act on those notifications immediately. Make sure the secondary instance is
running and accessible.
Meanwhile, the primary node will start to notify the secondary of any changes, so
that the secondary can act on those notifications immediately.
### Step 2. Enabling hashed storage (optional, from GitLab 10.0)
Make sure the secondary instance is
running and accessible. You can login to the secondary node
with the same credentials as used in the primary.
### Step 2. (Optional) Enabling hashed storage (from GitLab 10.0)
>**Warning**
Hashed storage is in **Alpha**. It is considered experimental and not
production-ready. See [Hashed
Storage](../administration/repository_storage_types.md) for more detail.
production-ready. See [Hashed Storage](../administration/repository_storage_types.md)
for more detail, and for the latest updates, check
[infrastructure issue #2821](https://gitlab.com/gitlab-com/infrastructure/issues/2821).
Using hashed storage significantly improves Geo replication - project and group
renames no longer require synchronization between nodes.
......@@ -120,7 +104,17 @@ 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 5. Managing the secondary GitLab node
### Verify proper functioning of the secondary node
Your nodes should now be ready to use. You can login to the secondary node
with the same credentials as used in the primary. Visit the secondary node's
**Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`) in your browser to check if it's
correctly identified as a secondary Geo node and if Geo is enabled.
If your installation isn't working properly, check the
[troubleshooting document](troubleshooting.md).
Point your users to the ["Using a Geo Server" guide](using_a_geo_server.md).
You can monitor the status of the syncing process on a secondary node
by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
......@@ -139,36 +133,23 @@ The two most obvious issues that replication can have here are:
1. Instance to instance notification not working. In that case, it can be
something of the following:
- You are using a custom certificate or custom CA (see the
[Troubleshooting](configuration.md#troubleshooting) section)
- Instance is firewalled (check your firewall rules)
[troubleshooting document](troubleshooting.md))
- The instance is firewalled (check your firewall rules)
Currently, this is what is synced:
* Git repositories
* Wikis
* LFS objects
* Issue, merge request, snippet and comment attachments
* User, group, and project avatars
## Next steps
Your nodes should now be ready to use. You can login to the secondary node
with the same credentials as used in the primary. Visit the secondary node's
**Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`) in your browser to check if it's
correctly identified as a secondary Geo node and if Geo is enabled.
If your installation isn't working properly, check the
[troubleshooting](#troubleshooting) section.
Point your users to the ["Using a Geo Server" guide](using_a_geo_server.md).
* Issues, merge requests, snippets, and comment attachments
* Users, groups, and project avatars
## Selective replication
With GitLab 9.5, GitLab Geo now supports the first iteration of selective
replication, which allows admins to choose which groups should be
replicated by secondary nodes.
GitLab Geo supports selective replication, which allows admins to choose which
groups should be replicated by secondary nodes.
It is important to notice that selective replication:
It is important to note that selective replication:
1. Does not restrict permissions from secondary nodes.
1. Does not hide projects metadata from secondary nodes. Since Geo currently
......@@ -177,12 +158,10 @@ secondary nodes, but repositories that have not been selected will be empty.
1. Secondary nodes won't pull repositories that do not belong to the selected
groups to be replicated.
### Upgrading Geo
## Upgrading Geo
See the [updating the Geo nodes document](updating_the_geo_nodes.md).
## Troubleshooting
See the [troubleshooting document](troubleshooting.md).
[toc]: README.md#using-omnibus-gitlab
doc/gitlab-geo/configuration_source.md
View file @ 02fe5f6d
......@@ -5,16 +5,22 @@ This is the documentation for installations from source. For installations
using the Omnibus GitLab packages, follow the
[**Omnibus GitLab Geo nodes configuration**](configuration.md) guide.
## Configuring a new secondary node
>**Note:**
Stages of the setup process must be completed in the documented order.
Before attempting the steps in this stage, [complete all prior stages][toc].
This is the final step in setting up a secondary Geo node. Stages of the setup
process must be completed in the documented order. Before attempting the steps
in this stage, [complete all prior stages](README.md#using-gitlab-installed-from-source).
The basic steps of configuring a secondary node are:
This is the final step you need to follow in order to setup a Geo node.
1. replicate required configurations between the primary and the secondaries;
1. configure a second, tracking database on each secondary;
1. start GitLab on the secondary node's machine.
You are encouraged to first read through all the steps before executing them
in your testing/production environment.
## Setting up GitLab
>**Notes:**
- **Do not** setup any custom authentication in the secondary nodes, this will be
......@@ -22,90 +28,48 @@ in your testing/production environment.
- **Do not** add anything in the secondaries Geo nodes admin area
(**Admin Area ➔ Geo Nodes**). This is handled solely by the primary node.
After having installed GitLab Enterprise Edition in the instance that will serve
as a Geo node and set up the [database replication](database_source.md), the
next steps can be summed up to:
1. Replicate some required configurations between the primary and the secondaries
1. Configure a second, tracking database on each secondary
1. Start GitLab on the secondary node's machine
### Prerequisites
This is the last step of configuring a Geo secondary node. Make sure you have
followed the first two steps of the [Setup instructions](README.md#setup-instructions):
1. You have already installed on the secondary server the same version of
GitLab Enterprise Edition that is present on the primary server.
1. You have set up the database replication.
1. Your secondary node is allowed to communicate via HTTP/HTTPS with
your primary node (make sure your firewall is not blocking that).
1. Your nodes must have an NTP service running to synchronize the clocks.
You can use different timezones, but the hour relative to UTC can't be more
than 60 seconds off from each node.
1. You have set up another PostgreSQL database that can store writes for the secondary.
Note that this MUST be on another instance, since the primary replicated database
is read-only.
### Step 1. Copying the database encryption key
GitLab stores a unique encryption key in disk that we use to safely store
sensitive data in the database. Any secondary node must have the
**exact same value** for `db_key_base` as defined in the primary one.
1. SSH into the **primary** node and login as root:
GitLab stores a unique encryption key on disk that is used to encrypt
sensitive data stored in the database. All secondary nodes must have the
**exact same value** for `db_key_base` as defined on the primary node.
```
sudo -i
```
1. SSH into the **primary** node, and execute the command below to display the
current encryption key:
1. Execute the command below to display the current encryption key and copy it:
```
```bash
sudo -u git -H bundle exec rake geo:db:show_encryption_key RAILS_ENV=production
```
1. SSH into the **secondary** node and login as root:
Copy the encryption key to bring it to the secondary node in the following steps.
```
sudo -i
```
1. SSH into the **secondary**, and execute the command below to open the
`secrets.yml` file:
1. Open the `secrets.yml` file and change the value of `db_key_base` to the
output of the previous step:
```
```bash
sudo -u git -H editor config/secrets.yml
```
1. Save and close the file.
1. Change the value of `db_key_base` to the output from the primary node.
Then save and close the file.
1. Restart GitLab for the changes to take effect:
```
```bash
service gitlab restart
```
The secondary will start automatically replicating missing data from the
primary in a process known as backfill. Meanwhile, the primary node will start
to notify changes to the secondary, which will act on those notifications
immediately. Make sure the secondary instance is running and accessible.
### Step 2. Enabling hashed storage (optional, GitLab 10.0)
Once restarted, the secondary will automatically start replicating missing data
from the primary in a process known as backfill. Meanwhile, the primary node
will start to notify the secondary of any changes, so that the secondary can
act on those notifications immediately.
>**Warning**
Hashed storage is in **Alpha**. It is considered experimental and not
production-ready. See [Hashed
Storage](../administration/repository_storage_types.md) for more detail.
Make sure the secondary instance is running and accessible. You can login to
the secondary node with the same credentials as used in the primary.
Using hashed storage significantly improves Geo replication - project and group
renames no longer require synchronization between nodes.
### Step 2. (Optional) Enabling hashed storage (from GitLab 10.0)
1. Visit the **primary** node's **Admin Area ➔ Settings**
(`/admin/application_settings`) in your browser
1. In the `Repository Storages` section, check `Create new projects using hashed storage paths`:
![](img/hashed-storage.png)
Read [Enabling Hashed Storage](configuration.md#step-2-optional-enabling-hashed-storage-from-gitlab-10-0)
### Step 3. (Optional) Configuring the secondary to trust the primary
......@@ -130,52 +94,10 @@ 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)`.
### Verify proper functioning of the secondary node
### Step 5. Managing the secondary GitLab node
You can monitor the status of the syncing process on a secondary node
by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
in your browser.
Please note that if `git_data_dirs` is customized on the primary for multiple
repository shards you must duplicate the same configuration on the secondary.
![GitLab Geo dashboard](img/geo-node-dashboard.png)
Disabling a secondary node stops the syncing process.
The two most obvious issues that replication can have here are:
Read [Verify proper functioning of the secondary node](configuration.md#verify-proper-functioning-of-the-secondary-node).
1. Database replication not working well
1. Instance to instance notification not working. In that case, it can be
something of the following:
- You are using a custom certificate or custom CA (see the
[Troubleshooting](configuration.md#troubleshooting) section)
- Instance is firewalled (check your firewall rules)
Currently, this is what is synced:
* Git repositories
* Wikis
* LFS objects
* Issue, merge request, snippet and comment attachments
* User, group, and project avatars
You can monitor the status of the syncing process on a secondary node
by visiting the primary node's **Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`)
in your browser.
## Next steps
Your nodes should now be ready to use. You can login to the secondary node
with the same credentials as used in the primary. Visit the secondary node's
**Admin Area ➔ Geo Nodes** (`/admin/geo_nodes`) in your browser to check if it's
correctly identified as a secondary Geo node and if Geo is enabled.
If your installation isn't working properly, check the
[troubleshooting](configuration.md#troubleshooting) section.
Point your users to the ["Using a Geo Server" guide](using_a_geo_server.md).
## Selective replication
......@@ -184,5 +106,3 @@ Read [Selective replication](configuration.md#selective-replication).
## Troubleshooting
Read the [troubleshooting document](troubleshooting.md).
[toc]: README.md#using-gitlab-installed-from-source
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7