diff --git a/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png b/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png new file mode 100644 index 00000000000..4b04ba8d1f1 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png differ diff --git a/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png b/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png new file mode 100644 index 00000000000..c19ad57c953 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png differ diff --git a/doc/administration/geo/replication/img/single_git_clone_panel.png b/doc/administration/geo/replication/img/single_git_clone_panel.png new file mode 100644 index 00000000000..8aa0bd2f7d8 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_clone_panel.png differ diff --git a/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png b/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png new file mode 100644 index 00000000000..a554532f3b8 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png differ diff --git a/doc/administration/geo/replication/img/single_git_created_policy_record.png b/doc/administration/geo/replication/img/single_git_created_policy_record.png new file mode 100644 index 00000000000..74c42395e15 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_created_policy_record.png differ diff --git a/doc/administration/geo/replication/img/single_git_name_policy.png b/doc/administration/geo/replication/img/single_git_name_policy.png new file mode 100644 index 00000000000..1a976539e94 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_name_policy.png differ diff --git a/doc/administration/geo/replication/img/single_git_policy_diagram.png b/doc/administration/geo/replication/img/single_git_policy_diagram.png new file mode 100644 index 00000000000..d62952dbbb3 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_policy_diagram.png differ diff --git a/doc/administration/geo/replication/img/single_git_traffic_policies.png b/doc/administration/geo/replication/img/single_git_traffic_policies.png new file mode 100644 index 00000000000..b3193c23d99 Binary files /dev/null and b/doc/administration/geo/replication/img/single_git_traffic_policies.png differ diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index 58d99863192..0de7691e461 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -229,6 +229,10 @@ For more information on Geo security, see [Geo security review](security_review. For more information on tuning Geo, see [Tuning Geo](tuning.md). +### Set up a location-aware Git URL + +For an example of how to set up a location-aware Git remote URL with AWS Route53, see [Location-aware Git remote URL with AWS Route53](location_aware_git_url.md). + ## Remove Geo node For more information on removing a Geo node, see [Removing **secondary** Geo nodes](remove_geo_node.md). diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md new file mode 100644 index 00000000000..b8ed3d07bdd --- /dev/null +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -0,0 +1,120 @@ +# Location-aware Git remote URL with AWS Route53 **(PREMIUM ONLY)** + +You can provide GitLab users with a single remote URL that automatically uses +the Geo node closest to them. This means users don't need to update their Git +configuration to take advantage of closer Geo nodes as they move. + +This is possible because, Git push requests can be automatically redirected +(HTTP) or proxied (SSH) from **secondary** nodes to the **primary** node. + +Though these instructions use [AWS Route53](https://aws.amazon.com/route53/), +other services such as [Cloudflare](https://www.cloudflare.com/) could be used +as well. + +NOTE: **Note** +You can also use a load balancer to distribute web UI or API traffic to +[multiple Geo **secondary** nodes](../../../user/admin_area/geo_nodes.md#multiple-secondary-nodes-behind-a-load-balancer). +Importantly, the **primary** node cannot yet be included. See the feature request +[Support putting the **primary** behind a Geo node load balancer](https://gitlab.com/gitlab-org/gitlab/issues/10888). + +## Prerequisites + +In this example, we have already set up: + +- `primary.example.com` as a Geo **primary** node. +- `secondary.example.com` as a Geo **secondary** node. + +We will create a `git.example.com` subdomain that will automatically direct +requests: + +- From Europe to the **secondary** node. +- From all other locations to the **primary** node. + +In any case, you require: + +- A working GitLab **primary** node that is accessible at its own address. +- A working GitLab **secondary** node. +- A Route53 Hosted Zone managing your domain. + +If you have not yet setup a Geo **primary** node and **secondary** node, please consult +[the Geo setup instructions](https://docs.gitlab.com/ee/administration/geo/replication/#setup-instructions). + +## Create a traffic policy + +In a Route53 Hosted Zone, traffic policies can be used to set up a variety of +routing configurations. + +1. Navigate to the +[Route53 dashboard](https://console.aws.amazon.com/route53/home) and click +**Traffic policies**. + + ![Traffic policies](img/single_git_traffic_policies.png) + +1. Click the **Create traffic policy** button. + + ![Name policy](img/single_git_name_policy.png) + +1. Fill in the **Policy Name** field with `Single Git Host` and click **Next**. + + ![Policy diagram](img/single_git_policy_diagram.png) + +1. Leave **DNS type** as `A: IP Address in IPv4 format`. +1. Click **Connect to...** and select **Geolocation rule**. + + ![Add geolocation rule](img/single_git_add_geolocation_rule.png) + +1. For the first **Location**, leave it as `Default`. +1. Click **Connect to...** and select **New endpoint**. +1. Choose **Type** `value` and fill it in with ``. +1. For the second **Location**, choose `Europe`. +1. Click **Connect to...** and select **New endpoint**. +1. Choose **Type** `value` and fill it in with ``. + + ![Add traffic policy endpoints](img/single_git_add_traffic_policy_endpoints.png) + +1. Click **Create traffic policy**. + + ![Create policy records with traffic policy](img/single_git_create_policy_records_with_traffic_policy.png) + +1. Fill in **Policy record DNS name** with `git`. +1. Click **Create policy records**. + + ![Created policy record](img/single_git_created_policy_record.png) + +You have successfully set up a single host, e.g. `git.example.com` which +distributes traffic to your Geo nodes by geolocation! + +## Configure Git clone URLs to use the special Git URL + +When a user clones a repository for the first time, they typically copy the Git +remote URL from the project page. By default, these SSH and HTTP URLs are based +on the external URL of the current host. For example: + +- `git@secondary.example.com:group1/project1.git` +- `https://secondary.example.com/group1/project1.git` + +![Clone panel](img/single_git_clone_panel.png) + +However, you can customize the SSH remote URL to use the location-aware +`git.example.com`. To do so, change the SSH remote URL's host by setting +`gitlab_rails['gitlab_ssh_host']` in `gitlab.rb` of web nodes. + +Unfortunately the means to specify a custom HTTP clone URL is not yet +implemented. The feature request can be found at +[Customizable Git HTTP clone root URL](https://gitlab.com/gitlab-org/gitlab/issues/31949). + +## Example Git request handling behavior + +After following the configuration steps above, handling for Git requests is now location aware. +For requests: + +- Outside Europe, all requests are directed to the **primary** node. +- Within Europe, over: + - HTTP: + - `git clone http://git.example.com/foo/bar.git` is directed to the **secondary** node. + - `git push` is initially directed to the **secondary**, which automatically + redirects to `primary.example.com`. + - SSH: + - `git clone git@git.example.com:foo/bar.git` is directed to the **secondary**. + - `git push` is initially directed to the **secondary**, which automatically + proxies the request to `primary.example.com`.