diff options
Diffstat (limited to 'doc/administration/gitaly/index.md')
| -rw-r--r-- | doc/administration/gitaly/index.md | 156 |
1 files changed, 137 insertions, 19 deletions
diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 48929910a9c..5732b6a1ca4 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -2,8 +2,7 @@ [Gitaly](https://gitlab.com/gitlab-org/gitaly) (introduced in GitLab 9.0) is a service that provides high-level RPC access to Git -repositories. As of GitLab 9.3 it is still an optional component with -limited scope. +repositories. Gitaly is a mandatory component in GitLab 9.4 and newer. GitLab components that access Git repositories (gitlab-rails, gitlab-shell, gitlab-workhorse) act as clients to Gitaly. End users do @@ -33,36 +32,155 @@ prometheus_listen_addr = "localhost:9236" Changes to `/home/git/gitaly/config.toml` are applied when you run `service gitlab restart`. -## Configuring GitLab to not use Gitaly +## Running Gitaly on its own server -Gitaly is still an optional component in GitLab 9.3. This means you -can choose to not use it. +> This is an optional way to deploy Gitaly which can benefit GitLab +installations that are larger than a single machine. Most +installations will be better served with the default configuration +used by Omnibus and the GitLab source installation guide. -In Omnibus you can make the following change in -`/etc/gitlab/gitlab.rb` and reconfigure. This will both disable the -Gitaly service and configure the rest of GitLab not to use it. +Starting with GitLab 9.4 it is possible to run Gitaly on a different +server from the rest of the application. This can improve performance +when running GitLab with its repositories stored on an NFS server. + +At the moment (GitLab 9.4) Gitaly is not yet a replacement for NFS +because some parts of GitLab still bypass Gitaly when accessing Git +repositories. If you choose to deploy Gitaly on your NFS server you +must still also mount your Git shares on your GitLab application +servers. + +Gitaly network traffic is unencrypted so you should use a firewall to +restrict access to your Gitaly server. + +Below we describe how to configure a Gitaly server at address +`gitaly.internal:9999` with secret token `abc123secret`. We assume +your GitLab installation has two repository storages, `default` and +`storage1`. + +### Client side token configuration + +Start by configuring a token on the client side. + +Omnibus installations: ```ruby -gitaly['enable'] = false +# /etc/gitlab/gitlab.rb +gitlab_rails['gitaly_token'] = 'abc123secret' +``` + +Source installations: + +```yaml +# /home/git/gitlab/config/gitlab.yml +gitlab: + gitaly: + token: 'abc123secret' +``` + +You need to reconfigure (Omnibus) or restart (source) for these +changes to be picked up. + +### Gitaly server configuration + +Next, on the Gitaly server, we need to configure storage paths, enable +the network listener and configure the token. + +Note: if you want to reduce the risk of downtime when you enable +authentication you can temporarily disable enforcement, see [the +documentation on configuring Gitaly +authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md#authentication) +. + +In most or all cases the storage paths below end in `/repositories`. Check the +directory layout on your Gitaly server to be sure. + +Omnibus installations: + +```ruby +# /etc/gitlab/gitlab.rb +gitaly['listen_addr'] = '0.0.0.0:9999' +gitaly['auth_token'] = 'abc123secret' +gitaly['storage'] = [ + { 'name' => 'default', 'path' => '/path/to/default/repositories' }, + { 'name' => 'storage1', 'path' => '/path/to/storage1/repositories' }, +] +``` + +Source installations: + +```toml +# /home/git/gitaly/config.toml +listen_addr = '0.0.0.0:9999' + +[auth] +token = 'abc123secret' + +[[storage] +name = 'default' +path = '/path/to/default/repositories' + +[[storage]] +name = 'storage1' +path = '/path/to/storage1/repositories' ``` -In source installations, edit `/home/git/gitlab/config/gitlab.yml` and -make sure `enabled` in the `gitaly` section is set to 'false'. This -does not disable the Gitaly service in your init script; it only -prevents it from being used. +Again, reconfigure (Omnibus) or restart (source). + +### Converting clients to use the Gitaly server -Apply the change with `service gitlab restart`. +Now as the final step update the client machines to switch from using +their local Gitaly service to the new Gitaly server you just +configured. This is a risky step because if there is any sort of +network, firewall, or name resolution problem preventing your GitLab +server from reaching the Gitaly server then all Gitaly requests will +fail. + +We assume that your Gitaly server can be reached at +`gitaly.internal:9999` from your GitLab server, and that your GitLab +NFS shares are mounted at `/mnt/gitlab/default` and +`/mnt/gitlab/storage1` respectively. + +Omnibus installations: + +```ruby +# /etc/gitlab/gitlab.rb +git_data_dirs({ + { 'default' => { 'path' => '/mnt/gitlab/default', 'gitaly_address' => 'tcp://gitlab.internal:9999' } }, + { 'storage1' => { 'path' => '/mnt/gitlab/storage1', 'gitaly_address' => 'tcp://gitlab.internal:9999' } }, +}) + +gitlab_rails['gitaly_token'] = 'abc123secret' +``` + +Source installations: ```yaml +# /home/git/gitlab/config/gitlab.yml +gitlab: + repositories: + storages: + default: + path: /mnt/gitlab/default/repositories + gitaly_address: tcp://gitlab.internal:9999 + storage1: + path: /mnt/gitlab/storage1/repositories + gitaly_address: tcp://gitlab.internal:9999 + gitaly: - enabled: false + token: 'abc123secret' ``` +Now reconfigure (Omnibus) or restart (source). When you tail the +Gitaly logs on your Gitaly server (`sudo gitlab-ctl tail gitaly` or +`tail -f /home/git/gitlab/log/gitaly.log`) you should see requests +coming in. One sure way to trigger a Gitaly request is to clone a +repository from your GitLab server over HTTP. + ## Disabling or enabling the Gitaly service -Be careful: if you disable Gitaly without instructing the rest of your -GitLab installation not to use Gitaly, you may end up with errors -because GitLab tries to access a service that is not running. +If you are running Gitaly [as a remote +service](#running-gitaly-on-its-own-server) you may want to disable +the local Gitaly service that runs on your Gitlab server by default. To disable the Gitaly service in your Omnibus installation, add the following line to `/etc/gitlab/gitlab.rb`: @@ -81,4 +199,4 @@ following to `/etc/default/gitlab`: gitaly_enabled=false ``` -When you run `service gitlab restart` Gitaly will be disabled.
\ No newline at end of file +When you run `service gitlab restart` Gitaly will be disabled. |