diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index b9711245bab302d75b3aa274347f8034487a15e1..16ae0d8606e5ad038621cf71711c5fd8b0fa25c8 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/index.md @@ -116,7 +116,7 @@ for details. To use TLS certificates with Let's Encrypt, you can manually point the domain to one of the Geo sites, generate the certificate, then copy it to all other sites. -- Using Geo secondary sites to accelerate runners is not officially supported. Support for this functionality is planned and can be tracked in [epic 9779](https://gitlab.com/groups/gitlab-org/-/epics/9779). If a replication lag occurs between the primary and secondary site, and the pipeline ref is not available on the secondary site when the job is executed, the job will fail. +- Using Geo secondary sites to accelerate runners is experimental and is not recommended for production. It can be configured and tested by following the steps in [secondary proxy runners](runners.md). Progress toward general availability can be tracked in [epic 9779](https://gitlab.com/groups/gitlab-org/-/epics/9779). - When secondary proxying is used together with separate URLs, [signing in the secondary site using SAML](../replication/single_sign_on.md#saml-with-separate-url-with-proxying-enabled) diff --git a/doc/administration/geo/secondary_proxy/runners.md b/doc/administration/geo/secondary_proxy/runners.md new file mode 100644 index 0000000000000000000000000000000000000000..6dfd61778e7a02878e8b2dcfef2b3b6c99de741d --- /dev/null +++ b/doc/administration/geo/secondary_proxy/runners.md @@ -0,0 +1,40 @@ +--- +stage: Systems +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Secondary runners **(PREMIUM SELF EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415179) in GitLab 16.7 [with a flag](../../feature_flags.md) named `geo_proxy_check_pipeline_refs`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, an administrator can [enable the feature flag](../../feature_flags.md) named `geo_proxy_check_pipeline_refs`. On GitLab.com, this feature is not available. + +With [Geo proxying for secondary sites](index.md), it is possible to register a `gitlab-runner` with a secondary site. This offloads load from the primary instance. + +## Enable or disable secondary runners + +To enable secondary runners, SSH into a Rails node on the **primary** Geo site and run: + +```ruby +sudo gitlab-rails runner 'Feature.enable(:geo_proxy_check_pipeline_refs)' +``` + +To disable secondary runners, SSH into a Rails node on the **primary** Geo site and run: + +```ruby +sudo gitlab-rails runner `Feature.disable(:geo_proxy_check_pipeline_refs)` +``` + +## Use secondary runners with a Location Aware public URL (Unified URL) + +Using a [Location Aware public URL](location_aware_external_url.md), with the feature flag enabled works with no extra configuration. After you install and register a runner in the same location as a secondary site, it automatically talks to the closest site, and only proxies to the primary if the secondary is out of date. + +## Use secondary runners with separate URLs + +Using separate secondary URLs, the runners should be: + +1. Registered with the secondary external URL. +1. Configured with [`clone_url`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#how-clone_url-works) set to the `external_url` of the secondary instance.