diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-07-20 15:26:25 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-07-20 15:26:25 +0300 |
commit | a09983ae35713f5a2bbb100981116d31ce99826e (patch) | |
tree | 2ee2af7bd104d57086db360a7e6d8c9d5d43667a /doc/administration/gitaly | |
parent | 18c5ab32b738c0b6ecb4d0df3994000482f34bd8 (diff) |
Add latest changes from gitlab-org/gitlab@13-2-stable-ee
Diffstat (limited to 'doc/administration/gitaly')
-rw-r--r-- | doc/administration/gitaly/img/praefect_storage_v12_10.png | bin | 59531 -> 0 bytes | |||
-rw-r--r-- | doc/administration/gitaly/index.md | 564 | ||||
-rw-r--r-- | doc/administration/gitaly/praefect.md | 335 | ||||
-rw-r--r-- | doc/administration/gitaly/reference.md | 2 |
4 files changed, 600 insertions, 301 deletions
diff --git a/doc/administration/gitaly/img/praefect_storage_v12_10.png b/doc/administration/gitaly/img/praefect_storage_v12_10.png Binary files differdeleted file mode 100644 index f60a56fa1fb..00000000000 --- a/doc/administration/gitaly/img/praefect_storage_v12_10.png +++ /dev/null diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 1469ed64004..057d0559c14 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -19,12 +19,13 @@ In the Gitaly documentation: - [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell). - [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse). -GitLab end users do not have direct access to Gitaly. +GitLab end users do not have direct access to Gitaly. Gitaly only manages Git +repository access for GitLab. Other types of GitLab data aren't accessed using Gitaly. CAUTION: **Caution:** -From GitLab 13.0, using NFS for Git repositories is deprecated. In GitLab 14.0, -support for NFS for Git repositories is scheduled to be removed. Upgrade to -[Gitaly Cluster](praefect.md) as soon as possible. +From GitLab 13.0, Gitaly support for NFS is deprecated. In GitLab 14.0, Gitaly support +for NFS is scheduled to be removed. Upgrade to [Gitaly Cluster](praefect.md) as soon as +possible. ## Architecture @@ -49,6 +50,12 @@ To change Gitaly settings: 1. Edit `/home/git/gitaly/config.toml` and add or change the [Gitaly settings](https://gitlab.com/gitlab-org/gitaly/blob/master/config.toml.example). 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +The following configuration options are also available: + +- Enabling [TLS support](#enable-tls-support). +- Configuring the [number of `gitaly-ruby` workers](#configure-number-of-gitaly-ruby-workers). +- Limiting [RPC concurrency](#limit-rpc-concurrency). + ## Run Gitaly on its own server By default, Gitaly is run on the same server as Gitaly clients and is @@ -72,6 +79,7 @@ The process for setting up Gitaly on its own server is: 1. [Configure authentication](#configure-authentication). 1. [Configure Gitaly servers](#configure-gitaly-servers). 1. [Configure Gitaly clients](#configure-gitaly-clients). +1. [Disable Gitaly where not required](#disable-gitaly-where-not-required-optional) (optional). When running Gitaly on its own server, note the following regarding GitLab versions: @@ -116,7 +124,7 @@ The following list depicts the network architecture of Gitaly: DANGER: **Danger:** Gitaly servers must not be exposed to the public internet as Gitaly's network traffic is unencrypted by default. The use of firewall is highly recommended to restrict access to the Gitaly server. -Another option is to [use TLS](#tls-support). +Another option is to [use TLS](#enable-tls-support). In the following sections, we describe how to configure two Gitaly servers with secret token `abc123secret`: @@ -380,20 +388,10 @@ Gitaly makes the following assumptions: clients, and that Gitaly server can read and write to `/mnt/gitlab/storage2`. - Your `gitaly1.internal` and `gitaly2.internal` Gitaly servers can reach each other. -Note you can't a use mixed setup, with at least one of your Gitaly servers configured as a local -server with the `path` setting provided. This is because other Gitaly instances can't communicate -with it. The following setup is _incorrect_, because: - -- You must replace `path` with `gitaly_address` containing a proper value. -- The address must be reachable from the other two addresses provided. - -```ruby -git_data_dirs({ - 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, - 'storage1' => { 'path' => '/var/opt/gitlab/git-data' }, - 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, -}) -``` +You can't define Gitaly servers with some as a local Gitaly server +(without `gitaly_address`) and some as remote +server (with `gitaly_address`) unless you setup with special +[mixed configuration](#mixed-configuration). **For Omnibus GitLab** @@ -457,15 +455,47 @@ If you have [server hooks](../server_hooks.md) configured, either per repository must move these to the Gitaly servers. If you have multiple Gitaly servers, copy your server hooks to all Gitaly servers. -### Disabling the Gitaly service in a cluster environment +#### Mixed configuration + +GitLab can reside on the same server as one of many Gitaly servers, but doesn't support +configuration that mixes local and remote configuration. The following setup is incorrect, because: + +- All addresses must be reachable from the other Gitaly servers. +- `storage1` will be assigned a Unix socket for `gitaly_address` which is + invalid for some of the Gitaly servers. + +```ruby +git_data_dirs({ + 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, + 'storage1' => { 'path' => '/mnt/gitlab/git-data' }, + 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, +}) +``` + +To combine local and remote Gitaly servers, use an external address for the local Gitaly server. For +example: + +```ruby +git_data_dirs({ + 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, + # Address of the GitLab server that has Gitaly running on it + 'storage1' => { 'gitaly_address' => 'tcp://gitlab.internal:8075', 'path' => '/mnt/gitlab/git-data' }, + 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, +}) +``` + +`path` can only be included for storage shards on the local Gitaly server. +If it's excluded, default Git storage directory will be used for that storage shard. -If you are running Gitaly [as a remote -service](#run-gitaly-on-its-own-server) you may want to disable -the local Gitaly service that runs on your GitLab server by default. -Disabling Gitaly only makes sense when you run GitLab in a custom -cluster configuration, where different services run on different -machines. Disabling Gitaly on all machines in the cluster is not a -valid configuration. +### Disable Gitaly where not required (optional) + +If you are running Gitaly [as a remote service](#run-gitaly-on-its-own-server) you may want to +disable the local Gitaly service that runs on your GitLab server by default, leaving it only running +where required. + +Disabling Gitaly on the GitLab instance only makes sense when you run GitLab in a custom cluster configuration, where +Gitaly runs on a separate machine from the GitLab instance. Disabling Gitaly on all machines in the cluster is not +a valid configuration (some machines much act as Gitaly servers). To disable Gitaly on a GitLab server: @@ -489,43 +519,44 @@ To disable Gitaly on a GitLab server: 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). -## TLS support +## Enable TLS support > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22602) in GitLab 11.8. -Gitaly supports TLS encryption. To be able to communicate -with a Gitaly instance that listens for secure connections you will need to use `tls://` URL -scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. +Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure +connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding +storage entry in the GitLab configuration. -You will need to bring your own certificates as this isn't provided automatically. -The certificate corresponding to each Gitaly server will need to be installed -on that Gitaly server. +You must supply your own certificates as this isn't provided automatically. The certificate +corresponding to each Gitaly server must be installed on that Gitaly server. -Additionally the certificate, or its certificate authority, must be installed on all Gitaly servers -(including the Gitaly server using the certificate) and on all Gitaly clients -that communicate with it following the procedure described in -[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) (and repeated below). +Additionally, the certificate (or its certificate authority) must be installed on all: -NOTE: **Note** -The certificate must specify the address you use to access the -Gitaly server. If you are addressing the Gitaly server by a hostname, you can -either use the Common Name field for this, or add it as a Subject Alternative -Name. If you are addressing the Gitaly server by its IP address, you must add it -as a Subject Alternative Name to the certificate. -[gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). +- Gitaly servers, including the Gitaly server using the certificate. +- Gitaly clients that communicate with it. -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +The process is documented in the +[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) +and repeated below. + +Note the following: + +- The certificate must specify the address you use to access the Gitaly server. If you are: + - Addressing the Gitaly server by a hostname, you can either use the Common Name field for this, + or add it as a Subject Alternative Name. + - Addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to + the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). +- You can configure Gitaly servers with both an unencrypted listening address `listen_addr` and an + encrypted listening address `tls_listen_addr` at the same time. This allows you to gradually + transition from unencrypted to encrypted traffic if necessary. To configure Gitaly with TLS: **For Omnibus GitLab** 1. Create certificates for Gitaly servers. -1. On the Gitaly clients, copy the certificates, or their certificate authority, into the `/etc/gitlab/trusted-certs`: +1. On the Gitaly clients, copy the certificates (or their certificate authority) into + `/etc/gitlab/trusted-certs`: ```shell sudo cp cert.pem /etc/gitlab/trusted-certs/ @@ -542,7 +573,8 @@ To configure Gitaly with TLS: ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate there: +1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate + there: ```shell sudo mkdir -p /etc/gitlab/ssl @@ -551,8 +583,9 @@ To configure Gitaly with TLS: sudo chmod 644 key.pem cert.pem ``` -1. Copy all Gitaly server certificates, or their certificate authority, to `/etc/gitlab/trusted-certs` so Gitaly server will trust the certificate when -calling into itself or other Gitaly servers: +1. Copy all Gitaly server certificates (or their certificate authority) to + `/etc/gitlab/trusted-certs` so that Gitaly servers will trust the certificate when calling into themselves + or other Gitaly servers: ```shell sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/ @@ -572,10 +605,13 @@ calling into itself or other Gitaly servers: ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. (Optional) After [verifying that all Gitaly traffic is being served over TLS](#observe-type-of-gitaly-connections), - you can improve security by disabling non-TLS connections by commenting out - or deleting `gitaly['listen_addr']` in `/etc/gitlab/gitlab.rb`, saving the file, - and [reconfiguring GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Verify Gitaly traffic is being served over TLS by + [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). +1. (Optional) Improve security by: + 1. Disabling non-TLS connections by commenting out or deleting `gitaly['listen_addr']` in + `/etc/gitlab/gitlab.rb`. + 1. Saving the file. + 1. [Reconfiguring GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). **For installations from source** @@ -605,9 +641,9 @@ calling into itself or other Gitaly servers: ``` NOTE: **Note:** - `/some/dummy/path` should be set to a local folder that exists, however no - data will be stored in this folder. This will no longer be necessary after - [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. + `/some/dummy/path` should be set to a local folder that exists, however no data will be stored + in this folder. This will no longer be necessary after + [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). 1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add: @@ -625,7 +661,9 @@ calling into itself or other Gitaly servers: sudo chmod 644 key.pem cert.pem ``` -1. Copy all Gitaly server certificates, or their certificate authority, to the system trusted certificates so Gitaly server will trust the certificate when calling into itself or other Gitaly servers. +1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted + certificates folder so Gitaly server will trust the certificate when calling into itself or other Gitaly + servers. ```shell sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt @@ -643,15 +681,18 @@ calling into itself or other Gitaly servers: ``` 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). -1. (Optional) After [verifying that all Gitaly traffic is being served over TLS](#observe-type-of-gitaly-connections), - you can improve security by disabling non-TLS connections by commenting out - or deleting `listen_addr` in `/home/git/gitaly/config.toml`, saving the file, - and [restarting GitLab](../restart_gitlab.md#installations-from-source). +1. Verify Gitaly traffic is being served over TLS by + [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). +1. (Optional) Improve security by: + 1. Disabling non-TLS connections by commenting out or deleting `listen_addr` in + `/home/git/gitaly/config.toml`. + 1. Saving the file. + 1. [Restarting GitLab](../restart_gitlab.md#installations-from-source). ### Observe type of Gitaly connections -To observe what type of connections are actually being used in a -production environment you can use the following Prometheus query: +[Prometheus](../monitoring/prometheus/index.md) can be used observe what type of connections Gitaly +is serving a production environment. Use the following Prometheus query: ```prometheus sum(rate(gitaly_connections_total[5m])) by (type) @@ -660,24 +701,26 @@ sum(rate(gitaly_connections_total[5m])) by (type) ## `gitaly-ruby` Gitaly was developed to replace the Ruby application code in GitLab. -In order to save time and/or avoid the risk of rewriting existing -application logic, in some cases we chose to copy some application code -from GitLab into Gitaly almost as-is. To be able to run that code, -`gitaly-ruby` was created, which is a "sidecar" process for the main Gitaly Go -process. Some examples of things that are implemented in `gitaly-ruby` are -RPCs that deal with wikis, and RPCs that create commits on behalf of -a user, such as merge commits. -### Number of `gitaly-ruby` workers +To save time and avoid the risk of rewriting existing application logic, we chose to copy some +application code from GitLab into Gitaly. + +To be able to run that code, `gitaly-ruby` was created, which is a "sidecar" process for the main +Gitaly Go process. Some examples of things that are implemented in `gitaly-ruby` are: + +- RPCs that deal with wikis. +- RPCs that create commits on behalf of a user, such as merge commits. + +### Configure number of `gitaly-ruby` workers -`gitaly-ruby` has much less capacity than Gitaly itself. If your Gitaly -server has to handle a lot of requests, the default setting of having -just one active `gitaly-ruby` sidecar might not be enough. If you see -`ResourceExhausted` errors from Gitaly, it's very likely that you have not -enough `gitaly-ruby` capacity. +`gitaly-ruby` has much less capacity than Gitaly implemented in Go. If your Gitaly server has to handle lots of +requests, the default setting of having just one active `gitaly-ruby` sidecar might not be enough. -You can increase the number of `gitaly-ruby` processes on your Gitaly -server with the following settings. +If you see `ResourceExhausted` errors from Gitaly, it's very likely that you have not enough +`gitaly-ruby` capacity. + +You can increase the number of `gitaly-ruby` processes on your Gitaly server with the following +settings: **For Omnibus GitLab** @@ -702,13 +745,16 @@ server with the following settings. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). -## Limiting RPC concurrency +## Limit RPC concurrency + +Clone traffic can put a large strain on your Gitaly service. The bulk of the work gets done in the +either of the following RPCs: + +- `SSHUploadPack` (for Git SSH). +- `PostUploadPack` (for Git HTTP). -It can happen that CI clone traffic puts a large strain on your Gitaly -service. The bulk of the work gets done in the SSHUploadPack (for Git -SSH) and PostUploadPack (for Git HTTP) RPC's. To prevent such workloads -from overcrowding your Gitaly server you can set concurrency limits in -Gitaly's configuration file. +To prevent such workloads from overwhelming your Gitaly server, you can set concurrency limits in +Gitaly's configuration file. For example: ```ruby # in /etc/gitlab/gitlab.rb @@ -725,226 +771,250 @@ gitaly['concurrency'] = [ ] ``` -This will limit the number of in-flight RPC calls for the given RPC's. -The limit is applied per repository. In the example above, each on the -Gitaly server can have at most 20 simultaneous `PostUploadPack` calls in -flight, and the same for `SSHUploadPack`. If another request comes in for -a repository that has used up its 20 slots, that request will get -queued. +This limits the number of in-flight RPC calls for the given RPCs. The limit is applied per +repository. In the example above: + +- Each repository served by the Gitaly server can have at most 20 simultaneous `PostUploadPack` RPC + calls in flight, and the same for `SSHUploadPack`. +- If another request comes in for a repository that has used up its 20 slots, that request gets + queued. + +You can observe the behavior of this queue using the Gitaly logs and Prometheus: -You can observe the behavior of this queue via the Gitaly logs and via -Prometheus. In the Gitaly logs, you can look for the string (or -structured log field) `acquire_ms`. Messages that have this field are -reporting about the concurrency limiter. In Prometheus, look for the -`gitaly_rate_limiting_in_progress`, `gitaly_rate_limiting_queued` and -`gitaly_rate_limiting_seconds` metrics. +- In the Gitaly logs, look for the string (or structured log field) `acquire_ms`. Messages that have + this field are reporting about the concurrency limiter. +- In Prometheus, look for the following metrics: -The name of the Prometheus metric is not quite right because this is a -concurrency limiter, not a rate limiter. If a Gitaly client makes 1000 requests -in a row in a very short timespan, the concurrency will not exceed 1, -and this mechanism (the concurrency limiter) will do nothing. + - `gitaly_rate_limiting_in_progress`. + - `gitaly_rate_limiting_queued`. + - `gitaly_rate_limiting_seconds`. -## Rotating a Gitaly authentication token +NOTE: **Note:** +Though the name of the Prometheus metric contains `rate_limiting`, it is a concurrency limiter, not +a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency will not +exceed 1 and the concurrency limiter has no effect. + +## Rotate Gitaly authentication token + +Rotating credentials in a production environment often requires downtime, causes outages, or both. -Rotating credentials in a production environment often either requires -downtime, or causes outages, or both. If you are careful, though, you -*can* rotate Gitaly credentials without a service interruption. +However, you can rotate Gitaly credentials without a service interruption. Rotating a Gitaly +authentication token involves: -This procedure also works if you are running GitLab on a single server. -In that case, "Gitaly server" and "Gitaly client" refers to the same -machine. +- [Verifying authentication monitoring](#verify-authentication-monitoring). +- [Enabling "auth transitioning" mode](#enable-auth-transitioning-mode). +- [Updating Gitaly authentication tokens](#update-gitaly-authentication-token). +- [Ensuring there are no authentication failures](#ensure-there-are-no-authentication-failures). +- [Disabling "auth transitioning" mode](#disable-auth-transitioning-mode). +- [Verifying authentication is enforced](#verify-authentication-is-enforced). -### 1. Monitor current authentication behavior +This procedure also works if you are running GitLab on a single server. In that case, "Gitaly +server" and "Gitaly client" refers to the same machine. -Use Prometheus to see what the current authentication behavior of your -GitLab installation is. +### Verify authentication monitoring + +Before rotating a Gitaly authentication token, verify that you can monitor the authentication +behavior of your GitLab installation using Prometheus. Use the following Prometheus query: ```prometheus sum(rate(gitaly_authentications_total[5m])) by (enforced, status) ``` -In a system where authentication is configured correctly, and where you -have live traffic, you will see something like this: +In a system where authentication is configured correctly and where you have live traffic, you will +see something like this: ```prometheus {enforced="true",status="ok"} 4424.985419441742 ``` -There may also be other numbers with rate 0. We only care about the -non-zero numbers. +There may also be other numbers with rate 0. We only care about the non-zero numbers. -The only non-zero number should have `enforced="true",status="ok"`. If -you have other non-zero numbers, something is wrong in your -configuration. +The only non-zero number should have `enforced="true",status="ok"`. If you have other non-zero +numbers, something is wrong in your configuration. -The `status="ok"` number reflects your current request rate. In the example -above, Gitaly is handling about 4000 requests per second. +The `status="ok"` number reflects your current request rate. In the example above, Gitaly is +handling about 4000 requests per second. -Now you have established that you can monitor the Gitaly authentication -behavior of your GitLab installation. +Now that you have established that you can monitor the Gitaly authentication behavior of your GitLab +installation, you can begin the rest of the procedure. -### 2. Reconfigure all Gitaly servers to be in "auth transitioning" mode +### Enable "auth transitioning" mode -The second step is to temporarily disable authentication on the Gitaly servers. +Temporarily disable Gitaly authentication on the Gitaly servers by putting them into "auth +transitioning" mode as follows: ```ruby # in /etc/gitlab/gitlab.rb gitaly['auth_transitioning'] = true ``` -After you have applied this, your Prometheus query should return -something like this: +After you have made this change, your [Prometheus query](#verify-authentication-monitoring) +should return something like: ```prometheus {enforced="false",status="would be ok"} 4424.985419441742 ``` -Because `enforced="false"`, it will be safe to start rolling out the new -token. +Because `enforced="false"`, it is safe to start rolling out the new token. -### 3. Update Gitaly token on all clients and servers +### Update Gitaly authentication token -```ruby -# in /etc/gitlab/gitlab.rb +To update to a new Gitaly authentication token, on each Gitaly client **and** Gitaly server: -gitaly['auth_token'] = 'my new secret token' -``` +1. Update the configuration: + + ```ruby + # in /etc/gitlab/gitlab.rb + + gitaly['auth_token'] = '<new secret token>' + ``` -Remember to apply this on both your Gitaly clients *and* servers. If you -check your Prometheus query while this change is being rolled out, you -will see non-zero values for the `enforced="false",status="denied"` counter. +1. Restart Gitaly: -### 4. Use Prometheus to ensure there are no authentication failures + ```shell + gitlab-ctl restart gitaly + ``` + +If you run your [Prometheus query](#verify-authentication-monitoring) while this change is +being rolled out, you will see non-zero values for the `enforced="false",status="denied"` counter. -After you applied the Gitaly token change everywhere, and all services -involved have been restarted, you should will temporarily see a mix of -`status="would be ok"` and `status="denied"`. +### Ensure there are no authentication failures -After the new token has been picked up by all Gitaly clients and -servers, the **only non-zero rate** should be -`enforced="false",status="would be ok"`. +After the new token is set, and all services involved have been restarted, you will +[temporarily see](#verify-authentication-monitoring) a mix of: -### 5. Disable "auth transitioning" Mode +- `status="would be ok"`. +- `status="denied"`. -Now we turn off the 'auth transitioning' mode. These final steps are -important: without them, you have **no authentication**. +After the new token has been picked up by all Gitaly clients and Gitaly servers, the +**only non-zero rate** should be `enforced="false",status="would be ok"`. -Update the configuration on your Gitaly servers: +### Disable "auth transitioning" mode + +To re-enable Gitaly authentication, disable "auth transitioning" mode. Update the configuration on +your Gitaly servers as follows: ```ruby # in /etc/gitlab/gitlab.rb gitaly['auth_transitioning'] = false ``` -### 6. Verify that authentication is enforced again +CAUTION: **Caution:** +Without completing this step, you have **no Gitaly authentication**. + +### Verify authentication is enforced -Refresh your Prometheus query. You should now see the same kind of -result as you did in the beginning: +Refresh your [Prometheus query](#verify-authentication-monitoring). You should now see a similar +result as you did at the start. For example: ```prometheus {enforced="true",status="ok"} 4424.985419441742 ``` -Note that `enforced="true"`, meaning that authentication is being enforced. +Note that `enforced="true"` means that authentication is being enforced. -## Direct Git access in GitLab Rails +## Direct Git access bypassing Gitaly -Also known as "the Rugged patches". +While it is possible to access Gitaly repositories stored on disk directly with a Git client, +it is not advisable because Gitaly is being continuously improved and changed. Theses improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss. + +Gitaly has optimizations, such as the +[`info/refs` advertisement cache](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/design_diskcache.md), +that rely on Gitaly controlling and monitoring access to repositories via the +official gRPC interface. Likewise, Praefect has optimizations, such as fault +tolerance and distributed reads, that depend on the gRPC interface and +database to determine repository state. + +For these reasons, **accessing repositories directly is done at your own risk +and is not supported**. + +## Direct access to Git in GitLab + +Direct access to Git uses code in GitLab known as the "Rugged patches". ### History -Before Gitaly existed, the things that are now Gitaly clients used to -access Git repositories directly. Either on a local disk in the case of -e.g. a single-machine Omnibus GitLab installation, or via NFS in the -case of a horizontally scaled GitLab installation. +Before Gitaly existed, what are now Gitaly clients used to access Git repositories directly, either: + +- On a local disk in the case of a single-machine Omnibus GitLab installation +- Using NFS in the case of a horizontally-scaled GitLab installation. -Besides running plain `git` commands, in GitLab Rails we also used to -use a Ruby gem (library) called +Besides running plain `git` commands, GitLab used to use a Ruby library called [Rugged](https://github.com/libgit2/rugged). Rugged is a wrapper around -[libgit2](https://libgit2.org/), a stand-alone implementation of Git in -the form of a C library. - -Over time it has become clear to use that Rugged, and particularly -Rugged in combination with the [Unicorn](https://yhbt.net/unicorn/) -web server, is extremely efficient. Because libgit2 is a *library* and -not an external process, there was very little overhead between GitLab -application code that tried to look up data in Git repositories, and the -Git implementation itself. - -Because Rugged+Unicorn was so efficient, GitLab's application code ended -up with lots of duplicate Git object lookups (like looking up the -`master` commit a dozen times in one request). We could write -inefficient code without being punished for it. - -When we migrated these Git lookups to Gitaly calls, we were suddenly -getting a much higher fixed cost per Git lookup. Even when Gitaly is -able to re-use an already-running `git` process to look up e.g. a commit -you still have the cost of a network roundtrip to Gitaly, and within -Gitaly a write/read roundtrip on the Unix pipes that connect Gitaly to -the `git` process. - -Using GitLab.com performance as our yardstick, we pushed down the number -of Gitaly calls per request until the loss of Rugged's efficiency was no -longer felt. It also helped that we run Gitaly itself directly on the -Git file severs, rather than via NFS mounts: this gave us a speed boost -that counteracted the negative effect of not using Rugged anymore. - -Unfortunately, some *other* deployments of GitLab could not ditch NFS -like we did on GitLab.com and they got the worst of both worlds: the -slowness of NFS and the increased inherent overhead of Gitaly. - -As a performance band-aid for these stuck-on-NFS deployments, we -re-introduced some of the old Rugged code that got deleted from -GitLab Rails during the Gitaly migration project. These pieces of -re-introduced code are informally referred to as "the Rugged patches". - -### Activation of direct Git access in GitLab Rails - -The Ruby methods that perform direct Git access are hidden behind [feature -flags](../../development/gitaly.md#legacy-rugged-code). These feature -flags are off by default. It is not good if you need to know about -feature flags to get the best performance so in a second iteration, we -added an automatic mechanism that will enable direct Git access. - -When GitLab Rails calls a function that has a Rugged patch it performs -two checks. The result of both of these checks is cached. - -1. Is the feature flag for this patch set in the database? If so, do - what the feature flag says. -1. If the feature flag is not set (i.e. neither true nor false), try to - see if we can access filesystem underneath the Gitaly server - directly. If so, use the Rugged patch. - -To see if GitLab Rails can access the repository filesystem directly, we use -the following heuristic: - -- Gitaly ensures that the filesystem has a metadata file in its root - with a UUID in it. -- Gitaly reports this UUID to GitLab Rails via the `ServerInfo` RPC. -- GitLab Rails tries to read the metadata file directly. If it exists, - and if the UUID's match, assume we have direct access. - -Because of the way the UUID check works, and because Omnibus GitLab will -fill in the correct repository paths in the GitLab Rails config file -`config/gitlab.yml`, **direct Git access in GitLab Rails is on by default in -Omnibus**. - -### Plans to remove direct Git access in GitLab Rails - -For the sake of removing complexity it is desirable that we get rid of -direct Git access in GitLab Rails. For as long as some GitLab installations are stuck -with Git repositories on slow NFS, however, we cannot just remove them. - -There are two prongs to our efforts to remove direct Git access in GitLab Rails: - -1. Reduce the number of (inefficient) Gitaly queries made by - GitLab Rails. -1. Persuade everybody who runs a Highly Available / horizontally scaled - GitLab installation to move off of NFS. - -The second prong is the only real solution. For this we need [Gitaly -HA](https://gitlab.com/groups/gitlab-org/-/epics?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Gitaly%20HA), -which is still under development as of December 2019. +[libgit2](https://libgit2.org/), a stand-alone implementation of Git in the form of a C library. + +Over time it became clear that Rugged, particularly in combination with +[Unicorn](https://yhbt.net/unicorn/), is extremely efficient. Because `libgit2` is a library and +not an external process, there was very little overhead between: + +- GitLab application code that tried to look up data in Git repositories. +- The Git implementation itself. + +Because the combination of Rugged and Unicorn was so efficient, GitLab's application code ended up with lots of +duplicate Git object lookups. For example, looking up the `master` commit a dozen times in one +request. We could write inefficient code without poor performance. + +When we migrated these Git lookups to Gitaly calls, we suddenly had a much higher fixed cost per Git +lookup. Even when Gitaly is able to re-use an already-running `git` process (for example, to look up +a commit), you still have: + +- The cost of a network roundtrip to Gitaly. +- Within Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process. + +Using GitLab.com to measure, we reduced the number of Gitaly calls per request until the loss of +Rugged's efficiency was no longer felt. It also helped that we run Gitaly itself directly on the Git +file severs, rather than via NFS mounts. This gave us a speed boost that counteracted the negative +effect of not using Rugged anymore. + +Unfortunately, other deployments of GitLab could not remove NFS like we did on GitLab.com, and they +got the worst of both worlds: + +- The slowness of NFS. +- The increased inherent overhead of Gitaly. + +The code removed from GitLab during the Gitaly migration project affected these deployments. As a +performance workaround for these NFS-based deployments, we re-introduced some of the old Rugged +code. This re-introduced code is informally referred to as the "Rugged patches". + +### How it works + +The Ruby methods that perform direct Git access are behind +[feature flags](../../development/gitaly.md#legacy-rugged-code), disabled by default. It wasn't +convenient to set feature flags to get the best performance, so we added an automatic mechanism that +enables direct Git access. + +When GitLab calls a function that has a "Rugged patch", it performs two checks: + +- Is the feature flag for this patch set in the database? If so, the feature flag setting controls + GitLab's use of "Rugged patch" code. +- If the feature flag is not set, GitLab tries accessing the filesystem underneath the + Gitaly server directly. If it can, it will use the "Rugged patch". + +The result of both of these checks is cached. + +To see if GitLab can access the repository filesystem directly, we use the following heuristic: + +- Gitaly ensures that the filesystem has a metadata file in its root with a UUID in it. +- Gitaly reports this UUID to GitLab via the `ServerInfo` RPC. +- GitLab Rails tries to read the metadata file directly. If it exists, and if the UUID's match, + assume we have direct access. + +Direct Git access is enable by default in Omnibus GitLab because it fills in the correct repository +paths in the GitLab configuration file `config/gitlab.yml`. This satisfies the UUID check. + +### Transition to Gitaly Cluster + +For the sake of removing complexity, we must remove direct Git access in GitLab. However, we can't +remove it as long some GitLab installations require Git repositories on NFS. + +There are two facets to our efforts to remove direct Git access in GitLab: + +- Reduce the number of inefficient Gitaly queries made by GitLab. +- Persuade administrators of fault-tolerant or horizontally-scaled GitLab instances to migrate off + NFS. + +The second facet presents the only real solution. For this, we developed +[Gitaly Cluster](praefect.md). ## Troubleshooting Gitaly diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 3d4e606205e..1f97cd304f9 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -35,8 +35,8 @@ The availability objectives for Gitaly clusters are: Writes are replicated asynchronously. Any writes that have not been replicated to the newly promoted primary are lost. - [Strong Consistency](https://gitlab.com/groups/gitlab-org/-/epics/1189) is - planned to improve this to "no loss". + [Strong consistency](#strong-consistency) can be used to avoid loss in some + circumstances. - **Recovery Time Objective (RTO):** Less than 10 seconds. @@ -103,7 +103,7 @@ GitLab](https://about.gitlab.com/install/). You will need the IP/host address for each node. -1. `LOAD_BALANCER_SERVER_ADDRESS`: the IP/hots address of the load balancer +1. `LOAD_BALANCER_SERVER_ADDRESS`: the IP/host address of the load balancer 1. `POSTGRESQL_SERVER_ADDRESS`: the IP/host address of the PostgreSQL server 1. `PRAEFECT_HOST`: the IP/host address of the Praefect server 1. `GITALY_HOST`: the IP/host address of each Gitaly server @@ -131,14 +131,13 @@ with secure tokens as you complete the setup process. Praefect cluster directly; that could lead to data loss. 1. `PRAEFECT_SQL_PASSWORD`: this password is used by Praefect to connect to PostgreSQL. -1. `GRAFANA_PASSWORD`: this password is used to access the `admin` - account in the Grafana dashboards. We will note in the instructions below where these secrets are required. ### PostgreSQL -NOTE: **Note:** do not store the GitLab application database and the Praefect +NOTE: **Note:** +Do not store the GitLab application database and the Praefect database on the same PostgreSQL server if using [Geo](../geo/replication/index.md). The replication state is internal to each instance of GitLab and should not be replicated. @@ -283,9 +282,16 @@ application server, or a Gitaly node. 1. Configure the **Praefect** cluster to connect to each Gitaly node in the cluster by editing `/etc/gitlab/gitlab.rb`. - In the example below we have configured one virtual storage (or shard) named - `storage-1`. This cluster has three Gitaly nodes `gitaly-1`, `gitaly-2`, and - `gitaly-3`, which will be replicas of each other. + The virtual storage's name must match the configured storage name in GitLab + configuration. In a later step, we configure the storage name as `default` + so we use `default` here as well. This cluster has three Gitaly nodes `gitaly-1`, + `gitaly-2`, and `gitaly-3`, which will be replicas of each other. + + CAUTION: **Caution:** + If you have data on an already existing storage called + `default`, you should configure the virtual storage with another name and + [migrate the data to the Praefect storage](#migrating-existing-repositories-to-praefect) + afterwards. Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which will be used by Praefect when communicating with Gitaly nodes in the cluster. This token is @@ -296,7 +302,8 @@ application server, or a Gitaly node. More Gitaly nodes can be added to the cluster to increase the number of replicas. More clusters can also be added for very large GitLab instances. - NOTE: **Note:** The `gitaly-1` node is currently denoted the primary. This + NOTE: **Note:** + The `gitaly-1` node is currently denoted the primary. This can be used to manually fail from one node to another. This will be removed in the [future](https://gitlab.com/gitlab-org/gitaly/-/issues/2634). @@ -304,7 +311,7 @@ application server, or a Gitaly node. # Name of storage hash must match storage name in git_data_dirs on GitLab # server ('praefect') and in git_data_dirs on Gitaly nodes ('gitaly-1') praefect['virtual_storages'] = { - 'storage-1' => { + 'default' => { 'gitaly-1' => { 'address' => 'tcp://GITALY_HOST:8075', 'token' => 'PRAEFECT_INTERNAL_TOKEN', @@ -322,6 +329,8 @@ application server, or a Gitaly node. } ``` +1. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2013) in GitLab 13.1 and later, enable [distribution of reads](#distributed-reads). + 1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure): @@ -349,9 +358,146 @@ application server, or a Gitaly node. **The steps above must be completed for each Praefect node!** +## Enabling TLS support + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/1698) in GitLab 13.2. + +Praefect supports TLS encryption. To communicate with a Praefect instance that listens +for secure connections, you must: + +- Use a `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry + in the GitLab configuration. +- Bring your own certificates because this isn't provided automatically. The certificate + corresponding to each Praefect server must be installed on that Praefect server. + +Additionally the certificate, or its certificate authority, must be installed on all Gitaly servers +and on all Praefect clients that communicate with it following the procedure described in +[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) (and repeated below). + +Note the following: + +- The certificate must specify the address you use to access the Praefect server. If + addressing the Praefect server by: + + - Hostname, you can either use the Common Name field for this, or add it as a Subject + Alternative Name. + - IP address, you must add it as a Subject Alternative Name to the certificate. + +- You can configure Praefect servers with both an unencrypted listening address + `listen_addr` and an encrypted listening address `tls_listen_addr` at the same time. + This allows you to do a gradual transition from unencrypted to encrypted traffic, if + necessary. + +To configure Praefect with TLS: + +**For Omnibus GitLab** + +1. Create certificates for Praefect servers. +1. On the Praefect servers, create the `/etc/gitlab/ssl` directory and copy your key + and certificate there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add: + + ```ruby + praefect['tls_listen_addr'] = "0.0.0.0:3305" + praefect['certificate_path'] = "/etc/gitlab/ssl/cert.pem" + praefect['key_path'] = "/etc/gitlab/ssl/key.pem" + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. On the Praefect clients (including each Gitaly server), copy the certificates, + or their certificate authority, into `/etc/gitlab/trusted-certs`: + + ```shell + sudo cp cert.pem /etc/gitlab/trusted-certs/ + ``` + +1. On the Praefect clients (except Gitaly servers), edit `git_data_dirs` in + `/etc/gitlab/gitlab.rb` as follows: + + ```ruby + git_data_dirs({ + 'default' => { 'gitaly_address' => 'tls://praefect1.internal:3305' }, + 'storage1' => { 'gitaly_address' => 'tls://praefect2.internal:3305' }, + }) + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +**For installations from source** + +1. Create certificates for Praefect servers. +1. On the Praefect servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate + there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + +1. On the Praefect clients (including each Gitaly server), copy the certificates, + or their certificate authority, into the system trusted certificates: + + ```shell + sudo cp cert.pem /usr/local/share/ca-certificates/praefect.crt + sudo update-ca-certificates + ``` + +1. On the Praefect clients (except Gitaly servers), edit `storages` in + `/home/git/gitlab/config/gitlab.yml` as follows: + + ```yaml + gitlab: + repositories: + storages: + default: + gitaly_address: tls://praefect1.internal:3305 + path: /some/dummy/path + storage1: + gitaly_address: tls://praefect2.internal:3305 + path: /some/dummy/path + ``` + + NOTE: **Note:** + `/some/dummy/path` should be set to a local folder that exists, however no + data will be stored in this folder. This will no longer be necessary after + [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. + +1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Copy all Praefect server certificates, or their certificate authority, to the system + trusted certificates on each Gitaly server so the Praefect server will trust the + certificate when called by Gitaly servers: + + ```shell + sudo cp cert.pem /usr/local/share/ca-certificates/praefect.crt + sudo update-ca-certificates + ``` + +1. Edit `/home/git/praefect/config.toml` and add: + + ```toml + tls_listen_addr = '0.0.0.0:3305' + + [tls] + certificate_path = '/etc/gitlab/ssl/cert.pem' + key_path = '/etc/gitlab/ssl/key.pem' + ``` + +1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). + ### Gitaly -NOTE: **Note:** Complete these steps for **each** Gitaly node. +NOTE: **Note:** +Complete these steps for **each** Gitaly node. To complete this section you will need: @@ -555,6 +701,17 @@ Particular attention should be shown to: external_url 'GITLAB_SERVER_URL' ``` +1. Disable the default Gitaly service running on the GitLab host. It won't be needed + as GitLab will connect to the configured cluster. + + CAUTION: **Caution:** + If you have existing data stored on the default Gitaly storage, + you should [migrate the data your Praefect storage first](#migrating-existing-repositories-to-praefect). + + ```ruby + gitaly['enable'] = false + ``` + 1. Add the Praefect cluster as a storage location by editing `/etc/gitlab/gitlab.rb`. @@ -562,28 +719,17 @@ Particular attention should be shown to: - `LOAD_BALANCER_SERVER_ADDRESS` with the IP address or hostname of the load balancer. - - `GITLAB_HOST` with the IP address or hostname of the GitLab server - `PRAEFECT_EXTERNAL_TOKEN` with the real secret ```ruby git_data_dirs({ "default" => { - "gitaly_address" => "tcp://GITLAB_HOST:8075" - }, - "storage-1" => { "gitaly_address" => "tcp://LOAD_BALANCER_SERVER_ADDRESS:2305", "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' } }) ``` -1. Allow Gitaly to listen on a TCP port by editing - `/etc/gitlab/gitlab.rb` - - ```ruby - gitaly['listen_addr'] = '0.0.0.0:8075' - ``` - 1. Configure the `gitlab_shell['secret_token']` so that callbacks from Gitaly nodes during a `git push` are properly authenticated by editing `/etc/gitlab/gitlab.rb`: @@ -632,14 +778,6 @@ Particular attention should be shown to: gitlab-ctl reconfigure ``` -1. To ensure that Gitaly [has updated its Prometheus listen - address](https://gitlab.com/gitlab-org/gitaly/-/issues/2734), [restart - Gitaly](../restart_gitlab.md#omnibus-gitlab-restart): - - ```shell - gitlab-ctl restart gitaly - ``` - 1. Verify each `gitlab-shell` on each Gitaly instance can reach GitLab. On each Gitaly instance run: ```shell @@ -652,16 +790,11 @@ Particular attention should be shown to: gitlab-rake gitlab:gitaly:check ``` -1. Update the **Repository storage** settings from **Admin Area > Settings > - Repository > Repository storage** to make the newly configured Praefect - cluster the storage location for new Git repositories. - - - The default option is unchecked. - - The Praefect option is checked. +1. Check in **Admin Area > Settings > Repository > Repository storage** that the Praefect storage + is configured to store new repositories. Following this guide, the `default` storage should have + weight 100 to store all new repositories. - ![Update repository storage](img/praefect_storage_v12_10.png) - -1. Verify everything is still working by creating a new project. Check the +1. Verify everything is working by creating a new project. Check the "Initialize repository with a README" box so that there is content in the repository that viewed. If the project is created, and you can see the README file, it works! @@ -712,6 +845,72 @@ To get started quickly: Congratulations! You've configured an observable highly available Praefect cluster. +## Distributed reads + +> Introduced in GitLab 13.1 in [beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga) with feature flag `gitaly_distributed_reads` set to disabled. + +Praefect supports distribution of read operations across Gitaly nodes that are +configured for the virtual node. + +To allow for [performance testing](https://gitlab.com/gitlab-org/quality/performance/-/issues/231), +distributed reads are currently in +[beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga) and disabled by +default. To enable distributed reads, the `gitaly_distributed_reads` +[feature flag](../feature_flags.md) must be enabled in a Ruby console: + +```ruby +Feature.enable(:gitaly_distributed_reads) +``` + +If enabled, all RPCs marked with `ACCESSOR` option like +[GetBlob](https://gitlab.com/gitlab-org/gitaly/-/blob/v12.10.6/proto/blob.proto#L16) +are redirected to an up to date and healthy Gitaly node. + +_Up to date_ in this context means that: + +- There is no replication operations scheduled for this node. +- The last replication operation is in _completed_ state. + +If there is no such nodes, or any other error occurs during node selection, the primary +node will be chosen to serve the request. + +To track distribution of read operations, you can use the `gitaly_praefect_read_distribution` +Prometheus counter metric. It has two labels: + +- `virtual_storage`. +- `storage`. + +They reflect configuration defined for this instance of Praefect. + +## Strong consistency + +> Introduced in GitLab 13.1 in [alpha](https://about.gitlab.com/handbook/product/#alpha-beta-ga), disabled by default. + +Praefect guarantees eventual consistency by replicating all writes to secondary nodes +after the write to the primary Gitaly node has happened. + +Praefect can instead provide strong consistency by creating a transaction and writing +changes to all Gitaly nodes at once. Strong consistency is currently in +[alpha](https://about.gitlab.com/handbook/product/#alpha-beta-ga) and not enabled by +default. If enabled, transactions are only available for a subset of RPCs. For more +information, see the [strong consistency epic](https://gitlab.com/groups/gitlab-org/-/epics/1189). + +To enable strong consistency: + +- In GitLab 13.2 and later, enable the `:gitaly_reference_transactions` feature flag. +- In GitLab 13.1, enable the `:gitaly_reference_transactions` and `:gitaly_hooks_rpc` + feature flags. + +Enabling feature flags requires [access to the Rails console](../feature_flags.md#start-the-gitlab-rails-console). +In the Rails console, enable or disable the flags as required. For example: + +```ruby +Feature.enable(:gitaly_reference_transactions) +``` + +To monitor strong consistency, use the `gitaly_praefect_transactions_total` and +`gitaly_praefect_transactions_delay_seconds` Prometheus counter metrics. + ## Automatic failover and leader election Praefect regularly checks the health of each backend Gitaly node. This @@ -739,38 +938,68 @@ current primary node is found to be unhealthy. It is likely that we will implement support for Consul, and a cloud native strategy in the future. -## Identifying Impact of a Primary Node Failure +## Primary Node Failure -When a primary Gitaly node fails, there is a chance of data loss. Data loss can occur if there were outstanding replication jobs the secondaries did not manage to process before the failure. The `dataloss` Praefect sub-command helps identify these cases by counting the number of dead replication jobs for each repository. This command must be executed on a Praefect node. +Praefect recovers from a failing primary Gitaly node by promoting a healthy secondary as the new primary. To minimize data loss, Praefect elects the secondary with the least unreplicated writes from the primary. There can still be some unreplicated writes, leading to data loss. -A time frame to search can be specified with `-from` and `-to`: +Praefect switches a virtual storage in to read-only mode after a failover event. This eases data recovery efforts by preventing new, possibly conflicting writes to the newly elected primary. This allows the administrator to attempt recovering the lost data before allowing new writes. + +If you prefer write availability over consistency, this behavior can be turned off by setting `praefect['failover_read_only_after_failover'] = false` in `/etc/gitlab/gitlab.rb` and [reconfiguring Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +### Checking for data loss + +The Praefect `dataloss` sub-command helps identify lost writes by checking for uncompleted replication jobs. This is useful for identifying possible data loss cases after a failover. This command must be executed on a Praefect node. ```shell -sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss -from <rfc3339-time> -to <rfc3339-time> +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss [-virtual-storage <virtual-storage>] ``` -If the time frame is not specified, dead replication jobs from the last six hours are counted: +If the virtual storage is not specified, every configured virtual storage is checked for data loss. ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss +``` -Failed replication jobs between [2020-01-02 00:00:00 +0000 UTC, 2020-01-02 06:00:00 +0000 UTC): -@hashed/fa/53/fa539965395b8382145f8370b34eab249cf610d2d6f2943c95b9b9d08a63d4a3.git: 2 jobs +```shell +Virtual storage: default + Current read-only primary: gitaly-2 + Previous write-enabled primary: gitaly-1 + Nodes with data loss from failing over from gitaly-1: + @hashed/2c/62/2c624232cdd221771294dfbb310aca000a0df6ac8b66b696d90ef06fdefb64a3.git: gitaly-0 + @hashed/4b/22/4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a.git: gitaly-0, gitaly-2 ``` -To specify a time frame in UTC, run: +Currently `dataloss` only considers a repository up to date if it has been directly replicated to from the previous write-enabled primary. While reconciling from an up to date secondary can recover the data, this is not visible in the data loss report. This is due for improvement via [Gitaly#2866](https://gitlab.com/gitlab-org/gitaly/-/issues/2866). + +NOTE: **Note:** +`dataloss` is still in beta and the output format is subject to change. + +### Checking repository checksums + +To check a project's repository checksums across on all Gitaly nodes, run the +[replicas Rake task](../raketasks/praefect.md#replica-checksums) on the main GitLab node. + +### Recovering lost writes + +The Praefect `reconcile` sub-command can be used to recover lost writes from the +previous primary once it is back online. This is only possible when the virtual storage +is still in read-only mode. ```shell -sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss -from 2020-01-02T00:00:00+00:00 -to 2020-01-02T00:02:00+00:00 +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml reconcile -virtual <virtual-storage> -reference <previous-primary> -target <current-primary> -f ``` -### Checking repository checksums +Refer to [Backend Node Recovery](#backend-node-recovery) section for more details on +the `reconcile` sub-command. + +### Enabling Writes -To check a project's repository checksums across on all Gitaly nodes, the -replicas Rake task can be run on the main GitLab node: +Any data recovery attempts should have been made before enabling writes to eliminate +any chance of conflicting writes. Virtual storage can be re-enabled for writes by using +the Praefect `enable-writes` sub-command. ```shell -sudo gitlab-rake "gitlab:praefect:replicas[project_id]" +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml enable-writes -virtual-storage <virtual-storage> ``` ## Backend Node Recovery diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 52fd6fa6900..0429149ec2d 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -91,7 +91,7 @@ certificate_path = '/home/git/cert.cert' key_path = '/home/git/key.pem' ``` -[Read more](index.md#tls-support) about TLS in Gitaly. +[Read more](index.md#enable-tls-support) about TLS in Gitaly. ### Storage |