diff options
Diffstat (limited to 'doc/administration')
197 files changed, 1491 insertions, 1899 deletions
diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md index 88e39a50b6c..d04056beb96 100644 --- a/doc/administration/application_settings_cache.md +++ b/doc/administration/application_settings_cache.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application cache interval **(FREE SELF)** diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md index 9ec7b81bfd0..ca60b6142fe 100644 --- a/doc/administration/audit_event_streaming.md +++ b/doc/administration/audit_event_streaming.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming **(ULTIMATE)** @@ -831,3 +831,49 @@ X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN> "event_type": "project_group_link_destroy" } ``` + +## Audit event streaming on invalid merge request approver state + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374566) in GitLab 15.5. + +Stream audit events that relate to invalid merge request approver states within a project. + +### Headers + +Headers are formatted as follows: + +```plaintext +POST /logs HTTP/1.1 +Host: <DESTINATION_HOST> +Content-Type: application/x-www-form-urlencoded +X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN> +X-Gitlab-Audit-Event-Type: audit_operation +``` + +### Example payload + +```json +{ + "id": 1, + "author_id": 1, + "entity_id": 6, + "entity_type": "Project", + "details": { + "author_name": "example_username", + "target_id": 20, + "target_type": "MergeRequest", + "target_details": { title: "Merge request title", iid: "Merge request iid", id: "Merge request id" }, + "custom_message": "Invalid merge request approver rules", + "ip_address": "127.0.0.1", + "entity_path": "example-group/example-project" + }, + "ip_address": "127.0.0.1", + "author_name": "example_username", + "entity_path": "example-group/example-project", + "target_details": "merge request title", + "created_at": "2022-03-09T06:53:11.181Z", + "target_type": "MergeRequest", + "target_id": 20, + "event_type": "audit_operation" +} +``` diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index b6c267bfd0c..11600bc2da6 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit Events **(PREMIUM)** diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index e363e7862ea..8e91466d345 100644 --- a/doc/administration/audit_reports.md +++ b/doc/administration/audit_reports.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to create evidence artifacts typically requested by a 3rd party auditor.' --- diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index bd48cfdbc4f..a047e7c1f0b 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auditor users **(PREMIUM SELF)** diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 1d20d87bdf4..b02ac06b67f 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian OmniAuth Provider **(FREE SELF)** @@ -11,7 +11,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu ## Atlassian application registration -1. Go to <https://developer.atlassian.com/console/myapps/> and sign-in with the Atlassian +1. Go to the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) and sign-in with the Atlassian account to administer the application. 1. Select **Create a new app**. 1. Choose an App Name, such as 'GitLab', and select **Create**. @@ -51,8 +51,8 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu { name: "atlassian_oauth2", # label: "Provider name", # optional label for login button, defaults to "Atlassian" - app_id: "YOUR_CLIENT_ID", - app_secret: "YOUR_CLIENT_SECRET", + app_id: "<your_client_id>", + app_secret: "<your_client_secret>", args: { scope: "offline_access read:jira-user read:jira-work", prompt: "consent" } } ] @@ -63,13 +63,13 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu ```yaml - { name: "atlassian_oauth2", # label: "Provider name", # optional label for login button, defaults to "Atlassian" - app_id: "YOUR_CLIENT_ID", - app_secret: "YOUR_CLIENT_SECRET", + app_id: "<your_client_id>", + app_secret: "<your_client_secret>", args: { scope: "offline_access read:jira-user read:jira-work", prompt: "consent" } } ``` -1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in [application registration](#atlassian-application-registration) steps. +1. Change `<your_client_id>` and `<your_client_secret>` to the Client credentials you received during [application registration](#atlassian-application-registration). 1. Save the configuration file. 1. For the changes to take effect: diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 61ce2b5ab25..1ac62b06fe7 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -2,12 +2,12 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authentiq OmniAuth Provider **(FREE SELF)** -To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq. +To enable the Authentiq OmniAuth provider for passwordless authentication, you must register an application with Authentiq. Authentiq generates a Client ID and the accompanying Client Secret for you to use. @@ -38,8 +38,8 @@ Authentiq generates a Client ID and the accompanying Client Secret for you to us { name: "authentiq", # label: "Provider name", # optional label for login button, defaults to "Authentiq" - app_id: "YOUR_CLIENT_ID", - app_secret: "YOUR_CLIENT_SECRET", + app_id: "<your_client_id>", + app_secret: "<your_client_secret>", args: { "scope": 'aq:name email~rs address aq:push' } @@ -52,22 +52,28 @@ Authentiq generates a Client ID and the accompanying Client Secret for you to us ```yaml - { name: 'authentiq', # label: 'Provider name', # optional label for login button, defaults to "Authentiq" - app_id: 'YOUR_CLIENT_ID', - app_secret: 'YOUR_CLIENT_SECRET', + app_id: '<your_client_id>', + app_secret: '<your_client_secret>', args: { scope: 'aq:name email~rs address aq:push' } } ``` -1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits. +1. The `scope` is set to request the: + - User's name. + - Required and signed email. + - Permission to send push notifications to sign in on subsequent visits. + See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers. -1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in step 1. +1. Change `<your_client_id>` and `<your_client_secret>` to the Client credentials you received from Authentiq. 1. Save the configuration file. -1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. +1. For the changes to take effect: + - [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed GitLab using Omnibus. + - [Restart GitLab](../restart_gitlab.md#installations-from-source) if you installed GitLab from source. On the sign in page there should now be an Authentiq icon below the regular sign in form. Select the icon to begin the authentication process. If the user: @@ -77,7 +83,7 @@ icon to begin the authentication process. If the user: 1. Decide what personal details to share. 1. Sign in to your GitLab installation. - Does not have the app installed, they are prompted to download the app and then follow the - procedure above. + previous procedure. If everything works, the user is returned to GitLab and is signed in. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index db8cdd3e7bb..bb06d5d1a58 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -2,41 +2,42 @@ type: concepts, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Amazon Web Services Cognito **(FREE SELF)** Amazon Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance. -The following documentation enables Cognito as an OAuth2 provider. +The following documentation enables Cognito as an OAuth 2.0 provider. ## Configure AWS Cognito -To enable the [AWS Cognito](https://aws.amazon.com/cognito/) OAuth2 OmniAuth provider, register your application with Cognito. This process generates a Client ID and Client Secret for your application. -Any settings you configure in the following procedure can be modified later. -The following steps enable AWS Cognito as an authentication provider: +To enable the [AWS Cognito](https://aws.amazon.com/cognito/) OAuth 2.0 OmniAuth provider, register your application with Cognito. This process generates a Client ID and Client Secret for your application. +To enable AWS Cognito as an authentication provider, complete the following steps. You can modify any settings you configure later. 1. Sign in to the [AWS console](https://console.aws.amazon.com/console/home). -1. Select **Cognito** from the **Services** menu. -1. Select **Manage User Pools**, and select the **Create a user pool** button in the top right corner. -1. Enter the pool name and then select the **Step through settings** button. +1. From the **Services** menu, select **Cognito**. +1. Select **Manage User Pools** and then select **Create a user pool** in the top right corner. +1. Enter the user pool name and then select **Step through settings**. 1. Under **How do you want your end users to sign in?**, select **Email address or phone number** and **Allow email addresses**. 1. Under **Which standard attributes do you want to require?**, select **email**. -1. Go to the next steps of configuration and set the rest of the settings to suit your needs - in the basic setup they are not related to GitLab configuration. -1. In the **App clients** settings, select **Add an app client**, add **App client name** and select the **Enable username password based authentication** checkbox. +1. Configure the remaining settings to suit your needs. In the basic setup, these settings do not affect GitLab configuration. +1. In the **App clients** settings: + 1. Select **Add an app client**. + 1. Add the **App client name**. + 1. Select the **Enable username password based authentication** checkbox. 1. Select **Create app client**. -1. In the next step, you can set up AWS Lambda functions for sending emails. You can then finish creating the pool. +1. Set up the AWS Lambda functions for sending emails and finish creating the user pool. 1. After creating the user pool, go to **App client settings** and provide the required information: - **Enabled Identity Providers** - select all - - **Callback URL** - `https://gitlab.example.com/users/auth/cognito/callback` - - Substitute the URL of your GitLab instance for `gitlab.example.com` + - **Callback URL** - `https://<your_gitlab_instance_url>/users/auth/cognito/callback` - **Allowed OAuth Flows** - Authorization code grant - **Allowed OAuth2 Scopes** - `email`, `openid`, and `profile` 1. Save changes for the app client settings. -1. Under **Domain name** include the AWS domain name for your AWS Cognito application. -1. Under **App Clients**, find your app client ID and app client secret. These values correspond to the OAuth2 Client ID and Client Secret. Save these values. +1. Under **Domain name**, include the AWS domain name for your AWS Cognito application. +1. Under **App Clients**, find your app client ID. Select **Show details* to display the app client secret. These values correspond to the OAuth 2.0 Client ID and Client Secret. Save these values. ## Configure GitLab @@ -49,8 +50,13 @@ The following steps enable AWS Cognito as an authentication provider: sudo editor /etc/gitlab/gitlab.rb ``` -1. In the following code block, substitute the Client ID (`app_id`), Client Secret (`app_secret`), and the Amazon domain name (`site`) for your AWS Cognito application. -Include the code block in the `/etc/gitlab/gitlab.rb` file: +1. In the following code block, enter your AWS Cognito application information in the following parameters: + + - `app_id`: Your client ID. + - `app_secret`: Your client secret. + - `site`: Your Amazon domain and region. + + Include the code block in the `/etc/gitlab/gitlab.rb` file: ```ruby gitlab_rails['omniauth_allow_single_sign_on'] = ['cognito'] @@ -59,12 +65,12 @@ Include the code block in the `/etc/gitlab/gitlab.rb` file: name: "cognito", label: "Provider name", # optional label for login button, defaults to "Cognito" icon: nil, # Optional icon URL - app_id: "CLIENT ID", - app_secret: "CLIENT SECRET", + app_id: "<client_id>", + app_secret: "<client_secret>", args: { scope: "openid profile email", client_options: { - site: "https://your_domain.auth.your_region.amazoncognito.com", + site: "https://<your_domain>.auth.<your_region>.amazoncognito.com", authorize_url: "/oauth2/authorize", token_url: "/oauth2/token", user_info_url: "/oauth2/userInfo" @@ -84,8 +90,9 @@ Include the code block in the `/etc/gitlab/gitlab.rb` file: 1. Save the configuration file. 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. -Your sign-in page should now display a Cognito button below the regular sign-in form. -To begin the authentication process, select the icon, and AWS Cognito asks the user to sign in and authorize the GitLab application. -If successful, the user is redirected and signed in to your GitLab instance. +Your sign-in page should now display a Cognito option below the regular sign-in form. +Select this option to begin the authentication process. +AWS Cognito then asks you to sign in and authorize the GitLab application. +If the authorization is successful, you're redirected and signed in to your GitLab instance. For more information, see [Configure initial settings](../../integration/omniauth.md#configure-initial-settings). diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index ced7cdb7119..4395309e91e 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian Crowd OmniAuth provider (deprecated) **(FREE SELF)** diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 2644e3a1f50..307d9a4518d 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -3,7 +3,7 @@ comments: false type: index stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab authentication and authorization **(FREE SELF)** diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 71ab084065a..c7e7253ef72 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # JWT OmniAuth provider **(FREE SELF)** diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 7f399f7e730..2077c6f7baf 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Secure LDAP **(FREE SELF)** diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 19f656d2f14..3bb9350e960 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate LDAP with GitLab **(FREE SELF)** @@ -13,7 +13,7 @@ to support user authentication. This integration works with most LDAP-compliant directory servers, including: - Microsoft Active Directory. - [Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) + [Microsoft Active Directory Trusts](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported. - Apple Open Directory. - Open LDAP. @@ -98,7 +98,7 @@ gitlab_rails['ldap_servers'] = { 'main' => { 'label' => 'LDAP', 'host' => 'ldap.mydomain.com', - 'port' => 389, + 'port' => 636, 'uid' => 'sAMAccountName', 'encryption' => 'simple_tls', 'verify_certificates' => true, @@ -312,7 +312,7 @@ To limit access to the nested members of an Active Directory group, use the foll ``` For more information about `LDAP_MATCHING_RULE_IN_CHAIN` filters, see -[Search Filter Syntax](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax). +[Search Filter Syntax](https://learn.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax). Support for nested members in the user filter shouldn't be confused with [group sync nested groups](ldap_synchronization.md#supported-ldap-group-typesattributes) support. diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index a68e6ae2649..0ec482648a9 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting LDAP **(FREE SELF)** @@ -866,3 +866,36 @@ To enable debug output in the rails console, [enter the rails console](#rails-co ```ruby Rails.logger.level = Logger::DEBUG ``` + +#### Get all error messages associated with groups, subgroups, members, and requesters + +Collect error messages associated with groups, subgroups, members, and requesters. This +captures error messages that may not appear in the Web interface. This can be especially helpful +for troubleshooting issues with [LDAP group sync](ldap_synchronization.md#group-sync) +and unexpected behavior with users and their membership in groups and subgroups. + +```ruby +# Find the group and subgroup +group = Group.find_by_full_path("parent_group") +subgroup = Group.find_by_full_path("parent_group/child_group") + +# Group and subgroup errors +group.valid? +group.errors.map(&:full_messages) + +subgroup.valid? +subgroup.errors.map(&:full_messages) + +# Group and subgroup errors for the members AND requesters +group.requesters.map(&:valid?) +group.requesters.map(&:errors).map(&:full_messages) +group.members.map(&:valid?) +group.members.map(&:errors).map(&:full_messages) +group.members_and_requesters.map(&:errors).map(&:full_messages) + +subgroup.requesters.map(&:valid?) +subgroup.requesters.map(&:errors).map(&:full_messages) +subgroup.members.map(&:valid?) +subgroup.members.map(&:errors).map(&:full_messages) +subgroup.members_and_requesters.map(&:errors).map(&:full_messages) +``` diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 37a27fc058e..af2b1400670 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP synchronization **(PREMIUM SELF)** diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 9f3c96902f8..bb263512e06 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -2,14 +2,16 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OpenID Connect OmniAuth provider **(FREE SELF)** -GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider. +GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) +as an OmniAuth provider. -To enable the OpenID Connect OmniAuth provider, you must register your application with an OpenID Connect provider. +To enable the OpenID Connect OmniAuth provider, you must register your application +with an OpenID Connect provider. The OpenID Connect provides you with a client's details and secret for you to use. 1. On your GitLab server, open the configuration file. @@ -27,7 +29,7 @@ The OpenID Connect provides you with a client's details and secret for you to us sudo -u git -H editor config/gitlab.yml ``` - See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings. +1. [Configure initial settings](../../integration/omniauth.md#configure-initial-settings). 1. Add the provider configuration. @@ -83,32 +85,51 @@ The OpenID Connect provides you with a client's details and secret for you to us ``` NOTE: - For more information on each configuration option refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage) - and the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). + For more information on each configuration option, refer to the: + + - [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage). + - [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). + +1. For the provider configuration, change the values for the provider to match your + OpenID Connect client setup. Use the following as a guide: -1. For the configuration above, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide: - `<your_oidc_label>` is the label that appears on the login page. - - `<custom_provider_icon>` (optional) is the icon that appears on the login page. Icons for the major social login platforms are built-in into GitLab, - but can be overridden by specifying this parameter. Both local paths and absolute URLs are accepted. - - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`. - If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`. - - If `discovery` is set to `true`, the OpenID Connect provider attempts to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`. - - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider. + - `<custom_provider_icon>` (optional) is the icon that appears on the login page. + Icons for the major social login platforms are built into GitLab, + but you can override these icons by specifying this parameter. GitLab accepts both + local paths and absolute URLs. + - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect + provider (for example, `https://example.com/auth/realms/your-realm`). + If this value is not provided, the URL is constructed from `client_options` + in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`. + - If `discovery` is set to `true`, the OpenID Connect provider attempts to automatically + discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. + Defaults to `false`. + - `client_auth_method` (optional) specifies the method used for authenticating + the client with the OpenID Connect provider. - Supported values are: - - `basic` - HTTP Basic Authentication - - `jwt_bearer` - JWT based authentication (private key and client secret signing) - - `mtls` - Mutual TLS or X.509 certificate validation - - Any other value POSTs the client ID and secret in the request body - - If not specified, defaults to `basic`. - - `<uid_field>` (optional) is the field name from the `user_info.raw_attributes` that defines the value for `uid`. For example, `preferred_username`. - If this value is not provided or the field with the configured value is missing from the `user_info.raw_attributes` details, the `uid` uses the `sub` field. - - `send_scope_to_token_endpoint` is `true` by default. In other words, the `scope` parameter is normally included in requests to the token endpoint. - However, if your OpenID Connect provider does not accept the `scope` parameter in such requests, set this to `false`. + - `basic` - HTTP Basic Authentication. + - `jwt_bearer` - JWT-based authentication (private key and client secret signing). + - `mtls` - Mutual TLS or X.509 certificate validation. + - Any other value posts the client ID and secret in the request body. + - If not specified, this value defaults to `basic`. + - `<uid_field>` (optional) is the field name from `user_info.raw_attributes` + that defines the value for `uid` (for example, `preferred_username`). + If you do not provide this value, or the field with the configured value is missing + from the `user_info.raw_attributes` details, `uid` uses the `sub` field. + - `send_scope_to_token_endpoint` is `true` by default, so the `scope` parameter + is normally included in requests to the token endpoint. + However, if your OpenID Connect provider does not accept the `scope` parameter + in such requests, set this to `false`. - `client_options` are the OpenID Connect client-specific options. Specifically: - `identifier` is the client identifier as configured in the OpenID Connect service provider. - - `secret` is the client secret as configured in the OpenID Connect service provider. - - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`. - - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful. + - `secret` is the client secret as configured in the OpenID Connect service provider. For example, + [OmniAuth OpenIDConnect](https://github.com/omniauth/omniauth_openid_connect)) requires this. If the service provider doesn't require a secret, + provide any value and it is ignored. + - `redirect_uri` is the GitLab URL to redirect the user to after successful login + (for example, `http://example.com/users/auth/openid_connect/callback`). + - `end_session_endpoint` (optional) is the URL to the endpoint that ends the + session. You can provide this URL if auto-discovery is disabled or unsuccessful. - The following `client_options` are optional unless auto-discovery is disabled or unsuccessful: - `authorization_endpoint` is the URL to the endpoint that authorizes the end user. - `token_endpoint` is the URL to the endpoint that provides Access Token. @@ -116,20 +137,22 @@ The OpenID Connect provides you with a client's details and secret for you to us - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys. 1. Save the configuration file. -1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) - for the changes to take effect if you installed GitLab via Omnibus or from source respectively. +1. For changes to take effect, if you installed GitLab: + + - With Omnibus, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + - From source, [restart GitLab](../restart_gitlab.md#installations-from-source). -On the sign in page, there should now be an OpenID Connect icon below the regular sign in form. -Select the icon to begin the authentication process. The OpenID Connect provider asks the user to -sign in and authorize the GitLab application (if confirmation required by the client). If everything goes well, the user -is redirected to GitLab and signed in. +On the sign in page, you have an OpenID Connect option below the regular sign in form. +Select this option to begin the authentication process. The OpenID Connect provider +asks you to sign in and authorize the GitLab application if confirmation is required +by the client. You are redirected to GitLab and signed in. ## Example configurations The following configurations illustrate how to set up OpenID with different providers with Omnibus GitLab. -### Google +### Configure Google See the [Google documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect) for more details: @@ -157,16 +180,16 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -### Microsoft Azure +### Configure Microsoft Azure -The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison). -To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you need the -following information: +The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://learn.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison). +To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, +you need the following information: -- A tenant ID. You may already have one. For more information, review the - [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. +- A tenant ID. You may already have one. For more information, see the + [Microsoft Azure Tenant](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. - A client ID and a client secret. Follow the instructions in the - [Microsoft Quickstart Register an Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation + [Microsoft Quickstart Register an Application](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation to obtain the tenant ID, client ID, and client secret for your app. Example Omnibus configuration block: @@ -194,49 +217,51 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -Microsoft has documented how its platform works with [the OIDC protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc). +Microsoft has documented how its platform works with [the OIDC protocol](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc). -### Microsoft Azure Active Directory B2C +### Configure Microsoft Azure Active Directory B2C -While GitLab works with [Azure Active Directory B2C](https://docs.microsoft.com/en-us/azure/active-directory-b2c/overview), it requires special -configuration to work. To get started, sign in to the [Azure Portal](https://portal.azure.com). +GitLab requires special +configuration to work with [Azure Active Directory B2C](https://learn.microsoft.com/en-us/azure/active-directory-b2c/overview). To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you need the following information from Azure: - A tenant ID. You may already have one. For more information, review the - [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. + [Microsoft Azure Tenant](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. - A client ID and a client secret. Follow the instructions in the - [Microsoft tutorial](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga) documentation to obtain the + [Microsoft tutorial](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga) documentation to obtain the client ID and client secret for your app. -- The user flow or policy name. Follow the instructions in the [Microsoft tutorial](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-user-flow). +- The user flow or policy name. Follow the instructions in the [Microsoft tutorial](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-user-flow). -If your GitLab domain is `gitlab.example.com`, ensure the app has the following `Redirect URI`: +Configure the app: -`https://gitlab.example.com/users/auth/openid_connect/callback` +1. Set the app `Redirect URI`. For example, If your GitLab domain is `gitlab.example.com`, + set the app `Redirect URI` to `https://gitlab.example.com/users/auth/openid_connect/callback`. -In addition, ensure that [ID tokens are enabled](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga#enable-id-token-implicit-grant). +1. [Enable the ID tokens](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga#enable-id-token-implicit-grant). -Add the following API permissions to the app: +1. Add the following API permissions to the app: -- `openid` -- `offline_access` + - `openid` + - `offline_access` #### Configure custom policies -Azure B2C [offers two ways of defining the business logic for logging in a user](https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview): +Azure B2C [offers two ways of defining the business logic for logging in a user](https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview): -- [User flows](https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#user-flows) -- [Custom policies](https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#custom-policies) +- [User flows](https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#user-flows) +- [Custom policies](https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#custom-policies) -While cumbersome to configure, custom policies are required because -standard Azure B2C user flows [do not send the OpenID `email` claim](https://github.com/MicrosoftDocs/azure-docs/issues/16566). In -other words, they do not work with the [`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#configure-initial-settings). +Custom policies are required because standard Azure B2C user flows +[do not send the OpenID `email` claim](https://github.com/MicrosoftDocs/azure-docs/issues/16566). +Therefore, the standard user flows do not work with the +[`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#configure-initial-settings). With a standard Azure B2C policy, GitLab cannot create a new account or -link to an existing one with an email address. +link to an existing account with an email address. -Carefully follow the instructions for [creating a custom policy](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy). +First, [create a custom policy](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy). -The Microsoft instructions use `SocialAndLocalAccounts` in the [custom policy starter pack](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#custom-policy-starter-pack), -but `LocalAccounts` works for authenticating against local, Active Directory accounts. Before you follow the instructions to [upload the polices](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies), do the following: +The Microsoft instructions use `SocialAndLocalAccounts` in the [custom policy starter pack](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#custom-policy-starter-pack), +but `LocalAccounts` authenticates against local Active Directory accounts. Before you [upload the polices](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies), do the following: 1. To export the `email` claim, modify the `SignUpOrSignin.xml`. Replace the following line: @@ -250,9 +275,9 @@ but `LocalAccounts` works for authenticating against local, Active Directory acc <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" /> ``` -1. For OIDC discovery to work with B2C, the policy must be configured with an issuer compatible with the +1. For OIDC discovery to work with B2C, configure the policy with an issuer compatible with the [OIDC specification](https://openid.net/specs/openid-connect-discovery-1_0.html#rfc.section.4.3). - See the [token compatibility settings](https://docs.microsoft.com/en-us/azure/active-directory-b2c/configure-tokens?pivots=b2c-custom-policy#token-compatibility-settings). + See the [token compatibility settings](https://learn.microsoft.com/en-us/azure/active-directory-b2c/configure-tokens?pivots=b2c-custom-policy#token-compatibility-settings). In `TrustFrameworkBase.xml` under `JwtIssuer`, set `IssuanceClaimPattern` to `AuthorityWithTfp`: ```xml @@ -268,22 +293,22 @@ but `LocalAccounts` works for authenticating against local, Active Directory acc ... ``` -1. Now [upload the policy](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies). Overwrite +1. [Upload the policy](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies). Overwrite the existing files if you are updating an existing policy. -1. Determine the issuer URL using the sign-in policy. The issuer URL is in the form: +1. To determine the issuer URL, use the sign-in policy. The issuer URL is in the form: ```markdown https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/ ``` - The policy name is lowercased in the URL. For example, `B2C_1A_signup_signin` + The policy name is lowercase in the URL. For example, `B2C_1A_signup_signin` policy appears as `b2c_1a_signup_sigin`. -The trailing forward slash is required. + Ensure you include the trailing forward slash. -1. Verify the operation of the OIDC discovery URL and issuer URL, append `.well-known/openid-configuration` - to the issuer URL: +1. Verify the operation of the OIDC discovery URL and issuer URL and append + `.well-known/openid-configuration` to the issuer URL: ```markdown https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration @@ -327,33 +352,35 @@ The trailing forward slash is required. - Ensure all occurrences of `yourtenant.onmicrosoft.com`, `ProxyIdentityExperienceFrameworkAppId`, and `IdentityExperienceFrameworkAppId` match your B2C tenant hostname and the respective client IDs in the XML policy files. -- Add `https://jwt.ms` as a redirect URI to the app, and use the [custom policy tester](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy). - Make sure the payload includes `email` that matches the user's email access. -- After you enable the custom policy, users might see "Invalid username or password" after they try to sign in. This might be a configuration - issue with the `IdentityExperienceFramework` app. See [this Microsoft comment](https://docs.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy.html?childToView=122370#comment-122370) - that suggests checking that the app manifest contains these settings: +- Add `https://jwt.ms` as a redirect URI to the app, and use the [custom policy tester](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy). + Ensure the payload includes `email` that matches the user's email access. +- After you enable the custom policy, users might see `Invalid username or password` + after they try to sign in. This might be a configuration issue with the `IdentityExperienceFramework` + app. See [this Microsoft comment](https://learn.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy.html?childToView=122370#comment-122370) that suggests you check that the app manifest + contains these settings: - `"accessTokenAcceptedVersion": null` - `"signInAudience": "AzureADMyOrg"` This configuration corresponds with the `Supported account types` setting used when - creating the `IdentityExperienceFramework` app. +creating the `IdentityExperienceFramework` app. -### Keycloak +### Configure Keycloak -GitLab works with OpenID providers that use HTTPS. Although a Keycloak -server can be set up using HTTP, GitLab can only communicate -with a Keycloak server that uses HTTPS. +GitLab works with OpenID providers that use HTTPS. Although you can set up a +Keycloak server that uses HTTP, GitLab can only communicate with a Keycloak server +that uses HTTPS. -We highly recommend configuring Keycloak to use public key encryption algorithms (for example, -RSA256, RSA512, and so on) instead of symmetric key encryption algorithms (for example, HS256 or HS358) to -sign tokens. Public key encryption algorithms are: +Configure Keycloak to use public key encryption algorithms (for example, +RSA256 or RSA512) instead of symmetric key encryption algorithms (for example, +HS256 or HS358) to sign tokens. Public key encryption algorithms are: - Easier to configure. - More secure because leaking the private key has severe security consequences. -The signature algorithm can be configured in the Keycloak administration console under -**Realm Settings > Tokens > Default Signature Algorithm**. +1. Open the Keycloak administration console. +1. Select **Realm Settings > Tokens > Default Signature Algorithm**. +1. Configure the signature algorithm. Example Omnibus configuration block: @@ -385,38 +412,40 @@ gitlab_rails['omniauth_providers'] = [ > Introduced in GitLab 14.2. WARNING: -The instructions below are included for completeness, but symmetric key -encryption should only be used when absolutely necessary. +The following instructions are included for completeness, but only use symmetric key +encryption if absolutely necessary. To use symmetric key encryption: -1. Extract the secret key from the Keycloak database. Keycloak doesn't expose this value in the Web - interface. The client secret seen in the Web interface is the OAuth2 client secret, which is - different from the secret used to sign JSON Web Tokens. - - For example, if you're using PostgreSQL as the backend database for Keycloak, log in to the - database console and extract the key via this SQL query: - - ```sql - $ psql -U keycloak - psql (13.3 (Debian 13.3-1.pgdg100+1)) - Type "help" for help. - - keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret'; - -[ RECORD 1 ]--------------------------------------------------------------------------------- - name | hmac-generated - value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g - -[ RECORD 2 ]--------------------------------------------------------------------------------- - name | fallback-HS384 - value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A - ``` +1. Extract the secret key from the Keycloak database. Keycloak does not expose this + value in the web interface. The client secret seen in the web interface is the + OAuth 2.0 client secret, which is different from the secret used to sign JSON Web Tokens. - In this example, there are two private keys: one for HS256 (`hmac-generated`), and another for - HS384 (`fallback-HS384`). We use the first `value` to configure GitLab. + For example, if you use PostgreSQL as the backend database for Keycloak: -1. Convert `value` to standard base64. As [discussed in the post](https://keycloak.discourse.group/t/invalid-signature-with-hs256-token/3228/9), - `value` is encoded in ["Base 64 Encoding with URL and Filename Safe Alphabet" in RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-5). - This needs to be converted to [standard base64 as defined in RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045). + - Sign into the database console. + - Run the following SQL query to extract the key: + + ```sql + $ psql -U keycloak + psql (13.3 (Debian 13.3-1.pgdg100+1)) + Type "help" for help. + + keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret'; + -[ RECORD 1 ]--------------------------------------------------------------------------------- + name | hmac-generated + value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g + -[ RECORD 2 ]--------------------------------------------------------------------------------- + name | fallback-HS384 + value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A + ``` + + In this example, there are two private keys: one for HS256 (`hmac-generated`) + and another for HS384 (`fallback-HS384`). We use the first `value` to configure GitLab. + +1. Convert `value` to standard base64. As discussed in the [**Invalid signature with HS256 token** post](https://keycloak.discourse.group/t/invalid-signature-with-hs256-token/3228/9), + `value` is encoded in the [**Base 64 Encoding with URL and Filename Safe Alphabet** section](https://datatracker.ietf.org/doc/html/rfc4648#section-5) of RFC 4648. + This must be converted to [standard base64 as defined in RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045). The following Ruby script does this: ```ruby @@ -458,17 +487,19 @@ To use symmetric key encryption: ] ``` -If after reconfiguring, you see the error `JSON::JWS::VerificationFailed` error message, this means -the incorrect secret was specified. +If you see a `JSON::JWS::VerificationFailed` error, +you have specified the wrong secret. ### Casdoor -GitLab works with OpenID providers that use HTTPS. To connect to GitLab using OpenID with Casdoor, use HTTPS instead of HTTP. +GitLab works with OpenID providers that use HTTPS. Use HTTPS to connect to GitLab +through OpenID with Casdoor. For your app, complete the following steps on Casdoor: 1. Get a client ID and a client secret. -1. Add your GitLab redirect URL. For example, if your GitLab domain is `gitlab.example.com`, ensure the Casdoor app has the following +1. Add your GitLab redirect URL. For example, if your GitLab domain is `gitlab.example.com`, + ensure the Casdoor app has the following `Redirect URI`: `https://gitlab.example.com/users/auth/openid_connect/callback`. See the [Casdoor documentation](https://casdoor.org/docs/integration/gitlab) for more details. @@ -520,23 +551,21 @@ Example installations from source configuration (file path: `config/gitlab.yml`) } ``` -## General troubleshooting - -If you're having trouble, here are some tips: +## Troubleshooting -1. Ensure `discovery` is set to `true`. Setting it to `false` requires - specifying all the URLs and keys required to make OpenID work. +1. Ensure `discovery` is set to `true`. If you set it to `false`, you must + specify all the URLs and keys required to make OpenID work. 1. Check your system clock to ensure the time is synchronized properly. -1. As mentioned in [the documentation](https://github.com/m0n9oose/omniauth_openid_connect), +1. As mentioned in [the OmniAuth OpenID Connect documentation](https://github.com/m0n9oose/omniauth_openid_connect), make sure `issuer` corresponds to the base URL of the Discovery URL. For example, `https://accounts.google.com` is used for the URL `https://accounts.google.com/.well-known/openid-configuration`. 1. The OpenID Connect client uses HTTP Basic Authentication to send the - OAuth2 access token if `client_auth_method` is not defined or if set to `basic`. - If you are seeing 401 errors upon retrieving the `userinfo` endpoint, you may - want to check your OpenID Web server configuration. For example, for - [`oauth2-server-php`](https://github.com/bshaffer/oauth2-server-php), you - may need to [add a configuration parameter to Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). + OAuth 2.0 access token if `client_auth_method` is not defined or if set to `basic`. + If you see 401 errors when retrieving the `userinfo` endpoint, check + your OpenID web server configuration. For example, for + [`oauth2-server-php`](https://github.com/bshaffer/oauth2-server-php), you may have to + [add a configuration parameter to Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 0590410bf31..11117e8a74c 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -13,7 +13,7 @@ GitLab supports authentication using smartcards. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33669) in GitLab 12.6. -By default, existing users can continue to log in with a username and password when smartcard +By default, existing users can continue to sign in with a username and password when smartcard authentication is enabled. To force existing users to use only smartcard authentication, @@ -101,7 +101,7 @@ Certificate: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7693) in GitLab 11.8 as an experimental feature. Smartcard authentication against an LDAP server may change or be removed completely in the future. GitLab implements a standard way of certificate matching following -[RFC4523](https://tools.ietf.org/html/rfc4523). It uses the +[RFC4523](https://www.rfc-editor.org/rfc/rfc4523). It uses the `certificateExactMatch` certificate matching rule against the `userCertificate` attribute. As a prerequisite, you must use an LDAP server that: diff --git a/doc/administration/cicd.md b/doc/administration/cicd.md index 5e061320c5b..6899b572e8f 100644 --- a/doc/administration/cicd.md +++ b/doc/administration/cicd.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -69,7 +69,8 @@ can choose a custom limit. For example, to set the limit to `100`: Plan.default.actual_limits.update!(ci_needs_size_limit: 100) ``` -To disable directed acyclic graphs (DAG), set the limit to `0`. +To disable directed acyclic graphs (DAG), set the limit to `0`. Pipelines with jobs +configured to use `needs` then return the error `job can only need 0 others`. ## Change maximum scheduled pipeline frequency diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 82bb1a35e02..d7e1c9af1de 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install the GitLab agent server for Kubernetes (KAS) **(FREE SELF)** @@ -28,9 +28,13 @@ Or, you can [use an external agent server](#use-an-external-installation). ### For Omnibus -For [Omnibus](https://docs.gitlab.com/omnibus/) package installations: +You can enable the agent server for [Omnibus](https://docs.gitlab.com/omnibus/) package installations on a single node, or on multiple nodes at once. -1. To enable the agent server, edit `/etc/gitlab/gitlab.rb`: +#### Enable on a single node + +To enable the agent server on a single node: + +1. Edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_kas['enable'] = true @@ -41,6 +45,33 @@ For [Omnibus](https://docs.gitlab.com/omnibus/) package installations: For additional configuration options, see the **Enable GitLab KAS** section of the [`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template). +#### Enable on multiple nodes + +To enable the agent server on multiple nodes: + +1. For each agent server node, edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_kas['enable'] = true + gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>' + gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>' + gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' + gitlab_kas['env'] = { + 'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/", + 'OWN_PRIVATE_API_URL' => 'grpc://<ip_or_hostname_of_this_host>:8155' + } + ``` + + In this configuration: + + - `gitlab_kas['private_api_listen_address']` is the address the agent server listens on. You can set it to `0.0.0.0` or an IP address reachable by other nodes in the cluster. + - `OWN_PRIVATE_API_URL` is the environment variable used by the KAS process for service discovery. You can set it to a hostname or IP address of the node you're configuring. The node must be reachable by other nodes in the cluster. + - `gitlab_kas['api_secret_key']` is the shared secret used for authentication between KAS and GitLab. This value must be Base64-encoded and exactly 32 bytes long. + - `gitlab_kas['private_api_secret_key']` is the shared secret used for authentication between different KAS instances. This value must be Base64-encoded and exactly 32 bytes long. + +1. For each application node, follow the steps in: [Use an external installation](../clusters/kas.md#use-an-external-installation). +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + ### For GitLab Helm Chart For GitLab [Helm Chart](https://docs.gitlab.com/charts/) installations: diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 573ffbf4686..ad345461776 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance features **(FREE)** @@ -48,9 +48,9 @@ settings and automation to ensure that whatever a compliance team has configured stays configured and working correctly. These features can help you automate compliance: -- [**Compliance frameworks**](../user/project/settings/index.md#compliance-frameworks) (for groups): Create a custom +- [**Compliance frameworks**](../user/group/manage.md#compliance-frameworks) (for groups): Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. -- [**Compliance pipelines**](../user/project/settings/index.md#compliance-pipeline-configuration) (for groups): Define a +- [**Compliance pipelines**](../user/group/manage.md#configure-a-compliance-pipeline) (for groups): Define a pipeline configuration to run for any projects with a given compliance framework. ## Audit management diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 4335c6d972f..40f03d25e8d 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/consul.md b/doc/administration/consul.md index e282960c857..a6f76882c4d 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 3f5d4adc95c..9021a795523 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Host the GitLab product documentation **(FREE SELF)** @@ -261,7 +261,7 @@ To upgrade to a later version [using your own web-server](#self-host-the-product If you self-host the product documentation: -- The version dropdown displays additional versions that don't exist. Selecting +- The version dropdown list displays additional versions that don't exist. Selecting these versions displays a `404 Not Found` page. - The search displays results from `docs.gitlab.com` and not the local site. - By default, the landing page redirects to the diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index a96a4c4405d..648f6d7018e 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- @@ -17,17 +17,17 @@ GitLab can read settings for certain features from encrypted settings files. The To enable the encrypted configuration settings, a new base key must be generated for `encrypted_settings_key_base`. The secret can be generated in the following ways: -**Omnibus Installation** +**Omnibus** Starting with 13.7 the new secret is automatically generated for you, but you must ensure your `/etc/gitlab/gitlab-secrets.json` contains the same values on all nodes. -**GitLab Cloud Native Helm Chart** +**Helm chart** Starting with GitLab 13.7, the new secret is automatically generated if you have the `shared-secrets` chart enabled. Otherwise, you need to follow the [secrets guide for adding the secret](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-rails-secret). -**Source Installation** +**Source** The new secret can be generated by running: diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index e70758e2774..beaef7afe57 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/external_pipeline_validation.md b/doc/administration/external_pipeline_validation.md index b9bf0cfdc50..e6f825f7cb8 100644 --- a/doc/administration/external_pipeline_validation.md +++ b/doc/administration/external_pipeline_validation.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 75e65c2a9d6..4f8f7c22a55 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags" --- @@ -27,8 +27,9 @@ Features behind flags can be gradually rolled out, typically: 1. The feature flag is removed. These features can be enabled and disabled to allow or prevent users from using -them. It can be done by GitLab administrators with access to GitLab Rails -console. +them. It can be done by GitLab administrators with access to the +[Rails console](#how-to-enable-and-disable-features-behind-flags) or the +[Feature flags API](../api/features.md). When you disable a feature flag, the feature is hidden from users and all of the functionality is turned off. For example, data is not recorded and services do not run. diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index ed5dbd83a8e..8fafb258593 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index d3aa2c97833..699fe6851eb 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automatic background verification **(PREMIUM SELF)** diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 1991b747af0..dda2c5d34d3 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index e82c130ba01..156a87614e6 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disaster Recovery (Geo) **(PREMIUM SELF)** @@ -10,8 +10,6 @@ Geo replicates your database, your Git repositories, and few other assets, but there are some [limitations](../index.md#limitations). WARNING: -Disaster recovery for multi-secondary configurations is in [**Alpha**](../../../policy/alpha-beta-support.md#alpha-features). -For the latest updates, check the [Disaster Recovery epic for complete maturity](https://gitlab.com/groups/gitlab-org/-/epics/3574). Multi-secondary configurations require the complete re-synchronization and re-configuration of all non-promoted secondaries and causes downtime. @@ -342,7 +340,7 @@ with the **secondary** site: 1. Promote the replica database associated with the **secondary** site. This sets the database to read-write. The instructions vary depending on where your database is hosted: - [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote) - - [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) + - [Azure PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) - [Google Cloud SQL](https://cloud.google.com/sql/docs/mysql/replication/manage-replicas#promote-replica) - For other external PostgreSQL databases, save the following script in your secondary site, for example `/tmp/geo_promote.sh`, and modify the connection @@ -413,7 +411,7 @@ required: 1. Promote the replica database associated with the **secondary** site. This sets the database to read-write. The instructions vary depending on where your database is hosted: - [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote) - - [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) + - [Azure PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) - [Google Cloud SQL](https://cloud.google.com/sql/docs/mysql/replication/manage-replicas#promote-replica) - For other external PostgreSQL databases, save the following script in your secondary site, for example `/tmp/geo_promote.sh`, and modify the connection @@ -617,9 +615,9 @@ Now we need to make each **secondary** site listen to changes on the new **prima to [initiate the replication process](../setup/database.md#step-3-initiate-the-replication-process) again but this time for another **primary** site. All the old replication settings are overwritten. -## Promoting a secondary Geo cluster in GitLab Cloud Native Helm Charts +## Promoting a secondary Geo cluster in the GitLab Helm chart -When updating a Cloud Native Geo deployment, the process for updating any node that is external to the secondary Kubernetes cluster does not differ from the non Cloud Native approach. As such, you can always defer to [Promoting a secondary Geo site in single-secondary configurations](#promoting-a-secondary-geo-site-in-single-secondary-configurations) for more information. +When updating a cloud-native Geo deployment, the process for updating any node that is external to the secondary Kubernetes cluster does not differ from the non cloud-native approach. As such, you can always defer to [Promoting a secondary Geo site in single-secondary configurations](#promoting-a-secondary-geo-site-in-single-secondary-configurations) for more information. The following sections assume you are using the `gitlab` namespace. If you used a different namespace when setting up your cluster, you should also replace `--namespace gitlab` with your namespace. diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index d0dbecce43a..60101f5af8e 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -233,7 +233,7 @@ At this point, your **secondary** site contains an up-to-date copy of everything ## Promote the **secondary** site -After the replication is finished, [promote the **secondary** site to a **primary** site](index.md). This process causes a brief outage on the **secondary** site, and users may need to log in again. If you follow the steps correctly, the old primary Geo site should still be disabled and user traffic should go to the newly-promoted site instead. +After the replication is finished, [promote the **secondary** site to a **primary** site](index.md). This process causes a brief outage on the **secondary** site, and users may need to sign in again. If you follow the steps correctly, the old primary Geo site should still be disabled and user traffic should go to the newly-promoted site instead. When the promotion is completed, the maintenance window is over, and your new **primary** site now begins to diverge from the old one. If problems do arise at this point, failing diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md index 11baf383c67..8c18aaa944d 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -121,7 +121,7 @@ follow these steps to avoid unnecessary data loss: ``` From this point, users are unable to view their data or make changes on the - **primary** site. They are also unable to log in to the **secondary** site. + **primary** site. They are also unable to sign in to the **secondary** site. However, existing sessions must work for the remainder of the maintenance period, and so public data is accessible throughout. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md index 2958c119c20..f9d99095951 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -106,7 +106,7 @@ follow these steps to avoid unnecessary data loss: ``` From this point, users are unable to view their data or make changes on the - **primary** site. They are also unable to log in to the **secondary** site. + **primary** site. They are also unable to sign in to the **secondary** site. However, existing sessions need to work for the remainder of the maintenance period, and so public data is accessible throughout. diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md index c9d4ccacae3..9abd7ea9347 100644 --- a/doc/administration/geo/glossary.md +++ b/doc/administration/geo/glossary.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index db298d4fdfc..a336f5ff8bc 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo **(PREMIUM SELF)** @@ -206,6 +206,7 @@ This list of limitations only reflects the latest version of GitLab. If you are - [Selective synchronization](replication/configuration.md#selective-synchronization) only limits what repositories and files are replicated. The entire PostgreSQL data is still replicated. Selective synchronization is not built to accommodate compliance / export control use cases. - [Pages access control](../../user/project/pages/pages_access_control.md) doesn't work on secondaries. See [GitLab issue #9336](https://gitlab.com/gitlab-org/gitlab/-/issues/9336) for details. - [GitLab chart with Geo](https://docs.gitlab.com/charts/advanced/geo/) does not support [Unified URLs](secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites). See [GitLab issue #3522](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/3522) for more details. +- [Disaster recovery](disaster_recovery/index.md) for multi-secondary sites causes downtime due to the complete re-synchronization and re-configuration of all non-promoted secondaries. ### Limitations on replication/verification diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 39d1f5ae602..fa74f16cdc8 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/container_registry.md b/doc/administration/geo/replication/container_registry.md index 01ba81b6dbe..abf34efa56e 100644 --- a/doc/administration/geo/replication/container_registry.md +++ b/doc/administration/geo/replication/container_registry.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 40b71684bac..566df2ee509 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -59,6 +59,10 @@ verification methods: | Blobs | Pages _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | CI Secure Files _(file system)_ | Geo with API | SHA256 checksum | | Blobs | CI Secure Files _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Incident Metric Images _(file system)_ | Geo with API/Managed | SHA256 checksum | +| Blobs | Incident Metric Images _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Alert Metric Images _(file system)_ | Geo with API | SHA256 checksum | +| Blobs | Alert Metric Images _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | - (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo sites. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance @@ -197,7 +201,8 @@ successfully, you must replicate their data using some other means. |[CI job artifacts](../../../ci/pipelines/job_artifacts.md) | **Yes** (10.4) | **Yes** (14.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Verification is behind the feature flag `geo_job_artifact_replication`, enabled by default in 14.10. | |[CI Pipeline Artifacts](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/pipeline_artifact.rb) | [**Yes** (13.11)](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | [**Yes** (13.11)](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Persists additional artifacts after a pipeline completes. | |[CI Secure Files](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/secure_file.rb) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [No](object_storage.md#verification-of-files-in-object-storage) | Verification is behind the feature flag `geo_ci_secure_file_replication`, enabled by default in 15.3. | -|[Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | No | No | Disabled by default. See [instructions](container_registry.md) to enable. | +|[Container Registry](../../packages/container_registry.md) | **Yes** (12.3)* | No | No | No | Replication is behind feature flag `geo_container_repository_replication`, enabled by default. +Requires additional configuration. See [instructions](container_registry.md) to set up the Container Registry replication. | |[Infrastructure Registry](../../../user/packages/infrastructure_registry/index.md) | **Yes** (14.0) | **Yes** (14.0) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | N/A | N/A | Designs also require replication of LFS objects and Uploads. | |[Package Registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | **Yes** (13.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | @@ -206,9 +211,11 @@ successfully, you must replicate their data using some other means. |[Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [**Yes** (14.2)](https://gitlab.com/groups/gitlab-org/-/epics/2810) | N/A | N/A | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | |[GitLab Pages](../../pages/index.md) | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_pages_deployment_replication`, enabled by default. Verification was behind the feature flag `geo_pages_deployment_verification`, removed in 14.7. | |[Project-level Secure files](../../../ci/secure_files/index.md) | **Yes** (15.3) | **Yes** (15.3) | **Yes** (15.3) | [No](object_storage.md#verification-of-files-in-object-storage) | | -|[Incident Metric Images](../../../operations/incident_management/incidents.md#metrics) | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/362561) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362561) | No | No | | -|[Alert Metric Images](../../../operations/incident_management/alerts.md#metrics-tab) | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/362564) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362564) | No | No | | +| [Incident Metric Images](../../../operations/incident_management/incidents.md#metrics) | **Yes** (15.5) | **Yes**(15.5) | **Yes** (15.5) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication/Verification is handled via the Uploads data type. | | +|[Alert Metric Images](../../../operations/incident_management/alerts.md#metrics-tab) | **Yes** (15.5) | **Yes** (15.5) | **Yes** (15.5) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication/Verification is handled via the Uploads data type. | |[Server-side Git hooks](../../server_hooks.md) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/1867) | No | N/A | N/A | Not planned because of current implementation complexity, low customer interest, and availability of alternatives to hooks. | -|[Elasticsearch integration](../../../integration/elasticsearch.md) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | No | Not planned because further product discovery is required and Elasticsearch (ES) clusters can be rebuilt. Secondaries use the same ES cluster as the primary. | -|[Dependency proxy images](../../../user/packages/dependency_proxy/index.md) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/259694) | No | No | No | Blocked by [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for disaster recovery purposes because it can be recreated from external sources. | +|[Elasticsearch integration](../../../integration/advanced_search/elasticsearch.md) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | No | Not planned because further product discovery is required and Elasticsearch (ES) clusters can be rebuilt. Secondaries use the same ES cluster as the primary. | +|[Dependency proxy images](../../../user/packages/dependency_proxy/index.md) | [Planned](https://gitlab.com/groups/gitlab-org/-/epics/8833) | No | No | No | Blocked by [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for disaster recovery purposes because it can be recreated from external sources. | |[Vulnerability Export](../../../user/application_security/vulnerability_report/index.md#export-vulnerability-details) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | No | No | Not planned because they are ephemeral and sensitive information. They can be regenerated on demand. | + +\* Migrated to [self-service framework](../../../development/geo/framework.md) in 15.5. See GitLab issue [#337436](https://gitlab.com/gitlab-org/gitlab/-/issues/337436) for more details. diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index 84bc2e034b9..3230a92136f 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -63,7 +63,7 @@ Geo node in a PostgreSQL console (`sudo gitlab-psql`): ## Remove Geo-related configuration -1. For each node on your primary Geo site, SSH into the node and log in as root: +1. For each node on your primary Geo site, SSH into the node and sign in as root: ```shell sudo -i diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 7a67af1cfa2..81afcc19bb1 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Frequently Asked Questions **(PREMIUM SELF)** @@ -69,6 +69,6 @@ That's totally fine. We use HTTP(s) to fetch repository changes from the **prima Yes. See [Container Registry for a **secondary** site](container_registry.md). -## Can you log in to a secondary site? +## Can you sign in to a secondary site? Yes, but secondary sites receive all authentication data (like user accounts and logins) from the primary instance. This means you are re-directed to the primary for authentication and then routed back. diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 7b59cdda1aa..8fa5a45b579 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo validation tests **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index 18103211580..e0e113eebbd 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index afa4f4eb552..5be7d40890c 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -53,7 +53,7 @@ you already have a working GitLab instance that is in-use, it can be used as a The second GitLab site serves as the Geo **secondary** site. Again, use the [GitLab reference architectures documentation](../../reference_architectures/index.md) to set this up. -It's a good idea to log in and test it. However, be aware that its data is +It's a good idea to sign in and test it. However, be aware that its data is wiped out as part of the process of replicating from the **primary** site. ## Configure a GitLab site to be the Geo **primary** site diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 0336a1669f9..8128eaf5310 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index b136f6cc8b8..62b1d9fdf7b 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index bc08b7b71e7..0231da53b9c 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index d64ad2549e8..3f16c1552ad 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Geo **(PREMIUM SELF)** @@ -311,6 +311,51 @@ sudo gitlab-rake gitlab:geo:check When performing a PostgreSQL major version (9 > 10) update this is expected. Follow the [initiate-the-replication-process](../setup/database.md#step-3-initiate-the-replication-process). +### Repository verification failures + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +to gather the following, basic troubleshooting information. + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +#### Get the number of verification failed repositories + +```ruby +Geo::ProjectRegistry.verification_failed('repository').count +``` + +#### Find the verification failed repositories + +```ruby +Geo::ProjectRegistry.verification_failed('repository') +``` + +#### Find repositories that failed to sync + +```ruby +Geo::ProjectRegistry.sync_failed('repository') +``` + +### Resync repositories + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +to enact the following, basic troubleshooting steps. + +#### Queue up all repositories for resync. Sidekiq handles each sync + +```ruby +Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true) +``` + +#### Sync individual repository now + +```ruby +project = Project.find_by_full_path('<group/project>') + +Geo::RepositorySyncService.new(project).execute +``` + ## Fixing replication errors The following sections outline troubleshooting steps for fixing replication @@ -779,7 +824,7 @@ This behavior affects only the following data types through GitLab 14.6: | Data type | From version | | ------------------------ | ------------ | | Package Registry | 13.10 | -| Pipeline Artifacts | 13.11 | +| CI Pipeline Artifacts | 13.11 | | Terraform State Versions | 13.12 | | Infrastructure Registry | 14.0 | | External MR diffs | 14.6 | @@ -792,6 +837,120 @@ This behavior affects only the following data types through GitLab 14.6: to make Geo visibly surface data loss risks. The sync/verification loop is therefore short-circuited. `last_sync_failure` is now set to `The file is missing on the Geo primary site`. +### Blob types + +- `Ci::JobArtifact` +- `Ci::PipelineArtifact` +- `Ci::SecureFile` +- `LfsObject` +- `MergeRequestDiff` +- `Packages::PackageFile` +- `PagesDeployment` +- `Terraform::StateVersion` +- `Upload` + +`Packages::PackageFile` is used in the following +[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +examples, but things generally work the same for the other types. + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +#### The Replicator + +The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it): + +```ruby +model_record = Packages::PackageFile.last +model_record.replicator.registry.replicator.model_record # just showing that these methods exist +``` + +#### Replicate a package file, synchronously, given an ID + +```ruby +model_record = Packages::PackageFile.find(id) +model_record.replicator.send(:download) +``` + +#### Replicate a package file, synchronously, given a registry ID + +```ruby +registry = Geo::PackageFileRegistry.find(registry_id) +registry.replicator.send(:download) +``` + +#### Verify package files on the secondary manually + +This iterates over all package files on the secondary, looking at the +`verification_checksum` stored in the database (which came from the primary) +and then calculate this value on the secondary to check if they match. This +does not change anything in the UI: + +```ruby +# Run on secondary +status = {} + +Packages::PackageFile.find_each do |package_file| + primary_checksum = package_file.verification_checksum + secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path) + verification_status = (primary_checksum == secondary_checksum) + + status[verification_status.to_s] ||= [] + status[verification_status.to_s] << package_file.id +end + +# Count how many of each value we get +status.keys.each {|key| puts "#{key} count: #{status[key].count}"} + +# See the output in its entirety +status +``` + +### Repository types newer than project/wiki repositories + +- `SnippetRepository` +- `GroupWikiRepository` + +`SnippetRepository` is used in the examples below, but things generally work the same for the other Repository types. + +#### The Replicator + +The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it). + +```ruby +model_record = SnippetRepository.last +model_record.replicator.registry.replicator.model_record # just showing that these methods exist +``` + +#### Replicate a snippet repository, synchronously, given an ID + +```ruby +model_record = SnippetRepository.find(id) +model_record.replicator.send(:sync_repository) +``` + +#### Replicate a snippet repository, synchronously, given a registry ID + +```ruby +registry = Geo::SnippetRepositoryRegistry.find(registry_id) +registry.replicator.send(:sync_repository) +``` + +### Find failed artifacts + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +to run the following commands: + +```ruby +Geo::JobArtifactRegistry.failed +``` + +#### Find `ID` of synced artifacts that are missing on primary + +```ruby +Geo::JobArtifactRegistry.synced.missing_on_primary.pluck(:artifact_id) +``` + #### Failed syncs with GitLab-managed object storage replication There is [an issue in GitLab 14.2 through 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/299819#note_822629467) diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 370c50c93db..ab9263ad344 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/upgrading_the_geo_sites.md b/doc/administration/geo/replication/upgrading_the_geo_sites.md index ce1ff4fe6a5..55395a55857 100644 --- a/doc/administration/geo/replication/upgrading_the_geo_sites.md +++ b/doc/administration/geo/replication/upgrading_the_geo_sites.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index fe0e06e7ea4..cfaa02e1a17 100644 --- a/doc/administration/geo/replication/usage.md +++ b/doc/administration/geo/replication/usage.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) --> diff --git a/doc/administration/geo/replication/version_specific_upgrades.md b/doc/administration/geo/replication/version_specific_upgrades.md index 6211b5689b1..9aad5cdeaa7 100644 --- a/doc/administration/geo/replication/version_specific_upgrades.md +++ b/doc/administration/geo/replication/version_specific_upgrades.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Version-specific upgrade instructions **(PREMIUM SELF)** @@ -10,6 +10,12 @@ Review this page for upgrade instructions for your version. These steps accompany the [general steps](upgrading_the_geo_sites.md#general-upgrade-steps) for upgrading Geo sites. +## Upgrading to 15.1 + +[Geo proxying](../secondary_proxy/index.md) was [enabled by default for different URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in 15.1. This may be a breaking change. If needed, you may [disable Geo proxying](../secondary_proxy/index.md#disable-geo-proxying). + +If you are using SAML with different URLs, there is a [known issue which requires proxying to be disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/377372). + ## Upgrading to 14.9 **Do not** upgrade to GitLab 14.9.0. Instead, use 14.9.1 or later. @@ -33,6 +39,10 @@ results in a loop that consistently fails for all objects stored in object stora For information on how to fix this, see [Troubleshooting - Failed syncs with GitLab-managed object storage replication](troubleshooting.md#failed-syncs-with-gitlab-managed-object-storage-replication). +## Upgrading to 14.6 + +[Geo proxying](../secondary_proxy/index.md) was [enabled by default for unified URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/325732) in 14.6. This may be a breaking change. If needed, you may [disable Geo proxying](../secondary_proxy/index.md#disable-geo-proxying). + ## Upgrading to 14.4 There is [an issue in GitLab 14.4.0 through 14.4.2](../../../update/index.md#1440) that can affect Geo and other features that rely on cronjobs. We recommend upgrading to GitLab 14.4.3 or later. @@ -80,9 +90,9 @@ GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab ## Upgrading to GitLab 14.0/14.1 -### Primary sites can not be removed from the UI +### Primary sites cannot be removed from the UI -We found an issue where [Primary sites can not be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). +We found an issue where [Primary sites cannot be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). This bug only exists in the UI and does not block the removal of Primary sites using any other method. diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index 731b5012663..2786982bb51 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -147,6 +147,13 @@ for details. - [Viewing projects and designs data from a primary site is not possible when using a unified URL](../index.md#view-replication-data-on-the-primary-site). +- When secondary proxying is used together with separate URLs, registering [GitLab runners](https://docs.gitlab.com/runner/) to clone from +secondary sites is not supported. The runner registration will succeed, but the clone URL will default to the primary site. The runner +[clone URL](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) is configured per GitLab deployment +and cannot be configured per Geo site. Therefore, all runners will clone from the primary site (or configured clone URL) irrespective of +which Geo site they register on. For information about GitLab CI using a specific Geo secondary to clone from, see issue +[3294](https://gitlab.com/gitlab-org/gitlab/-/issues/3294#note_1009488466). + ## Behavior of secondary sites when the primary Geo site is down Considering that web traffic is proxied to the primary, the behavior of the secondary sites differs when the primary diff --git a/doc/administration/geo/secondary_proxy/location_aware_external_url.md b/doc/administration/geo/secondary_proxy/location_aware_external_url.md index 1430e99557f..b983230a314 100644 --- a/doc/administration/geo/secondary_proxy/location_aware_external_url.md +++ b/doc/administration/geo/secondary_proxy/location_aware_external_url.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 8a919a0a269..8ea8d6c4d8e 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index b87baa658a1..eabed7c10f3 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with external PostgreSQL instances **(PREMIUM SELF)** @@ -69,14 +69,13 @@ To set up an external database, you can either: Given you have a primary site set up on AWS EC2 that uses RDS. You can now just create a read-only replica in a different region and the -replication process is managed by AWS. Make sure you've set Network ACL (Access Control List), Subnet, and -Security Group according to your needs, so the secondary Rails node(s) can access the database. +replication process is managed by AWS. Make sure you've set Network ACL (Access Control List), Subnet, and Security Group according to your needs, so the secondary Rails nodes can access the database. The following instructions detail how to create a read-only replica for common cloud providers: - Amazon RDS - [Creating a Read Replica](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Create) -- Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal) +- Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal) - Google Cloud SQL - [Creating read replicas](https://cloud.google.com/sql/docs/postgres/replication/create-replica) Once your read-only replica is set up, you can skip to [configure your secondary site](#configure-secondary-site-to-use-the-external-read-replica) @@ -195,7 +194,7 @@ to grant additional roles to your tracking database user (by default, this is `gitlab_geo`): - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. -- Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. +- Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. - Google Cloud SQL requires the [`cloudsqlsuperuser`](https://cloud.google.com/sql/docs/postgres/users#default-users) role. This is for the installation of extensions during installation and upgrades. As an alternative, diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md index 79b52ef71da..c794b8ef219 100644 --- a/doc/administration/geo/setup/index.md +++ b/doc/administration/geo/setup/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -16,14 +16,14 @@ You must use a [GitLab Premium](https://about.gitlab.com/pricing/) license or hi but you only need one license for all the sites. WARNING: -The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all sites. Do not create an account or log in to the new secondary.** +The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all sites. Do not create an account or sign in to the new secondary.** ## Using Omnibus GitLab If you installed GitLab using the Omnibus packages (highly recommended): 1. Confirm the [requirements for running Geo](../index.md#requirements-for-running-geo) are met. -1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the nodes that serve as the **secondary** site. **Do not create an account or log in** to the new **secondary** site. The **GitLab version must match** across primary and secondary sites. +1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the nodes that serve as the **secondary** site. **Do not create an account or sign in** to the new **secondary** site. The **GitLab version must match** across primary and secondary sites. 1. [Add the GitLab License](../../../user/admin_area/license.md) on the **primary** site to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher. 1. [Confirm network connectivity](../index.md#firewall-rules) between the **primary** and **secondary** site. 1. [Set up the database replication](database.md) (`primary (read-write) <-> secondary (read-only)` topology). diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 44b09ef185a..4099ddc16f8 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -1,5 +1,5 @@ --- -info: For assistance with this TAM Onboarding page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this TAM Onboarding page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned --- @@ -283,7 +283,7 @@ You can learn more about how to administer GitLab. ### Free GitLab training -- GitLab basics: Discover self-service guides on [Git and GitLab basics](../gitlab-basics/index.md). +- GitLab basics: Discover self-service guides on [Git and GitLab basics](../tutorials/index.md). - GitLab Learn: Learn new GitLab skills in a structured course at [GitLab Learn](https://about.gitlab.com/learn/). ### Third-party training diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 3612487f456..f900c5a6867 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Set and configure Git protocol v2" --- @@ -15,7 +15,7 @@ configuration is required by an administrator. More details about the new features and improvements are available in the [Google Open Source Blog](https://opensource.googleblog.com/2018/05/introducing-git-protocol-version-2.html) -and the [protocol documentation](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt). +and the [protocol documentation](https://github.com/git/git/blob/master/Documentation/gitprotocol-v2.txt). ## Requirements diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index bfd252a9f42..e4aef2db9a8 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly **(FREE SELF)** @@ -555,12 +555,15 @@ Additionally, the certificate (or its certificate authority) must be installed o - Gitaly servers. - Gitaly clients that communicate with it. -Note the following: +### Certificate requirements - The certificate must specify the address you use to access the Gitaly server. You must add the hostname or IP address as a Subject Alternative Name to the certificate. - 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. +- The certificate's Common Name field is ignored. + +### Configure Gitaly with TLS To configure Gitaly with TLS: diff --git a/doc/administration/gitaly/faq.md b/doc/administration/gitaly/faq.md deleted file mode 100644 index f6571295200..00000000000 --- a/doc/administration/gitaly/faq.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-08-24' ---- - -This document was moved to [another location](index.md). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index c7f7c4c58a5..96447239116 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly and Gitaly Cluster **(FREE SELF)** diff --git a/doc/administration/gitaly/monitoring.md b/doc/administration/gitaly/monitoring.md index a435fff74fc..9b7acd536b3 100644 --- a/doc/administration/gitaly/monitoring.md +++ b/doc/administration/gitaly/monitoring.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring Gitaly and Gitaly Cluster diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index bd03aa1bdbc..e3b198d1012 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly Cluster **(FREE SELF)** @@ -1320,7 +1320,7 @@ Deletions are disabled by default due to a race condition with repository rename deletions. This is especially prominent in Geo instances as Geo performs more renames than instances without Geo. You should enable deletions only if the [`gitaly_praefect_generated_replica_paths` feature flag](index.md#praefect-generated-replica-paths-gitlab-150-and-later) is enabled. -By default, the worker does not delete invalid metadata records but simply logs them and outputs Prometheus +By default, the worker does not delete invalid metadata records but logs them and outputs Prometheus metrics for them. You can enable deleting invalid metadata records with: diff --git a/doc/administration/gitaly/recovery.md b/doc/administration/gitaly/recovery.md index 4bbf25d7cdd..b51454aa44e 100644 --- a/doc/administration/gitaly/recovery.md +++ b/doc/administration/gitaly/recovery.md @@ -1,14 +1,15 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Recovery options +# Gitaly Cluster recovery options and tools -Gitaly Cluster can [recover from certain types of failure](recovery.md). +Gitaly Cluster can recover from primary-node failure and unavailable repositories. Gitaly Cluster can perform data +recovery and has Praefect tracking database tools. -## Primary Node Failure +## Primary node failure Gitaly Cluster recovers from a failing primary Gitaly node by promoting a healthy secondary as the new primary. @@ -29,14 +30,12 @@ To minimize data loss in GitLab 13.0 to 14.0, Gitaly Cluster: > - Introduced in GitLab 13.0 as [generally available](../../policy/alpha-beta-support.md#generally-available-ga). > - Between GitLab 13.0 and GitLab 13.2, read-only mode applied to the whole virtual storage and occurred whenever failover occurred. -> - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/2862), read-only mode applies on a per-repository basis and only occurs if a new primary is out of date. -new primary. If the failed primary contained unreplicated writes, [data loss can occur](#check-for-data-loss). +> - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/2862), read-only mode applies on a per-repository basis and only occurs if a new primary is out of date. If the failed primary contained unreplicated writes, [data loss can occur](#check-for-data-loss). > - Removed in GitLab 14.1. Instead, repositories [become unavailable](#unavailable-repositories). -When Gitaly Cluster switches to a new primary in GitLab 13.0 to 14.0, repositories enter -read-only mode if they are out of date. This can happen after failing over to an outdated -secondary. Read-only mode eases data recovery efforts by preventing writes that may conflict -with the unreplicated writes on other nodes. +When Gitaly Cluster switches to a new primary in GitLab 13.0 to 14.0, repositories enter read-only mode if they are +out-of-date. This can happen after failing over to an outdated secondary. Read-only mode eases data recovery efforts by +preventing writes that may conflict with the unreplicated writes on other nodes. To enable writes again in GitLab 13.0 to 14.0, an administrator can: @@ -46,7 +45,7 @@ To enable writes again in GitLab 13.0 to 14.0, an administrator can: [accept data loss](#enable-writes-or-accept-data-loss) if necessary, depending on the version of GitLab. -## Unavailable repositories +### Unavailable repositories > - From GitLab 13.0 through 14.0, repositories became read-only if they were outdated on the primary but fully up to date on a healthy secondary. `dataloss` sub-command displays read-only repositories by default through these versions. > - Since GitLab 14.1, Praefect contains more responsive failover logic which immediately fails over to one of the fully up to date secondaries rather than placing the repository in read-only mode. Since GitLab 14.1, the `dataloss` sub-command displays repositories which are unavailable due to having no fully up to date copies on healthy Gitaly nodes. @@ -252,7 +251,7 @@ These tools reconcile the outdated repositories to bring them fully up to date a > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2717) in GitLab 13.4. Praefect automatically reconciles repositories that are not up to date. By default, this is done every -five minutes. For each outdated repository on a healthy Gitaly node, the Praefect picks a +five minutes. For each outdated repository on a healthy Gitaly node, Praefect picks a random, fully up-to-date replica of the repository on another healthy Gitaly node to replicate from. A replication job is scheduled only if there are no other replication jobs pending for the target repository. @@ -296,7 +295,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3767) in GitLab 14.3. > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4054) in GitLab 14.6, support for dry-run mode. -> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4715) in GitLab 15.3, support for removing repositories from Praefect's database. +> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4715) in GitLab 15.3, support for removing repositories from the Praefect tracking database. The `remove-repository` Praefect sub-command removes a repository from a Gitaly Cluster, and all state associated with a given repository including: @@ -311,9 +310,9 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t - Replace `<virtual-storage>` with the name of the virtual storage containing the repository. - Replace `<repository>` with the relative path of the repository to remove. -- In GitLab 15.3 and later, add `-db-only` to remove the Praefect database entry without removing the on-disk repository. Use this option to remove orphaned database entries and to +- In GitLab 15.3 and later, add `-db-only` to remove the Praefect tracking database entry without removing the on-disk repository. Use this option to remove orphaned database entries and to protect on-disk repository data from deletion when a valid repository is accidentally specified. If the database entry is accidentally deleted, re-track the repository with the - [`track-repository` command](#manually-track-repositories). + [`track-repository` command](#manually-add-a-single-repository-to-the-tracking-database). - In GitLab 14.6 and later, add `-apply` to run the command outside of dry-run mode and remove the repository. For example: ```shell @@ -349,7 +348,11 @@ Parts of the repository can continue to exist after running `remove-repository`. If this occurs, run `remove-repository` again. -### Manually list untracked repositories +## Praefect tracking database maintenance + +Common maintenance tasks on the Praefect tracking database are documented in this section. + +### List untracked repositories > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3926) in GitLab 14.4. > - `older-than` option added in GitLab 15.0. @@ -357,10 +360,14 @@ If this occurs, run `remove-repository` again. The `list-untracked-repositories` Praefect sub-command lists repositories of the Gitaly Cluster that both: - Exist for at least one Gitaly storage. -- Aren't tracked in the Praefect database. +- Aren't tracked in the Praefect tracking database. + +Add the `-older-than` option to avoid showing repositories that: -Add the `-older-than` option to avoid showing repositories that are the process of being created and for which a record doesn't yet exist in the -Praefect database. Replace `<duration>` with a time duration (for example, `5s`, `10m`, or `1h`). Defaults to `6h`. +- Are in the process of being created. +- For which a record doesn't yet exist in the Praefect tracking database. + +Replace `<duration>` with a time duration (for example, `5s`, `10m`, or `1h`). Defaults to `6h`. ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml list-untracked-repositories -older-than <duration> @@ -382,12 +389,12 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t {"virtual_storage":"default","storage":"gitaly-1","relative_path":"@hashed/ab/cd/abcd123456789012345678901234567890123456789012345678901234567891.git"} ``` -### Manually track repositories +### Manually add a single repository to the tracking database > - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5658) in GitLab 14.4. > - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5789) in GitLab 14.6, support for immediate replication. -The `track-repository` Praefect sub-command adds repositories on disk to the Praefect database to be tracked. +The `track-repository` Praefect sub-command adds repositories on disk to the Praefect tracking database to be tracked. ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml track-repository -virtual-storage <virtual-storage> -authoritative-storage <storage-name> -repository <repository> -replicate-immediately @@ -427,15 +434,17 @@ The command outputs: This command fails if: -- The repository is already being tracked by the Praefect database. +- The repository is already being tracked by the Praefect tracking database. - The repository does not exist on disk. -### Manually track large numbers of repositories +### Manually add many repositories to the tracking database > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6319) in GitLab 15.4. -The `track-repositories` Praefect sub-command adds large batches of on-disk repositories to the Praefect database for tracking. This can -be useful when migrating an existing instance to new infrastructure and ingesting all existing repositories into a fresh Gitaly Cluster. +Migrations using the API automatically add repositories to the Praefect tracking database. + +If you are instead manually copying repositories over from existing infrastructure, you can use the `track-repositories` +Praefect subcommand. This subcommand adds large batches of on-disk repositories to the Praefect tracking database. ```shell # Omnibus GitLab install @@ -449,21 +458,21 @@ The command validates that all entries: - Are formatted correctly and contain required fields. - Correspond to a valid Git repository on disk. -- Are not currently tracked in the Praefect database. +- Are not currently tracked in the Praefect tracking database. If any entry fails these checks, the command aborts prior to attempting to track a repository. - `input-path` is the path to a file containing a list of repositories formatted as newline-delimited JSON objects. Objects must contain the following keys: - - `relative_path`: corresponds with `repository` in [track-repositories](#manually-track-repositories). + - `relative_path`: corresponds with `repository` in [`track-repository`](#manually-add-a-single-repository-to-the-tracking-database). - `authoritative-storage`: the storage Praefect is to treat as the primary. - `virtual-storage`: the virtual storage the repository is located in. - For example: + For example: - ```json - {"relative_path":"@hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git","authoritative_storage":"gitaly-1","virtual_storage":"default"} - {"relative_path":"@hashed/f8/9f/f89f8d0e735a91c5269ab08d72fa27670d000e7561698d6e664e7b603f5c4e40.git","authoritative_storage":"gitaly-2","virtual_storage":"default"} - ``` + ```json + {"relative_path":"@hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git","authoritative_storage":"gitaly-1","virtual_storage":"default"} + {"relative_path":"@hashed/f8/9f/f89f8d0e735a91c5269ab08d72fa27670d000e7561698d6e664e7b603f5c4e40.git","authoritative_storage":"gitaly-2","virtual_storage":"default"} + ``` - `-replicate-immediately`, causes the command to replicate the repository to its secondaries immediately. Otherwise, replication jobs are scheduled for execution in the database and are picked up by a Praefect background process. diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 2542848c7a8..3bf1e3136c0 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly reference **(FREE SELF)** diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 285ec3d2631..1c5f0d43864 100644 --- a/doc/administration/gitaly/troubleshooting.md +++ b/doc/administration/gitaly/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Gitaly and Gitaly Cluster **(FREE SELF)** @@ -67,6 +67,13 @@ remote: GitLab: 401 Unauthorized You need to sync your `gitlab-secrets.json` file with your GitLab application nodes. +### 500 and `fetching folder content` errors on repository pages + +`Fetching folder content`, and in some cases `500`, errors indicate +connectivity problems between GitLab and Gitaly. +Consult the [client-side gRPC logs](#client-side-grpc-logs) +for details. + ### Client side gRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC @@ -81,6 +88,19 @@ You can run a gRPC trace with: sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check ``` +If this command fails with a `failed to connect to all addresses` error, +check for an SSL or TLS problem: + +```shell +/opt/gitlab/embedded/bin/openssl s_client -connect <gitaly-ipaddress>:<port> -verify_return_error +``` + +Check whether `Verify return code` field indicates a +[known Omnibus GitLab configuration problem](https://docs.gitlab.com/omnibus/settings/ssl.html). + +If `openssl` succeeds but `gitlab-rake gitlab:gitaly:check` fails, +check [certificate requirements](configure_gitaly.md#certificate-requirements) for Gitaly. + ### Server side gRPC logs gRPC tracing can also be enabled in Gitaly itself with the `GODEBUG=http2debug` diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index cb0156f8e2d..15287b917e7 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Housekeeping **(FREE SELF)** diff --git a/doc/administration/inactive_project_deletion.md b/doc/administration/inactive_project_deletion.md index 824a444fdd2..88d8e3fc648 100644 --- a/doc/administration/inactive_project_deletion.md +++ b/doc/administration/inactive_project_deletion.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Inactive project deletion **(FREE SELF)** diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 9351a101ee4..4959bacaaa4 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incoming email **(FREE SELF)** @@ -775,7 +775,7 @@ mailboxes. To configure GitLab for Microsoft Graph, you will need to register an OAuth2 application in your Azure Active Directory that has the `Mail.ReadWrite` permission for all mailboxes. See the [MailRoom step-by-step guide](https://github.com/tpitale/mail_room/#microsoft-graph-configuration) -and [Microsoft instructions](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) +and [Microsoft instructions](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for more details. Record the following when you configure your OAuth2 application: @@ -792,7 +792,7 @@ to read/write mail in *all* mailboxes. To mitigate security concerns, we recommend configuring an application access policy which limits the mailbox access for all accounts, as described in -[Microsoft documentation](https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access). +[Microsoft documentation](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access). This example for Omnibus GitLab assumes you're using the following mailbox: `incoming@example.onmicrosoft.com`: @@ -822,7 +822,7 @@ gitlab_rails['incoming_email_inbox_options'] = { } ``` -For Microsoft Cloud for US Government or [other Azure deployments](https://docs.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. - Example for Microsoft Cloud for US Government: diff --git a/doc/administration/index.md b/doc/administration/index.md index 58284a74bf7..7d684daf5a6 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- @@ -194,7 +194,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Monitoring GitLab](monitoring/index.md): - [Monitoring uptime](../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - - [IP allowlist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. + - [IP allowlist](monitoring/ip_allowlist.md): Monitor endpoints that provide health check information when probed. - [Monitoring GitHub imports](monitoring/github_imports.md): The GitLab GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. ### Performance Monitoring diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 0cf2e3a1131..3f44b53a6d5 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -165,7 +165,7 @@ This setting limits global search requests as follows: | Authenticated user | 30 | | Unauthenticated user | 10 | -Depending on the number of enabled [scopes](../user/search/advanced_search.md#global-search-scopes), a global search request can consume two to seven requests per minute. You may want to disable one or more scopes to use fewer requests. Global search requests that exceed the search rate limit per minute return the following error: +Depending on the number of enabled [scopes](../user/search/index.md#global-search-scopes), a global search request can consume two to seven requests per minute. You may want to disable one or more scopes to use fewer requests. Global search requests that exceed the search rate limit per minute return the following error: ```plaintext This endpoint has been requested too many times. Try again later. @@ -289,6 +289,29 @@ For GitLab.com, see the [webhook limits for GitLab.com](../user/gitlab_com/index The maximum webhook payload size is 25 MB. +### Webhook timeout + +The number of seconds GitLab waits for an HTTP response after sending a webhook. + +To change the webhook timeout value: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['webhook_timeout'] = 60 + ``` + +1. Save the file. +1. Reconfigure and restart GitLab for the changes to + take effect: + + ```shell + gitlab-ctl reconfigure + gitlab-ctl restart + ``` + +See also [webhook limits for GitLab.com](../user/gitlab_com/index.md#other-limits). + ### Recursive webhooks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index d9126036a16..5516a47637d 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance review **(FREE SELF)** diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index fb4659175b0..aa029be90e7 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kroki diagrams **(FREE SELF)** @@ -54,7 +54,7 @@ read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images ## Enable Kroki in GitLab You need to enable Kroki integration from Settings under Admin Area. -To do that, log in with an administrator account and follow these steps: +To do that, sign in with an administrator account and follow these steps: 1. On the top bar, select **Main menu > Admin**. 1. Go to **Settings > General**. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md index 37e81f220cf..baf9e8c8a3b 100644 --- a/doc/administration/integration/mailgun.md +++ b/doc/administration/integration/mailgun.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference, howto --- @@ -45,7 +45,7 @@ you're ready to enable the Mailgun integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. 1. On the top bar, select **Main menu >** **{admin}** **Admin**. 1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. -1. Select the **Enable Mailgun** check box. +1. Select the **Enable Mailgun** checkbox. 1. Enter the Mailgun HTTP webhook signing key as described in [the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks-1) and shown in the [API security](https://app.mailgun.com/app/account/security/api_keys) section for your Mailgun account. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index de790c7ce40..f0b3e949b35 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, howto --- diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 41984bbe7a7..14da70f6efb 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web terminals (DEPRECATED) **(FREE)** diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 20a77691bbc..366cbea5711 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 31e9944d9a4..d10f5320109 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 14749a9c7f6..1e9f20ded55 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs artifacts administration **(FREE SELF)** @@ -233,8 +233,6 @@ by the `gitlab:artifacts:migrate` Rake task. To migrate back to local storage: -1. Set both `direct_upload` and `background_upload` to `false` in `gitlab.rb`, under the artifacts object storage settings. -1. [Reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Run `gitlab-rake gitlab:artifacts:migrate_to_local`. 1. Disable object_storage for artifacts in `gitlab.rb`: - Set `gitlab_rails['artifacts_object_store_enabled'] = false`. diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 84da4e31d92..5aa0e8f3948 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index 2fcf7d2f276..1b01c665ab8 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.html' --- @@ -220,7 +220,6 @@ end To migrate back to local storage: -1. Set both `direct_upload` and `background_upload` to `false` under the LFS object storage settings. Don't forget to restart GitLab. 1. Run `rake gitlab:lfs:migrate_to_local` on your console. 1. Disable `object_storage` for LFS objects in `gitlab.rb`. Remember to restart GitLab afterwards. diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index 88a46759924..5b2334bff8a 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 87b63c6272d..ad89d32183b 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Balancer for multi-node GitLab **(FREE SELF)** diff --git a/doc/administration/logs/index.md b/doc/administration/logs/index.md index d3529de08db..2bcda759442 100644 --- a/doc/administration/logs/index.md +++ b/doc/administration/logs/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Log system **(FREE SELF)** diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md index 20b439af49b..dfe434ed1f2 100644 --- a/doc/administration/logs/log_parsing.md +++ b/doc/administration/logs/log_parsing.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Parsing GitLab logs with `jq` **(FREE SELF)** diff --git a/doc/administration/logs/tracing_correlation_id.md b/doc/administration/logs/tracing_correlation_id.md index 1d3e4955d3a..f651455a088 100644 --- a/doc/administration/logs/tracing_correlation_id.md +++ b/doc/administration/logs/tracing_correlation_id.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Find relevant log entries with a correlation ID **(FREE SELF)** @@ -28,7 +28,7 @@ documentation for some popular browsers. - [Network Monitor - Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) - [Inspect Network Activity In Chrome DevTools](https://developer.chrome.com/docs/devtools/network/) - [Safari Web Development Tools](https://developer.apple.com/safari/tools/) -- [Microsoft Edge Network panel](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) +- [Microsoft Edge Network panel](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) To locate a relevant request and view its correlation ID: @@ -187,7 +187,7 @@ You can then view the database details for this request:  -1. A new request is inserted into the `Request Selector` dropdown on the right-hand side of the Performance Bar. Select the new request to view the metrics of the API request: +1. A new request is inserted into the `Request Selector` dropdown list on the right-hand side of the Performance Bar. Select the new request to view the metrics of the API request:  diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 60de8e2fd3a..12f3c4c1cc3 100644 --- a/doc/administration/maintenance_mode/index.md +++ b/doc/administration/maintenance_mode/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Maintenance Mode **(PREMIUM SELF)** @@ -82,7 +82,7 @@ them to disable Maintenance Mode after it's been enabled. ### Authentication -All users can log in and out of the GitLab instance but no new users can be created. +All users can sign in and out of the GitLab instance but no new users can be created. If there are [LDAP syncs](../auth/ldap/index.md) scheduled for that time, they fail since user creation is disabled. Similarly, [user creations based on SAML](../../integration/saml.md#general-setup) fail. @@ -113,9 +113,9 @@ For most JSON requests, `POST`, `PUT`, `PATCH`, and `DELETE` are blocked, and th |:----:|:--------------------------------------:|:----:| | `POST` | `/admin/application_settings/general` | To allow updating application settings in the administrator UI | | `PUT` | `/api/v4/application/settings` | To allow updating application settings with the API | -| `POST` | `/users/sign_in` | To allow users to log in. | -| `POST` | `/users/sign_out`| To allow users to log out. | -| `POST` | `/oauth/token` | To allow users to log in to a Geo secondary for the first time. | +| `POST` | `/users/sign_in` | To allow users to sign in. | +| `POST` | `/users/sign_out`| To allow users to sign out. | +| `POST` | `/oauth/token` | To allow users to sign in to a Geo secondary for the first time. | | `POST` | `/admin/session`, `/admin/session/destroy` | To allow [Admin Mode for GitLab administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158) | | `POST` | Paths ending with `/compare`| Git revision routes. | | `POST` | `.git/git-upload-pack` | To allow Git pull/clone. | diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index fe1c74b0e24..4dec9e52c19 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request diffs storage **(FREE SELF)** @@ -271,3 +271,11 @@ By default, `sudo` does not preserve existing environment variables. You should ```shell sudo gitlab-rake gitlab:external_diffs:force_object_storage START_ID=59946109 END_ID=59946109 UPDATE_DELAY=5 ``` + +## Switching from external storage to object storage + +Automatic migration moves diffs stored in the database, but it does not move diffs between storage types. +To switch from external storage to object storage: + +1. Move files stored on local or NFS storage to object storage manually. +1. Run the Rake task in the [previous section](#correcting-incorrectly-migrated-diffs) to change their location in the database. diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index e16e9bb0336..097109585af 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitHub imports **(FREE SELF)** diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index 4b62a8ae931..ad864255f02 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Self-monitoring project (DEPRECATED) **(FREE SELF)** diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md index 82a6da1d56a..e57156e6513 100644 --- a/doc/administration/monitoring/index.md +++ b/doc/administration/monitoring/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab **(FREE SELF)** @@ -20,7 +20,7 @@ Explore our features to monitor your GitLab instance: importer with various Prometheus metrics. - [Monitoring uptime](../../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - - [IP allowlists](ip_whitelist.md): Configure GitLab for monitoring endpoints that + - [IP allowlists](ip_allowlist.md): Configure GitLab for monitoring endpoints that provide health check information when probed. - [`nginx_status`](https://docs.gitlab.com/omnibus/settings/nginx.html#enablingdisabling-nginx_status): Monitor your NGINX server status. diff --git a/doc/administration/monitoring/ip_allowlist.md b/doc/administration/monitoring/ip_allowlist.md index 3151b696182..400c70d0fde 100644 --- a/doc/administration/monitoring/ip_allowlist.md +++ b/doc/administration/monitoring/ip_allowlist.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # IP whitelist **(FREE SELF)** @@ -15,7 +15,7 @@ that provide health check information when probed. To control access to those endpoints via IP whitelisting, you can add single hosts or use IP ranges: -**For Omnibus installations** +**Omnibus** 1. Open `/etc/gitlab/gitlab.rb` and add or uncomment the following: @@ -27,7 +27,7 @@ hosts or use IP ranges: --- -**For installations using cloud native Helm charts** +**Helm chart** You can set the required IPs under the `gitlab.webservice.monitoring.ipWhitelist` key. For example: @@ -42,7 +42,7 @@ gitlab: --- -**For installations from source** +**Source** 1. Edit `config/gitlab.yml`: diff --git a/doc/administration/monitoring/ip_whitelist.md b/doc/administration/monitoring/ip_whitelist.md deleted file mode 100644 index 9fb4ffe3089..00000000000 --- a/doc/administration/monitoring/ip_whitelist.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'ip_allowlist.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](ip_allowlist.md). - -<!-- This redirect file can be deleted after <2022-08-31>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index 74db35eebc2..cb5852a7dac 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Configuration **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 6e9ea0d8d42..a003a3f25bc 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Grafana Configuration **(FREE SELF)** @@ -81,7 +81,7 @@ GitLab displays your link in the **Main menu > Admin > Monitoring > Metrics Dash When setting up Grafana through the process above, no scope shows in the screen at **Main menu > Admin > Applications > GitLab Grafana**. However, the `read_user` scope is required and is provided to the application automatically. Setting any scope other than -`read_user` without also including `read_user` leads to this error when you try to log in using +`read_user` without also including `read_user` leads to this error when you try to sign in using GitLab as the OAuth provider: ```plaintext diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index b063a20dc7f..0bea0836191 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Performance Monitoring **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index c23046158e1..de6178a3151 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance bar **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md deleted file mode 100644 index d0d05c16ea0..00000000000 --- a/doc/administration/monitoring/performance/request_profiling.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-07-26' -redirect_to: 'index.md' ---- - -# Request profiling (removed) **(FREE SELF)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352488) in GitLab 14.8 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350152) in 15.0. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 15ec880533e..bce35306505 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 00dae8e4dd5..e8bdacb0e14 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Prometheus metrics **(FREE SELF)** @@ -11,7 +11,7 @@ To enable the GitLab Prometheus metrics: 1. Log in to GitLab as a user with administrator access. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. -1. Find the **Metrics - Prometheus** section, and select **Add link to Prometheus**. +1. Find the **Metrics - Prometheus** section, and select **Enable GitLab Prometheus metrics endpoint**. 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect. For installations from source you must configure it yourself. @@ -20,7 +20,7 @@ For installations from source you must configure it yourself. GitLab monitors its own internal service metrics, and makes them available at the `/-/metrics` endpoint. Unlike other [Prometheus](https://prometheus.io) exporters, to access -the metrics, the client IP address must be [explicitly allowed](../ip_whitelist.md). +the metrics, the client IP address must be [explicitly allowed](../ip_allowlist.md). These metrics are enabled and collected for [Omnibus GitLab](https://docs.gitlab.com/omnibus/) and Chart installations. For source installations, these metrics must be enabled @@ -302,6 +302,10 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_uploads_verification_total` | Gauge | 14.6 | Number of uploads verifications tried on secondary | `url` | | `geo_uploads_verified` | Gauge | 14.6 | Number of uploads verified on secondary | `url` | | `geo_uploads_verification_failed` | Gauge | 14.6 | Number of uploads verifications failed on secondary | `url` | +| `geo_container_repositories` | Gauge | 15.4 | Number of container repositories on primary | `url` | +| `geo_container_repositories_synced` | Gauge | 15.4 | Number of container repositories synced on secondary | `url` | +| `geo_container_repositories_failed` | Gauge | 15.4 | Number of syncable container repositories failed to sync on secondary | `url` | +| `geo_container_repositories_registry` | Gauge | 15.4 | Number of container repositories in the registry | `url` | | `gitlab_sli:rails_request_apdex:total` | Counter | 14.4 | The number of request-apdex measurements, [more information the development documentation](../../../development/application_slis/rails_request_apdex.md) | `endpoint_id`, `feature_category`, `request_urgency` | | `gitlab_sli:rails_request_apdex:success_total` | Counter | 14.4 | The number of successful requests that met the target duration for their urgency. Divide by `gitlab_sli:rails_requests_apdex:total` to get a success ratio | `endpoint_id`, `feature_category`, `request_urgency` | | `geo_ci_secure_files` | Gauge | 15.3 | Number of secure files on primary | `url` | diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index c4aa607fa4d..56583deca89 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab with Prometheus **(FREE SELF)** @@ -205,7 +205,7 @@ To use an external Prometheus server: ``` 1. Install and set up a dedicated Prometheus instance, if necessary, using the [official installation instructions](https://prometheus.io/docs/prometheus/latest/installation/). -1. Add the Prometheus server IP address to the [monitoring IP allowlist](../ip_whitelist.md). For example: +1. Add the Prometheus server IP address to the [monitoring IP allowlist](../ip_allowlist.md). For example: ```ruby gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '192.168.0.1'] @@ -353,7 +353,7 @@ To add a Prometheus dashboard for a single server GitLab setup: 1. Create a new data source in Grafana. 1. Name your data source (such as GitLab). -1. Select `Prometheus` in the type dropdown box. +1. Select `Prometheus` in the type dropdown list. 1. Add your Prometheus listen address as the URL, and set access to `Browser`. 1. Set the HTTP method to `GET`. 1. Save and test your configuration to verify that it works. @@ -381,7 +381,7 @@ memory, disk, and CPU utilization. The web exporter is a dedicated metrics server that allows splitting end-user and Prometheus traffic into two separate applications to improve performance and availability. -[Read more about the web exporter](puma_exporter.md). +[Read more about the web exporter](web_exporter.md). ### Redis exporter diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index d7a4a96cd9a..c2f84773b3a 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Node exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index 979a6bcd232..56da3155fd9 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PgBouncer exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index 95a6540bd19..0458a4a5bae 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL Server Exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/puma_exporter.md b/doc/administration/monitoring/prometheus/puma_exporter.md deleted file mode 100644 index a3e095f5f09..00000000000 --- a/doc/administration/monitoring/prometheus/puma_exporter.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'web_exporter.md' -remove_date: '2022-09-01' ---- - -This document was moved to [another location](web_exporter.md). - -<!-- This redirect file can be deleted after <2022-09-01>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index a5f12bbc52f..b50a2a4aebf 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index f4fa35c206e..b79e97bd937 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Registry exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/web_exporter.md b/doc/administration/monitoring/prometheus/web_exporter.md index 45a8e8d5640..5539526c501 100644 --- a/doc/administration/monitoring/prometheus/web_exporter.md +++ b/doc/administration/monitoring/prometheus/web_exporter.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web exporter (dedicated metrics server) **(FREE SELF)** diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index 9967cce5b73..9072bd1f344 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index fd9ab9b5972..0e85635b3d2 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Object storage **(FREE SELF)** @@ -20,7 +20,7 @@ GitLab has been tested by vendors and customers on a number of object storage pr - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatible mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +- [Azure Blob storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors, whose list is not officially established. - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. @@ -247,9 +247,9 @@ The connection settings match those provided by [fog-aws](https://github.com/fog | `aws_signature_version` | AWS signature version to use. `2` or `4` are valid options. Digital Ocean Spaces and other providers may need `2`. | `4` | | `enable_signature_v4_streaming` | Set to `true` to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be `false`. | `true` | | `region` | AWS region. | | -| `host` | S3 compatible host for when not using AWS. For example, `localhost` or `storage.example.com`. HTTPS and port 443 is assumed. | `s3.amazonaws.com` | -| `endpoint` | Can be used when configuring an S3 compatible service such as [MinIO](https://min.io), by entering a URL such as `http://127.0.0.1:9000`. This takes precedence over `host`. | (optional) | -| `path_style` | Set to `true` to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as `false` for AWS S3. | `false`. | +| `host` | DEPRECATED: Use `endpoint` instead. S3 compatible host for when not using AWS. For example, `localhost` or `storage.example.com`. HTTPS and port 443 is assumed. | `s3.amazonaws.com` | +| `endpoint` | Can be used when configuring an S3 compatible service such as [MinIO](https://min.io), by entering a URL such as `http://127.0.0.1:9000`. This takes precedence over `host`. Always use `endpoint` for consolidated form. | (optional) | +| `path_style` | Set to `true` to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Set to `true` for using [MinIO](https://min.io). Leave as `false` for AWS S3. | `false`. | | `use_iam_profile` | Set to `true` to use IAM profile instead of access keys. | `false` | | `aws_credentials_refresh_threshold_seconds` | Sets the [automatic refresh threshold](https://github.com/fog/fog-aws#controlling-credential-refresh-time-with-iam-authentication) when using temporary credentials in IAM. | `15` | @@ -277,10 +277,13 @@ Here are the valid connection parameters for GCS: |------------------------------|-------------------|---------| | `provider` | Provider name. | `Google` | | `google_project` | GCP project name. | `gcp-project-12345` | -| `google_client_email` | Email address of the service account. | `foo@gcp-project-12345.iam.gserviceaccount.com` | | `google_json_key_location` | JSON key path. | `/path/to/gcp-project-12345-abcde.json` | +| `google_json_key_string` | JSON key string. | `{ "type": "service_account", "project_id": "example-project-382839", ... }` | | `google_application_default` | Set to `true` to use [Google Cloud Application Default Credentials](https://cloud.google.com/docs/authentication/production#automatically) to locate service account credentials. | | +GitLab reads the value of `google_json_key_location`, then `google_json_key_string`, and finally, `google_application_default`. +It uses the first of these settings that has a value. + The service account must have permission to access the bucket. Learn more in Google's [Cloud Storage authentication documentation](https://cloud.google.com/storage/docs/authentication). @@ -296,7 +299,6 @@ For Omnibus installations, this is an example of the `connection` setting: gitlab_rails['object_store']['connection'] = { 'provider' => 'Google', 'google_project' => '<GOOGLE PROJECT>', - 'google_client_email' => '<GOOGLE CLIENT EMAIL>', 'google_json_key_location' => '<FILENAME>' } ``` @@ -342,7 +344,7 @@ containers. The [storage-specific form](#storage-specific-configuration) is not supported. For more details, see [how to transition to consolidated form](#transition-to-consolidated-form). The following are the valid connection parameters for Azure. Read the -[Azure Blob storage documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +[Azure Blob storage documentation](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) to learn more. | Setting | Description | Example | diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 8523b881730..7aeb05457c0 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fast lookup of authorized SSH keys in the database **(FREE SELF)** @@ -157,7 +157,7 @@ The capabilities of GitLab Shell are not limited to Git operations. If you are considering switching from OpenSSH to `gitlab-sshd`, consider these concerns: - The `gitlab-sshd` component is only available for - [Cloud Native Helm Charts](https://docs.gitlab.com/charts/) deployments. + [GitLab Helm chart](https://docs.gitlab.com/charts/) deployments. - `gitlab-sshd` supports the PROXY protocol. It can run behind proxy servers that rely on it, such as HAProxy. The PROXY protocol not enabled by default, but can be enabled with a Helm chart setting. - By default, `gitlab-sshd` binds to port 22, but you can configure a different port in the Helm chart. diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index a5c4795efea..ec2975baf52 100644 --- a/doc/administration/operations/filesystem_benchmarking.md +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File system performance benchmarking **(FREE SELF)** diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 179958c6df1..d18f41becd5 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performing operations in GitLab **(FREE SELF)** diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 4228b792fdc..75078568c44 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving repositories managed by GitLab **(FREE SELF)** diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 8e7594dfc2d..eb326c06e6a 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the bundled Puma instance of the GitLab package **(FREE SELF)** @@ -401,4 +401,4 @@ The output in `/tmp/puma.txt` may help diagnose the root cause. ## Related topics -- [Use a dedicated metrics server to export web metrics](../monitoring/prometheus/puma_exporter.md) +- [Use a dedicated metrics server to export web metrics](../monitoring/prometheus/web_exporter.md) diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index 627dfbeb66c..1ef985b8938 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails console **(FREE SELF)** @@ -240,6 +240,24 @@ project.id # => 2537 ``` +## Time an operation + +If you'd like to time one or more operations, use the following format, replacing +the placeholder `<operation>` with your Ruby or Rails commands of choice: + +```ruby +# A single operation +Benchmark.measure { <operation> } + +# A breakdown of multiple operations +Benchmark.bm do |x| + x.report(:label1) { <operation_1> } + x.report(:label2) { <operation_2> } +end +``` + +For more information, review [our developer documentation about benchmarks](../../development/performance.md#benchmarks). + ## Active Record objects ### Looking up database-persisted objects @@ -680,3 +698,21 @@ unlike with issues or merge requests. ```ruby ApplicationSetting.current ``` + +### Open object in `irb` + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +Sometimes it is easier to go through a method if you are in the context of the object. You can shim into the namespace of `Object` to let you open `irb` in the context of any object: + +```ruby +Object.define_method(:irb) { binding.irb } + +project = Project.last +# => #<Project id:2537 root/discard>> +project.irb +# Notice new context +irb(#<Project>)> web_url +# => "https://gitlab-example/root/discard" +``` diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 8069dad4d8d..401451d58b4 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User lookup via OpenSSH's AuthorizedPrincipalsCommand **(FREE SELF)** @@ -74,7 +74,7 @@ $ ssh-add -L | grep cert | ssh-keygen -L -f - ``` Technically that's not strictly true, for example, it could be -`prod-aearnfjord` if it's a SSH certificate you'd normally log in to +`prod-aearnfjord` if it's a SSH certificate you'd normally sign in to servers as the `prod-aearnfjord` user, but then you must specify your own `AuthorizedPrincipalsCommand` to do that mapping instead of using our provided default. @@ -108,7 +108,7 @@ Where `{KEY_ID}` is the `%i` argument passed to the script You need to customize the `sshUsers` part of that. It should be some principal that's guaranteed to be part of the key for all users -who can log in to GitLab, or you must provide a list of principals, +who can sign in to GitLab, or you must provide a list of principals, one of which is present for the user, for example: ```plaintext @@ -123,7 +123,7 @@ into multiple lines of `authorized_keys` output, as described in the `AuthorizedPrincipalsFile` documentation in `sshd_config(5)`. Normally when using the `AuthorizedKeysCommand` with OpenSSH the -principal is some "group" that's allowed to log into that +principal is some "group" that's allowed to sign in to that server. However with GitLab it's only used to appease OpenSSH's requirement for it, we effectively only care about the "key ID" being correct. Once that's extracted GitLab enforces its own ACLs for diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md index 65cb8ef1e6c..c6a33ed7ba9 100644 --- a/doc/administration/package_information/defaults.md +++ b/doc/administration/package_information/defaults.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package defaults **(FREE SELF)** diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md index 73059514e1c..d8f4551ca09 100644 --- a/doc/administration/package_information/deprecation_policy.md +++ b/doc/administration/package_information/deprecation_policy.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Omnibus GitLab deprecation policy **(FREE SELF)** diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md index d3a82b87116..4758b453135 100644 --- a/doc/administration/package_information/index.md +++ b/doc/administration/package_information/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package information **(FREE SELF)** @@ -53,7 +53,7 @@ Documentation on package signatures can be found at [Signed Packages](signed_pac Configuration file in `/etc/gitlab/gitlab.rb` is created on initial installation of the Omnibus GitLab package. On subsequent package upgrades, the configuration -file is not updated with new configuration. This is done in order to avoid +file is not updated with new configuration. This is done to avoid accidental overwrite of user configuration provided in `/etc/gitlab/gitlab.rb`. New configuration options are noted in the @@ -76,7 +76,7 @@ characters on each line. ## Init system detection -Omnibus GitLab attempts to query the underlying system in order to +Omnibus GitLab attempts to query the underlying system to check which init system it uses. This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure` run. diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md index e5afe6b85dd..0e46289a308 100644 --- a/doc/administration/package_information/licensing.md +++ b/doc/administration/package_information/licensing.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Licensing **(FREE SELF)** diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md index d19f5f67b74..ec406f8b458 100644 --- a/doc/administration/package_information/omnibus_packages.md +++ b/doc/administration/package_information/omnibus_packages.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Omnibus based packages and images **(FREE SELF)** diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md index d831e8cea7f..6409c5fdbc9 100644 --- a/doc/administration/package_information/postgresql_versions.md +++ b/doc/administration/package_information/postgresql_versions.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL versions shipped with Omnibus GitLab **(FREE SELF)** diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md index 351c2ac5d5f..34c8148e807 100644 --- a/doc/administration/package_information/signed_packages.md +++ b/doc/administration/package_information/signed_packages.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Signatures **(FREE SELF)** diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md index 5ccabd66ed0..00f1bc1eec3 100644 --- a/doc/administration/package_information/supported_os.md +++ b/doc/administration/package_information/supported_os.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported operating systems **(FREE SELF)** @@ -31,6 +31,7 @@ The following lists the currently supported OSs and their possible EOL dates. | Ubuntu 20.04 | GitLab CE / GitLab EE 13.2.0 | amd64, arm64 | [Ubuntu Install Documentation](https://about.gitlab.com/install/#ubuntu) | April 2025 | <https://wiki.ubuntu.com/Releases> | | Amazon Linux 2 | GitLab CE / GitLab EE 14.9.0 | amd64, arm64 | [Amazon Linux 2 Install Documentation](https://about.gitlab.com/install/#amazonlinux-2) | June 2023 | <https://aws.amazon.com/amazon-linux-2/faqs/> | | Raspberry Pi OS (Buster) (formerly known as Raspbian Buster) | GitLab CE 12.2.0 | armhf | [Raspberry Pi Install Documentation](https://about.gitlab.com/install/#raspberry-pi-os) | 2024 | [Raspberry Pi Details](https://www.raspberrypi.com/news/new-old-functionality-with-raspberry-pi-os-legacy/) | +| Raspberry Pi OS (Bullseye) | GitLab CE 15.5.0 | armhf | [Raspberry Pi Install Documentation](https://about.gitlab.com/install/#raspberry-pi-os) | 2026 | [Raspberry Pi Details](https://www.raspberrypi.com/news/raspberry-pi-os-debian-bullseye/) | NOTE: CentOS 8 was EOL on December 31, 2021. In GitLab 14.5 and later, diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 537840ce785..d04e3217f57 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Container Registry administration **(FREE SELF)** @@ -40,7 +40,9 @@ if you want to implement this. If you have installed GitLab from source: -1. You must [install Registry](https://docs.docker.com/registry/deploying/) by yourself. +1. You must [deploy a registry](https://docs.docker.com/registry/deploying/) using the image corresponding to the + version of GitLab you are installing + (for example: `registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab`) 1. After the installation is complete, to enable it, you must configure the Registry's settings in `gitlab.yml`. 1. Use the sample NGINX configuration file from under @@ -158,7 +160,7 @@ If your certificate provider provides the CA Bundle certificates, append them to An administrator may want the container registry listening on an arbitrary port such as `5678`. However, the registry and application server are behind an AWS application load balancer that only -listens on ports `80` and `443`. The administrator may simply remove the port number for +listens on ports `80` and `443`. The administrator may remove the port number for `registry_external_url`, so HTTP or HTTPS is assumed. Then, the rules apply that map the load balancer to the registry from ports `80` or `443` to the arbitrary port. This is important if users rely on the `docker login` example in the container registry. Here's an example: @@ -882,10 +884,41 @@ point to the correct registry URL and copy the `registry.key` file to each Sidek information, see the [Sidekiq configuration](../sidekiq.md) page. -To reduce the amount of [Container Registry disk space used by a given project](../troubleshooting/gitlab_rails_cheat_sheet.md#registry-disk-space-usage-by-project), +To reduce the amount of [Container Registry disk space used by a given project](#registry-disk-space-usage-by-project), administrators can clean up image tags and [run garbage collection](#container-registry-garbage-collection). +### Registry Disk Space Usage by Project + +To find the disk space used by each project, run the following in the +[GitLab Rails console](../operations/rails_console.md#starting-a-rails-console-session): + +```ruby +projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]] +# You need to specify the projects that you want to look through. You can get these in any manner. +projects = Project.last(100) + +projects.each do |p| + project_total_size = 0 + container_repositories = p.container_repositories + + container_repositories.each do |c| + c.tags.each do |t| + project_total_size = project_total_size + t.total_size unless t.total_size.nil? + end + end + + if project_total_size > 0 + projects_and_size << [p.project_id, p.creator.id, project_total_size, p.full_path] + end +end + +# print it as comma separated output +projects_and_size.each do |ps| + puts "%s,%s,%s,%s" % ps +end +``` + To remove image tags by running the cleanup policy, run the following commands in the [GitLab Rails console](../operations/rails_console.md): @@ -935,7 +968,7 @@ provided by `gitlab-ctl`. Prerequisites: - You must have installed GitLab by using an Omnibus package or the - [cloud native chart](https://docs.gitlab.com/charts/charts/registry/#garbage-collection). + [GitLab Helm chart](https://docs.gitlab.com/charts/charts/registry/#garbage-collection). - You must set the Registry to [read-only mode](#performing-garbage-collection-without-downtime). Running garbage collection causes downtime for the Container Registry. When you run this command on an instance in an environment where another instance is still writing to the Registry storage, @@ -1192,7 +1225,7 @@ and signed with the private key. The Registry then verifies that the signature matches the registry certificate specified in its configuration and allows the operation. GitLab background jobs processing (through Sidekiq) also interacts with Registry. -These jobs talk directly to Registry in order to handle image deletion. +These jobs talk directly to Registry to handle image deletion. ## Troubleshooting @@ -1292,8 +1325,8 @@ Check which files are in use: The output of these `openssl` commands should match, proving that the cert-key pair is a match: ```shell -openssl x509 -noout -modulus -in /var/opt/gitlab/registry/gitlab-registry.crt | openssl sha256 -openssl rsa -noout -modulus -in /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key | openssl sha256 +/opt/gitlab/embedded/bin/openssl x509 -noout -modulus -in /var/opt/gitlab/registry/gitlab-registry.crt | /opt/gitlab/embedded/bin/openssl sha256 +/opt/gitlab/embedded/bin/openssl rsa -noout -modulus -in /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key | /opt/gitlab/embedded/bin/openssl sha256 ``` If the two pieces of the certificate do not align, remove the files and run `gitlab-ctl reconfigure` diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index 40c1b9d795a..789863e8ed0 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Dependency Proxy administration **(FREE SELF)** diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 56786f334b0..a7ab0fb3246 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Package Registry administration **(FREE SELF)** diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 024fb12a51f..922f9a27aad 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to administer GitLab Pages.' --- @@ -243,7 +243,6 @@ control over how the Pages daemon runs and serves content in your environment. | `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`. | | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | -| `client_cert_key_pairs` | Client certificates and keys used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 14.8. | | `dir` | Working directory for configuration and secrets files. | | `enable` | Enable or disable GitLab Pages on the current system. | | `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`. | @@ -525,22 +524,6 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -### Support mutual TLS when calling the GitLab API - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 14.8. - -If GitLab has been [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl.html#enable-2-way-ssl-client-authentication), you need to add the client certificates to Pages: - -1. Configure in `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['client_cert_key_pairs'] = ['</path/to/cert>:</path/to/key>'] - ``` - - Where `</path/to/cert>` and `</path/to/key>` are the file paths to the client certificate and its respective key file. - Both of these files must be encoded in PEM format. -1. To configure Pages to validate the server certificates, [add the root CA to the system trust store](#using-a-custom-certificate-authority-ca). - ### ZIP serving and cache configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/392) in GitLab 13.7. @@ -754,7 +737,7 @@ To set the maximum number of GitLab Pages custom domains for a project: ## Running GitLab Pages on a separate server You can run the GitLab Pages daemon on a separate server to decrease the load on -your main application server. +your main application server. This configuration does not support mutual TLS (mTLS). See the [corresponding feature proposal](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) for more information. To configure GitLab Pages on a separate server: diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 14ac05e0293..52556809845 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages administration for source installations **(FREE SELF)** diff --git a/doc/administration/polling.md b/doc/administration/polling.md index 7f1e7a047cf..11f26f081cb 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Polling interval multiplier **(FREE SELF)** diff --git a/doc/administration/postgresql/database_load_balancing.md b/doc/administration/postgresql/database_load_balancing.md index f53b50192eb..6bf36ef4794 100644 --- a/doc/administration/postgresql/database_load_balancing.md +++ b/doc/administration/postgresql/database_load_balancing.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Load Balancing **(FREE SELF)** diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md index 7036502e377..8605ee94255 100644 --- a/doc/administration/postgresql/external.md +++ b/doc/administration/postgresql/external.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab using an external PostgreSQL service **(FREE SELF)** @@ -21,7 +21,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance: 1. If you are using a cloud-managed service, you may need to grant additional roles to your `gitlab` user: - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. - - Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. Azure Database for PostgreSQL - Flexible Server requires [allow-listing extensions before they can be installed](https://docs.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions). + - Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. Azure Database for PostgreSQL - Flexible Server requires [allow-listing extensions before they can be installed](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions). - Google Cloud SQL requires the [`cloudsqlsuperuser`](https://cloud.google.com/sql/docs/postgres/users#default-users) role. This is for the installation of extensions during installation and upgrades. As an alternative, diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index 8b811deee16..f48e537064a 100644 --- a/doc/administration/postgresql/index.md +++ b/doc/administration/postgresql/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring PostgreSQL for scaling **(FREE SELF)** diff --git a/doc/administration/postgresql/moving.md b/doc/administration/postgresql/moving.md index 23d377dba37..96076205281 100644 --- a/doc/administration/postgresql/moving.md +++ b/doc/administration/postgresql/moving.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving GitLab databases to a different PostgreSQL instance **(FREE SELF)** diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index b12edd4b9ad..91c689fadea 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 37471a4f491..0ee48047944 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM SELF)** @@ -1123,7 +1123,7 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>) ### Reinitialize a replica -If a replica cannot start or rejoin the cluster, or when it lags behind and can not catch up, it might be necessary to reinitialize the replica: +If a replica cannot start or rejoin the cluster, or when it lags behind and cannot catch up, it might be necessary to reinitialize the replica: 1. [Check the replication status](#check-replication-status) to confirm which server needs to be reinitialized. For example: diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md index 5428e44ccc0..77ff9fd2fe1 100644 --- a/doc/administration/postgresql/standalone.md +++ b/doc/administration/postgresql/standalone.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone PostgreSQL using Omnibus GitLab **(FREE SELF)** diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md deleted file mode 100644 index 8f27d41b75f..00000000000 --- a/doc/administration/pseudonymizer.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -stage: Systems -group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: 'index.md' ---- - -# Pseudonymizer (removed) **(ULTIMATE)** - -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/219952) in GitLab 14.7 and removed in 15.0. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/219952) in GitLab 14.7. diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index cf569cd81d0..2660caa80b3 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrity check Rake task **(FREE SELF)** diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index 5c6c99d099b..a4d027101dd 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Rake Tasks **(PREMIUM SELF)** diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 0d724bfd4dc..224ed63d3e6 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub import **(FREE SELF)** diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index cdad323733d..f6c5f84c500 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index c4401b49180..293efb1b7ae 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintenance Rake tasks **(FREE SELF)** @@ -310,6 +310,12 @@ To check the status of specific migrations, you can use the following Rake task: sudo gitlab-rake db:migrate:status ``` +To check the [tracking database on a Geo secondary site](../geo/setup/external_database.md#configure-the-tracking-database), you can use the following Rake task: + +```shell +sudo gitlab-rake db:migrate:status:geo +``` + This outputs a table with a `Status` of `up` or `down` for each Migration ID. diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index b7db3f26a60..d1dbc83ad86 100644 --- a/doc/administration/raketasks/praefect.md +++ b/doc/administration/raketasks/praefect.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Praefect Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 00bd71af6c5..e43fbac25e9 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project import/export administration **(FREE SELF)** diff --git a/doc/administration/raketasks/smtp.md b/doc/administration/raketasks/smtp.md index 49274501809..5e9e3544902 100644 --- a/doc/administration/raketasks/smtp.md +++ b/doc/administration/raketasks/smtp.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SMTP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index fc0ff23c5b1..d740aaa9c96 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage Rake tasks **(FREE SELF)** @@ -185,8 +185,7 @@ as most of the fixes are relatively high risk, involving running code on the Rai ### Read only projects -If you have [set projects read only](../troubleshooting/gitlab_rails_cheat_sheet.md#make-a-project-read-only-can-only-be-done-in-the-console) -they might fail to migrate. +If you have set projects as read only they might fail to migrate. 1. [Start a Rails console](../operations/rails_console.md#starting-a-rails-console-session). @@ -233,7 +232,7 @@ Delete the project using the Rails console: - Replace `admin_handle` with the handle of an instance administrator or with `root`. - Verify the output before proceeding. **There are no other checks performed**. -1. [Destroy the project](../troubleshooting/gitlab_rails_cheat_sheet.md#destroy-a-project) **immediately**: +1. [Destroy the project](../../user/project/working_with_projects.md#delete-a-project-using-console) **immediately**: ```ruby Projects::DestroyService.new(project, user).execute diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 216c0875645..b6f14bc6fa4 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads migrate Rake tasks **(FREE SELF)** @@ -166,33 +166,22 @@ GitLab provides a wrapper Rake task that migrates all uploaded files (for exampl attachments, and favicon) to local storage in one step. The wrapper task invokes individual Rake tasks to migrate files falling under each of these categories one by one. -For details on these Rake tasks, refer to [Individual Rake tasks](#individual-rake-tasks), -keeping in mind the task name in this case is `gitlab:uploads:migrate_to_local`. +For details on these Rake tasks, refer to [Individual Rake tasks](#individual-rake-tasks). +Keep in mind the task name in this case is `gitlab:uploads:migrate_to_local`. -To migrate uploads from object storage to local storage: +To migrate uploads from object storage to local storage, run the following Rake task: -1. Disable both `direct_upload` and `background_upload` under `uploads` settings in `gitlab.rb`: +**Omnibus GitLab installation** - ```ruby - gitlab_rails['uploads_object_store_direct_upload'] = false - gitlab_rails['uploads_object_store_background_upload'] = false - ``` - - Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure). - -1. Run the Rake task: - - **Omnibus Installation** - - ```shell - gitlab-rake "gitlab:uploads:migrate_to_local:all" - ``` +```shell +gitlab-rake "gitlab:uploads:migrate_to_local:all" +``` - **Source Installation** +**Source installation** - ```shell - sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:migrate_to_local:all - ``` +```shell +sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:migrate_to_local:all +``` After running the Rake task, you can disable object storage by undoing the changes described in the instructions to [configure object storage](../../uploads.md#using-object-storage). diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index bf6dc4fd776..831abee9739 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads sanitize Rake tasks **(FREE SELF)** diff --git a/doc/administration/read_only_gitlab.md b/doc/administration/read_only_gitlab.md index 387a1a75393..3718741e2e9 100644 --- a/doc/administration/read_only_gitlab.md +++ b/doc/administration/read_only_gitlab.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Place GitLab into a read-only state **(FREE SELF)** diff --git a/doc/administration/redis/index.md b/doc/administration/redis/index.md index fb5f6cc3a54..31ea879b289 100644 --- a/doc/administration/redis/index.md +++ b/doc/administration/redis/index.md @@ -2,7 +2,7 @@ type: index stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring Redis for scaling **(FREE SELF)** diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index b775b579fd4..1c2515099fe 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -2,7 +2,7 @@ type: howto stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis replication and failover with Omnibus GitLab **(PREMIUM SELF)** diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index d624fe28f80..7904fb1ded8 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -2,7 +2,7 @@ type: howto stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis replication and failover providing your own instance **(FREE SELF)** diff --git a/doc/administration/redis/standalone.md b/doc/administration/redis/standalone.md index bd5b30efb7b..c36d75a566d 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -2,7 +2,7 @@ type: howto stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone Redis using Omnibus GitLab **(FREE SELF)** diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index f9e5390c227..e568daed961 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -2,7 +2,7 @@ type: reference stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Redis **(FREE SELF)** diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 5d676dac000..45939b48f78 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 10,000 users **(PREMIUM SELF)** @@ -17,30 +17,37 @@ full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 200 RPS, Web: 20 RPS, Git (Pull): 20 RPS, Git (Push): 4 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|------------------------------------------|-------|-------------------------|------------------|----------------|-----------| -| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | `D8s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Gitaly<sup>5</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | `D16s v3` | -| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | `F32s v2` | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|------------------------------------------|-------|-------------------------|------------------|----------------| +| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly<sup>5</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | +| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -151,13 +158,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported infrastructure -As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -293,7 +296,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -506,7 +509,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1276,7 +1279,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Examples of the above could include [Google's Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) or [Amazon RDS](https://aws.amazon.com/rds/). @@ -1693,7 +1696,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1861,7 +1866,9 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -2012,46 +2019,7 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. If you're [using NFS](#configure-nfs-optional): - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - - 1. Edit `/etc/gitlab/gitlab.rb` and use the following configuration: - - ```ruby - ## Prevent GitLab from starting if NFS data mounts are not available - high_availability['mountpoint'] = '/var/opt/gitlab/git-data' - - ## Ensure UIDs and GIDs match between servers for permissions via NFS - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` - - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). 1. Confirm the node can connect to Gitaly: @@ -2189,7 +2157,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2319,9 +2286,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 96b1e541f92..a8e0e23512f 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 1,000 users **(FREE SELF)** @@ -12,7 +12,7 @@ full list of reference architectures, see If you are serving up to 1,000 users and you don't have strict availability requirements, a single-node solution with -[frequent backups](index.md#automated-backups) is appropriate for +[frequent backups](index.md#backups) is appropriate for many organizations. > - **Supported users (approximate):** 1,000 @@ -24,6 +24,7 @@ many organizations. > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 20 RPS, Web: 2 RPS, Git (Pull): 2 RPS, Git (Push): 1 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/1k)** +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). | Users | Configuration | GCP | AWS | Azure | |--------------|-------------------------|----------------|--------------|----------| @@ -83,11 +84,7 @@ Any "burstable" instance types are not recommended due to inconsistent performan As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -Be aware of the following specific call outs: - -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Swap diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 423dbc7abfb..7d67ac48b73 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 25,000 users **(PREMIUM SELF)** @@ -17,30 +17,37 @@ full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 500 RPS, Web: 50 RPS, Git (Pull): 50 RPS, Git (Push): 10 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/25k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|------------------------------------------|-------|-------------------------|------------------|--------------|-----------| -| External load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | `D16s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Gitaly<sup>5</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | `D32s v3` | -| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | `F32s v2` | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|------------------------------------------|-------|-------------------------|------------------|--------------| +| External load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly<sup>5</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | +| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -151,13 +158,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported infrastructure -As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -295,7 +298,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -508,7 +511,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1281,7 +1284,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1696,7 +1699,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1864,7 +1869,9 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -2017,46 +2024,8 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. If you're [using NFS](#configure-nfs-optional): - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - - 1. Edit `/etc/gitlab/gitlab.rb` and use the following configuration: - - ```ruby - ## Prevent GitLab from starting if NFS data mounts are not available - high_availability['mountpoint'] = '/var/opt/gitlab/git-data' - - ## Ensure UIDs and GIDs match between servers for permissions via NFS - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm the node can connect to Gitaly: ```shell @@ -2192,7 +2161,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2322,9 +2290,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 99cc6d47f6a..61ea435f63f 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 2,000 users **(FREE SELF)** @@ -18,6 +18,7 @@ For a full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 40 RPS, Web: 4 RPS, Git (Pull): 4 RPS, Git (Push): 1 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k)** +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). | Service | Nodes | Configuration | GCP | AWS | Azure | |----------------------------|-------|------------------------|-----------------|--------------|----------| @@ -31,9 +32,15 @@ For a full list of reference architectures, see | NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run as reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run as reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and [Azure Database for PostgreSQL](https://azure.microsoft.com/en-gb/services/postgresql/) is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. <!-- markdownlint-enable MD029 --> @@ -89,11 +96,7 @@ Any "burstable" instance types are not recommended due to inconsistent performan As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -Be aware of the following specific call outs: - -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ## Setup components @@ -177,7 +180,7 @@ details about managing SSL certificates and configuring NGINX, see the Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -249,7 +252,7 @@ to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -589,31 +592,6 @@ but this is dependent on workload. On each node perform the following: -1. If you're [using NFS](#configure-nfs-optional): - - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -742,7 +720,10 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). + 1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the node can connect to Gitaly. + 1. Tail the logs to see the requests: ```shell @@ -899,7 +880,7 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +- [Azure Blob storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -1026,8 +1007,13 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and [Azure Database for PostgreSQL](https://azure.microsoft.com/en-gb/services/postgresql/) is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. 3. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 5c227e3dc27..7484fafe1b0 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 3,000 users **(PREMIUM SELF)** @@ -27,29 +27,36 @@ For a full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 60 RPS, Web: 6 RPS, Git (Pull): 6 RPS, Git (Push): 1 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/3k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|-------------------------------------------|-------|-----------------------|-----------------|--------------|----------| -| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Gitaly<sup>5</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|-------------------------------------------|-------|-----------------------|-----------------|--------------| +| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Gitaly<sup>5</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -157,13 +164,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported infrastructure -As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -296,7 +299,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -790,7 +793,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1221,7 +1224,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1636,7 +1639,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -1803,35 +1808,12 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. On each node perform the following: -1. If you're [using NFS](#configure-nfs-optional): - - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -1979,7 +1961,10 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). + 1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the node can connect to Gitaly. + 1. Tail the logs to see the requests: ```shell @@ -2129,7 +2114,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2198,12 +2182,12 @@ cluster alongside your instance, read how to ## Supported modifications for lower user counts (HA) -The 3k GitLab reference architecture is the smallest we recommend that achieves High Availability (HA). -However, for environments that need to serve less users but maintain HA, there's several +The 3,000 user GitLab reference architecture is the smallest we recommend that achieves High Availability (HA). +However, for environments that need to serve fewer users but maintain HA, there are several supported modifications you can make to this architecture to reduce complexity and cost. -It should be noted that to achieve HA with GitLab, this architecture's makeup is ultimately what is -required. Each component has various considerations and rules to follow and this architecture +It should be noted that to achieve HA with GitLab, the 3,000 user architecture's makeup is ultimately what is +required. Each component has various considerations and rules to follow, and the 3,000 user architecture meets all of these. Smaller versions of this architecture will be fundamentally the same, but with smaller performance requirements, several modifications can be considered as follows: @@ -2283,9 +2267,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index bddec55ba71..88fc3649b3f 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 50,000 users **(PREMIUM SELF)** @@ -17,30 +17,37 @@ full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 1000 RPS, Web: 100 RPS, Git (Pull): 100 RPS, Git (Push): 20 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/50k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|------------------------------------------|-------|-------------------------|------------------|---------------|-----------| -| External load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | -| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | `D32s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | -| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Gitaly<sup>5</sup> | 3 | 64 vCPU, 240 GB memory | `n1-standard-64` | `m5.16xlarge` | `D64s v3` | -| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | `F32s v2` | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|------------------------------------------|-------|-------------------------|------------------|---------------| +| External load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | +| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | +| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly<sup>5</sup> | 3 | 64 vCPU, 240 GB memory | `n1-standard-64` | `m5.16xlarge` | +| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -151,13 +158,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported infrastructure -As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -302,7 +305,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -515,7 +518,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1289,7 +1292,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Examples of the above could include [Google's Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) or [Amazon RDS](https://aws.amazon.com/rds/). @@ -1706,7 +1709,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1874,7 +1879,9 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -2034,46 +2041,8 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. If you're [using NFS](#configure-nfs-optional): - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - - 1. Edit `/etc/gitlab/gitlab.rb` and use the following configuration: - - ```ruby - ## Prevent GitLab from starting if NFS data mounts are not available - high_availability['mountpoint'] = '/var/opt/gitlab/git-data' - - ## Ensure UIDs and GIDs match between servers for permissions via NFS - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm the node can connect to Gitaly: ```shell @@ -2209,7 +2178,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2339,9 +2307,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 0e599df7c1f..c8cf35a2e59 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 5,000 users **(PREMIUM SELF)** @@ -24,29 +24,36 @@ costly-to-operate environment by using the > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 100 RPS, Web: 10 RPS, Git (Pull): 10 RPS, Git (Push): 2 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/5k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|-------------------------------------------|-------|-------------------------|-----------------|--------------|----------| -| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Gitaly<sup>5</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | `D8s v3` | -| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | `c5.4xlarge` | `F16s v2`| -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|-------------------------------------------|-------|-------------------------|-----------------|--------------| +| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Gitaly<sup>5</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | +| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | `c5.4xlarge` | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -154,13 +161,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported infrastructure -As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -293,7 +296,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer is not able to connect. @@ -786,7 +789,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1218,7 +1221,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1633,7 +1636,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.71`: Sidekiq 1 - `10.6.0.72`: Sidekiq 2 @@ -1799,35 +1804,12 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. On each node perform the following: -1. If you're [using NFS](#configure-nfs-optional): - - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` depends on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -1978,7 +1960,10 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). + 1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the node can connect to Gitaly. + 1. Tail the logs to see the requests: ```shell @@ -2128,7 +2113,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2257,9 +2241,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/img/reference-architectures.png b/doc/administration/reference_architectures/img/reference-architectures.png Binary files differdeleted file mode 100644 index 0f8e663b57b..00000000000 --- a/doc/administration/reference_architectures/img/reference-architectures.png +++ /dev/null diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 7be12e12386..2cf9f2a1e83 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -2,44 +2,20 @@ type: reference, concepts stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architectures **(FREE SELF)** -You can set up GitLab on a single server or scale it up to serve many users. -This page details the recommended Reference Architectures that were built and -verified by the GitLab Quality and Support teams. - -Below is a chart representing each architecture tier and the number of users -they can handle. As your number of users grow with time, it's recommended that -you scale GitLab accordingly. - - -<!-- Internal link: https://docs.google.com/spreadsheets/d/1obYP4fLKkVVDOljaI3-ozhmCiPtEeMblbBKkf2OADKs/edit#gid=1403207183 --> - -For GitLab instances with less than 2,000 users, it's recommended that you use -the [default setup](#automated-backups) by -[installing GitLab](../../install/index.md) on a single machine to minimize -maintenance and resource costs. - -If your organization has more than 2,000 users, the recommendation is to scale the -GitLab components to multiple machine nodes. The machine nodes are grouped by -components. The addition of these nodes increases the performance and -scalability of to your GitLab instance. - -When scaling GitLab, there are several factors to consider: - -- Multiple application nodes to handle frontend traffic. -- A load balancer is added in front to distribute traffic across the application nodes. -- The application nodes connects to a shared file server and PostgreSQL and Redis services on the backend. +The GitLab Reference Architectures have been designed and tested by the +GitLab Quality and Support teams to provide recommended deployments at scale. ## Available reference architectures Depending on your workflow, the following recommended reference architectures may need to be adapted accordingly. Your workload is influenced by factors including how active your users are, how much automation you use, mirroring, -and repository/change size. Additionally the displayed memory values are +and repository/change size. Additionally, the displayed memory values are provided by [GCP machine types](https://cloud.google.com/compute/docs/machine-types). For different cloud vendors, attempt to select options that best match the provided architecture. @@ -70,7 +46,183 @@ The following Cloud Native Hybrid reference architectures, where select recommen A GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/#self-managed) license is required to get assistance from Support with troubleshooting the [2,000 users](2k_users.md) and higher reference architectures. -[Read more about our definition of scaled architectures](https://about.gitlab.com/support/#definition-of-scaled-architecture). +[Read more about our definition of scaled architectures](https://about.gitlab.com/support/definitions/#definition-of-scaled-architecture). + +## Deciding which architecture to use + +The Reference Architectures are designed to strike a balance between two important factors--performance and resilience. + +While they are designed to make it easier to set up GitLab at scale, it can still be a challenge to know which one will meet your requirements. + +As a general guide, **the more performant and/or resilient you want your environment to be, the more involved it will be**. + +This section explains the designs you can choose from. It begins with the least complexity, goes to the most, and ends with a decision tree. + +### Backups + +For environments serving 2,000 or fewer users we generally recommend that an [automated backup](../../raketasks/backup_gitlab.md#configuring-cron-to-make-daily-backups) strategy is used instead of HA. + +Backups can provide a good level of RPO / RTO while avoiding the complexities that come with HA. + +### High Availability (HA) + +High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. To achieve this however is involved, and the environments required can be sizable. + +For environments serving 3,000 or more users we generally recommend that a HA strategy is used as at this level outages will have a bigger impact against more users. All the architectures in this range have HA built in by design for this reason. + +For users who still need to have HA for a lower number of users this can also be achieved with an [adjusted 3K architecture as detailed here](3k_users.md#supported-modifications-for-lower-user-counts-ha). + +#### Do you need High Availability (HA)? + +As mentioned above, achieving HA does come at a cost. The environment's required are sizable as each component needs to be multiplied, which comes with additional actual and maintenance costs. + +For a lot of our customers with fewer than 3,000 users, we've found a backup strategy is sufficient and even preferable. While this does have a slower recovery time, it also means you have a much smaller architecture and less maintenance costs as a result. + +In general then, we'd only recommend you employ HA in the following scenarios: + +- When you have 3,000 or more users. +- When GitLab being down would critically impact your workflow. + +#### Zero Downtime Upgrades + +[Zero Downtime Upgrades](../../update/zero_downtime.md) are available for standard Reference Architecture environments with HA (Cloud Native Hybrid is not supported at this time). This allows for an environment to stay up during an upgrade, but the process is more involved as a result and has some limitations as detailed in the documentation. + +When going through this process it's worth noting that there may still be brief moments of downtime when the HA mechanisms tale effect. + +In most cases the downtime required for doing an upgrade in general shouldn't be substantial, so this is only recommended if it's a key requirement for you. + +### Cloud Native Hybrid (Kubernetes HA) + +As an additional layer of HA resilience you can deploy select components in Kubernetes, known as a Cloud Native Hybrid Reference Architecture. + +Note that this is an alternative and more **advanced** setup compared to a standard Reference Architecture. Running services in Kubernetes is well known to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. + +### GitLab Geo (Cross Regional Distribution / Disaster Recovery) + +With [GitLab Geo](../geo/index.md) you can have both distributed environments in different regions and a full Disaster Recovery (DR) setup in place. With this setup you would have 2 or more separate environments, with one being a primary that gets replicated to the others. In the rare event the primary site went down completely you could fail over to one of the other environments. + +This is an **advanced and involved** setup and should only be undertaken if you have DR as a key requirement. Decisions then on how each environment are configured would also need to be taken, such as if each environment itself would be the full size and / or have HA. + +### Decision Tree + +Below you can find the above guidance in the form of a decision tree. It's recommended you read through the above guidance in full first before though. + +```mermaid +%%{init: { 'theme': 'base' } }%% +graph TD + L1A(<b>What Reference Architecture should I use?</b>) --> L2A(More than 3000 users?) + L2A -->|No| L3A("<a href=#do-you-need-high-availability-ha>Do you need HA?</a><br>(or Zero-Downtime Upgrades)") --> |Yes| L4A><b>Recommendation</b><br><br>3K architecture with HA<br>including supported modifications] + L3A -->|No| L4B><b>Recommendation</b><br><br>Architecture closest to user<br>count with Backups] + L2A -->|Yes| L3B[Do you have experience with<br/>and want additional resilience<br/>with select components in Kubernetes?] + L3B -->|No| L4C><b>Recommendation</b><br><br>Architecture closest to user<br>count with HA] + L3B -->|Yes| L4D><b>Recommendation</b><br><br>Cloud Native Hybrid architecture<br>closest to user count] + + L5A("<a href=#gitlab-geo-cross-regional-distribution-disaster-recovery>Do you need cross regional distribution or disaster recovery?"</a>) --> |Yes| L6A><b>Additional Recommendation</b><br><br> GitLab Geo] + L4A -.- L5A + L4B -.- L5A + L4C -.- L5A + L4D -.- L5A + +classDef default fill:#FCA326 +linkStyle default fill:none,stroke:#7759C2 +``` + +## Recommended cloud providers and services + +NOTE: +The following lists are non-exhaustive. Generally, other cloud providers not listed +here likely work with the same specs, but this hasn't been validated. +Additionally, when it comes to other cloud provider services not listed here, +it's advised to be cautious as each implementation can be notably different +and should be tested thoroughly before production use. + +Through testing and real life usage, the Reference Architectures are validated and supported on the following cloud providers: + +<table> +<thead> + <tr> + <th>Reference Architecture</th> + <th>GCP</th> + <th>AWS</th> + <th>Azure</th> + <th>Bare Metal</th> + </tr> +</thead> +<tbody> + <tr> + <td>Omnibus</td> + <td>🟢</td> + <td>🟢</td> + <td>🟡<sup>1</sup></td> + <td>🟢</td> + </tr> + <tr> + <td>Cloud Native Hybrid</td> + <td>🟢</td> + <td>🟢</td> + <td></td> + <td></td> + </tr> +</tbody> +</table> + +1. We only recommend smaller setups (up to 2k) at this time on Azure due to performance issues at larger scales. See the [Recommendation Notes for Azure](#recommendation-notes-for-azure) section for more info. + +Additionally, the following cloud provider services are validated and supported for use as part of the Reference Architectures: + +<table> +<thead> + <tr> + <th>Cloud Service</th> + <th>GCP</th> + <th>AWS</th> + <th>Bare Metal</th> + </tr> +</thead> +<tbody> + <tr> + <td>Object Storage</td> + <td>🟢 <a href="https://cloud.google.com/storage" target="_blank">Cloud Storage</a></td> + <td>🟢 <a href="https://aws.amazon.com/s3/" target="_blank">S3</a></td> + <td>🟢 <a href="https://min.io/" target="_blank">MinIO</a></td> + </tr> + <tr> + <td>Database</td> + <td>🟢 <a href="https://cloud.google.com/sql" target="_blank" rel="noopener noreferrer">Cloud SQL</a></td> + <td>🟢 <a href="https://aws.amazon.com/rds/" target="_blank" rel="noopener noreferrer">RDS</a></td> + <td></td> + </tr> + <tr> + <td>Redis</td> + <td></td> + <td>🟢 <a href="https://aws.amazon.com/elasticache/" target="_blank" rel="noopener noreferrer">ElastiCache</a></td> + <td></td> + </tr> +</tbody> +</table> + +### Recommendation notes for the database services + +When selecting a database service, it should run a standard, performant, and [supported version](../../install/requirements.md#postgresql-requirements) of PostgreSQL with the following features: + +- Read Replicas for [Database Load Balancing](../postgresql/database_load_balancing.md). +- Cross Region replication for [GitLab Geo](../geo/index.md). + +Several cloud provider services are known not to support the above or have been found to have other issues and aren't recommended: + +- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible and not supported. See [14.4.0](../../update/index.md#1440) for more details. +- [Azure Database for PostgreSQL Single Server](https://azure.microsoft.com/en-gb/services/postgresql/#overview) (Single / Flexible) is **strongly not recommended** for use due to notable performance / stability issues or missing functionality. See [Recommendation Notes for Azure](#recommendation-notes-for-azure) for more details. +- [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + +### Recommendation notes for Azure + +Due to performance issues that we found with several key Azure services, we only recommend smaller architectures (up to 2k) to be deployed to Azure. For larger architectures, we recommend using another cloud provider. + +In addition to the above, you should be aware of the additional specific guidance for Azure: + +- **We outright strongly do not recommend [Azure Database for PostgreSQL Single Server](https://learn.microsoft.com/en-us/azure/postgresql/single-server/overview-single-server)** specifically due to significant performance and stability issues found. **For GitLab 14.0 and higher the service is not supported** due to it only supporting up to PostgreSQL 11. + - A new service, [Azure Database for Postgres Flexible Server](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/) has been released but due to it missing some functionality we don't recommend it at this time. +- [Azure Blob Storage](https://azure.microsoft.com/en-gb/services/storage/blobs/) has been found to have performance limits that can impact production use at certain times. However, this has only been seen in larger architectures. ## Validation and test results @@ -97,7 +249,7 @@ Network latency on the test environments between components on all Cloud Provide We aim to have a "test smart" approach where architectures tested have a good range that can also apply to others. Testing focuses on 10k Omnibus on GCP as the testing has shown this is a good bellwether for the other architectures and cloud providers as well as Cloud Native Hybrids. -The Standard Reference Architectures are designed to be platform agnostic, with everything being run on VMs via [Omnibus GitLab](https://docs.gitlab.com/omnibus/). While testing occurs primarily on GCP, ad-hoc testing has shown that they perform similarly on equivalently specced hardware on other Cloud Providers or if run on premises (bare-metal). +The Standard Reference Architectures are designed to be platform-agnostic, with everything being run on VMs via [Omnibus GitLab](https://docs.gitlab.com/omnibus/). While testing occurs primarily on GCP, ad-hoc testing has shown that they perform similarly on equivalently specced hardware on other Cloud Providers or if run on premises (bare-metal). Testing on these reference architectures is performed with the [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) @@ -111,14 +263,14 @@ per 1,000 users: - API: 20 RPS - Web: 2 RPS - Git (Pull): 2 RPS -- Git (Push): 0.4 RPS (rounded to nearest integer) +- Git (Push): 0.4 RPS (rounded to the nearest integer) ### How to interpret the results NOTE: Read our blog post on [how our QA team leverages GitLab performance testing tool](https://about.gitlab.com/blog/2020/02/18/how-were-building-up-performance-testing-of-gitlab/). -Testing is done publicly and all results are shared. +Testing is done publicly, and all results are shared. The following table details the testing done against the reference architectures along with the frequency and results. Additional testing is continuously evaluated, and the table is updated accordingly. @@ -292,170 +444,6 @@ The following table details the cost to run the different reference architecture </tr> </table> -## Recommended cloud providers and services - -NOTE: -The following lists are non exhaustive. Generally, other cloud providers not listed -here likely work with the same specs, but this hasn't been validated. -Additionally, when it comes to other cloud provider services not listed here, -it's advised to be cautious as each implementation can be notably different -and should be tested thoroughly before production use. - -Through testing and real life usage, the Reference Architectures are validated and supported on the following cloud providers: - -<table> -<thead> - <tr> - <th>Reference Architecture</th> - <th>GCP</th> - <th>AWS</th> - <th>Azure</th> - <th>Bare Metal</th> - </tr> -</thead> -<tbody> - <tr> - <td>Omnibus</td> - <td>✅</td> - <td>✅</td> - <td>✅</td> - <td>✅</td> - </tr> - <tr> - <td>Cloud Native Hybrid</td> - <td>✅</td> - <td>✅</td> - <td></td> - <td></td> - </tr> -</tbody> -</table> - -Additionally, the following cloud provider services are validated and supported for use as part of the Reference Architectures: - -<table> -<thead> - <tr> - <th>Cloud Service</th> - <th>GCP</th> - <th>AWS</th> - <th>Bare Metal</th> - </tr> -</thead> -<tbody> - <tr> - <td>Object Storage</td> - <td>✅ <a href="https://cloud.google.com/storage" target="_blank">Cloud Storage</a></td> - <td>✅ <a href="https://aws.amazon.com/s3/" target="_blank">S3</a></td> - <td>✅ <a href="https://min.io/" target="_blank">MinIO</a></td> - </tr> - <tr> - <td>Database</td> - <td>✅ <a href="https://cloud.google.com/sql" target="_blank" rel="noopener noreferrer">Cloud SQL</a></td> - <td>✅ <a href="https://aws.amazon.com/rds/" target="_blank" rel="noopener noreferrer">RDS</a></td> - <td></td> - </tr> - <tr> - <td>Redis</td> - <td></td> - <td>✅ <a href="https://aws.amazon.com/elasticache/" target="_blank" rel="noopener noreferrer">ElastiCache</a></td> - <td></td> - </tr> -</tbody> -</table> - -The following specific cloud provider services have been found to have issues in terms of either functionality or performance. As such, they either have caveats that should be considered or are not recommended: - -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Blob Storage](https://azure.microsoft.com/en-gb/services/storage/blobs/) has been found to have performance limits that can impact production use at certain times. For larger Reference Architectures the service may not be sufficient for production use and an alternative is recommended for use instead. -- [Azure Database for PostgreSQL Server](https://azure.microsoft.com/en-gb/services/postgresql/#overview) (Single / Flexible) is not recommended for use due to notable performance issues or missing functionality. - -NOTE: -As a general rule we unfortunately don't recommend Azure Services at this time. -If required, we advise thorough testing is done at your intended scale -over a sustained period to validate if the service is suitable. - -## Availability Components - -GitLab comes with the following components for your use, listed from least to -most complex: - -- [Automated backups](#automated-backups) -- [Traffic load balancer](#traffic-load-balancer) -- [Zero downtime updates](#zero-downtime-updates) -- [Automated database failover](#automated-database-failover) -- [Instance level replication with GitLab Geo](#instance-level-replication-with-gitlab-geo) - -As you implement these components, begin with a single server and then do -backups. Only after completing the first server should you proceed to the next. - -Also, not implementing extra servers for GitLab doesn't necessarily mean that you have -more downtime. Depending on your needs and experience level, single servers can -have more actual perceived uptime for your users. - -### Automated backups - -> - Level of complexity: **Low** -> - Required domain knowledge: PostgreSQL, GitLab configurations, Git - -This solution is appropriate for many teams that have the default GitLab installation. -With automatic backups of the GitLab repositories, configuration, and the database, -this can be an optimal solution if you don't have strict requirements. -[Automated backups](../../raketasks/backup_gitlab.md#configuring-cron-to-make-daily-backups) -is the least complex to setup. This provides a point-in-time recovery of a predetermined schedule. - -### Traffic load balancer **(PREMIUM SELF)** - -> - Level of complexity: **Medium** -> - Required domain knowledge: HAProxy, shared storage, distributed systems - -This requires separating out GitLab into multiple application nodes with an added -[load balancer](../load_balancer.md). The load balancer distributes traffic -across GitLab application nodes. Meanwhile, each application node connects to a -shared file server and database systems on the back end. This way, if one of the -application servers fails, the workflow is not interrupted. -[HAProxy](https://www.haproxy.org/) is recommended as the load balancer. - -With this added component you have a number of advantages compared -to the default installation: - -- Increase the number of users. -- Enable zero-downtime upgrades. -- Increase availability. - -For more details on how to configure a traffic load balancer with GitLab, you can refer -to any of the [available reference architectures](#available-reference-architectures) with more than 1,000 users. - -### Zero downtime updates **(PREMIUM SELF)** - -> - Level of complexity: **Medium** -> - Required domain knowledge: PostgreSQL, HAProxy, shared storage, distributed systems - -GitLab supports [zero-downtime upgrades](../../update/zero_downtime.md). -Single GitLab nodes can be updated with only a [few minutes of downtime](../../update/index.md#upgrade-based-on-installation-method). -To avoid this, we recommend to separate GitLab into several application nodes. -As long as at least one of each component is online and capable of handling the instance's usage load, your team's productivity is not interrupted during the update. - -### Automated database failover **(PREMIUM SELF)** - -> - Level of complexity: **High** -> - Required domain knowledge: PgBouncer, Patroni, shared storage, distributed systems - -By adding automatic failover for database systems, you can enable higher uptime -with additional database nodes. This extends the default database with -cluster management and failover policies. -[PgBouncer in conjunction with Patroni](../postgresql/replication_and_failover.md) -is recommended. - -### Instance level replication with GitLab Geo **(PREMIUM SELF)** - -> - Level of complexity: **Very High** -> - Required domain knowledge: Storage replication - -[GitLab Geo](../geo/index.md) allows you to replicate your GitLab -instance to other geographical locations as a read-only fully operational instance -that can also be promoted in case of disaster. - ## Deviating from the suggested reference architectures As a general guideline, the further away you move from the Reference Architectures, @@ -475,11 +463,3 @@ However, it is still an additional layer and may still add some support complexi Other technologies, like [Docker swarm](https://docs.docker.com/engine/swarm/) are not officially supported, but can be implemented at your own risk. In that case, GitLab Support is not able to help you. - -## Supported modifications for lower user count HA reference architectures - -The reference architectures for user counts [3,000](3k_users.md) and up support High Availability (HA). - -In the specific case you have the requirement to achieve HA but have a lower user count, select modifications to the [3,000 user](3k_users.md) architecture are supported. - -For more details, [refer to this section in the architecture's documentation](3k_users.md#supported-modifications-for-lower-user-counts-ha). diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 13fa8450996..6e97ffc3b47 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reply by email **(FREE SELF)** @@ -54,4 +54,4 @@ If it finds a reply key, it leaves your reply as a comment on the entity the notification was about (issue, merge request, commit...). For more details about the `Message-ID`, `In-Reply-To`, and `References headers`, -see [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). +see [RFC 5322](https://www.rfc-editor.org/rfc/rfc5322#section-3.6.4). diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index 0fbb4562995..ef6fd82a460 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Postfix for incoming email **(FREE SELF)** diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 4615499d6fa..08c1df3d5eb 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository checks **(FREE SELF)** diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 482cbd97e37..492c5306b26 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage **(FREE SELF)** diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 865daba9e89..77a5eae3747 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage types **(FREE SELF)** @@ -167,6 +167,10 @@ For example: "@groups/#{hash[0..1]}/#{hash[2..3]}/#{hash}.wiki.git" ``` +### Gitaly Cluster storage + +If Gitaly Cluster is used, Praefect manages storage locations. For more information, see [Praefect-generated replica paths](gitaly/index.md#praefect-generated-replica-paths-gitlab-150-and-later). + ### Object storage support This table shows which storable objects are storable in each storage type: diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index e5ec12054b8..1a1194e16a9 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to restart GitLab **(FREE SELF)** @@ -119,7 +119,7 @@ This should restart Puma, Sidekiq, GitLab Workhorse, and [Mailroom](reply_by_ema ## Helm chart installations There is no single command to restart the entire GitLab application installed via -the [cloud native Helm Chart](https://docs.gitlab.com/charts/). Usually, it should be +the [cloud-native Helm chart](https://docs.gitlab.com/charts/). Usually, it should be enough to restart a specific component separately (for example, `gitaly`, `puma`, `workhorse`, or `gitlab-shell`) by deleting all the pods related to it: diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 4148abf1bdc..6ab4f476e5e 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/administration/custom_hooks.html' --- diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md index b774b0d3e14..feaaa55aa59 100644 --- a/doc/administration/sidekiq/extra_sidekiq_processes.md +++ b/doc/administration/sidekiq/extra_sidekiq_processes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run multiple Sidekiq processes **(FREE SELF)** @@ -75,6 +75,9 @@ To start multiple processes: ] ``` + `*` which matches all workers. + As a result, the wildcard query must stay at the end of the list or the rules after it are ignored. + `*` cannot be combined with concrete queue names - `*, mailers` just handles the `mailers` queue. diff --git a/doc/administration/sidekiq/extra_sidekiq_routing.md b/doc/administration/sidekiq/extra_sidekiq_routing.md index ebbf4059290..56c51beb758 100644 --- a/doc/administration/sidekiq/extra_sidekiq_routing.md +++ b/doc/administration/sidekiq/extra_sidekiq_routing.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Queue routing rules **(FREE SELF)** @@ -161,20 +161,3 @@ After the Sidekiq routing rules are changed, administrators must take care with the migration to avoid losing jobs entirely, especially in a system with long queues of jobs. The migration can be done by following the migration steps mentioned in [Sidekiq job migration](sidekiq_job_migration.md) - -### Workers that cannot be migrated - -Some workers cannot share a queue with other workers - typically because -they check the size of their own queue - and so must be excluded from -this process. We recommend excluding these from any further worker -routing by adding a rule to keep them in their own queue, for example: - -```ruby -sidekiq['routing_rules'] = [ - ['tags=needs_own_queue', nil], - # ... -] -``` - -These queues must also be included in at least one -[Sidekiq queue group](extra_sidekiq_processes.md#start-multiple-processes). diff --git a/doc/administration/sidekiq/index.md b/doc/administration/sidekiq/index.md index f4e67fcb6dd..f17c248e60e 100644 --- a/doc/administration/sidekiq/index.md +++ b/doc/administration/sidekiq/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure an external Sidekiq instance **(FREE SELF)** @@ -377,6 +377,10 @@ To enable LDAP with the synchronization worker for Sidekiq: sudo gitlab-ctl reconfigure ``` +## Configure SAML Groups for SAML Group Sync + +If you use [SAML Group Sync](../../user/group/saml_sso/group_sync.md), you must configure [SAML Groups](../../integration/saml.md#saml-groups) on all your Sidekiq nodes. + ## Disable Rugged Calls into Rugged, Ruby bindings for `libgit2`, [lock the Sidekiq processes's GVL](https://silverhammermba.github.io/emberb/c/#c-in-ruby-threads), diff --git a/doc/administration/sidekiq/sidekiq_health_check.md b/doc/administration/sidekiq/sidekiq_health_check.md index 3477320a2ac..74b478c1913 100644 --- a/doc/administration/sidekiq/sidekiq_health_check.md +++ b/doc/administration/sidekiq/sidekiq_health_check.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq Health Check **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_job_migration.md b/doc/administration/sidekiq/sidekiq_job_migration.md index a3bc8b2959a..f61021ad4e7 100644 --- a/doc/administration/sidekiq/sidekiq_job_migration.md +++ b/doc/administration/sidekiq/sidekiq_job_migration.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq job migration **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_memory_killer.md b/doc/administration/sidekiq/sidekiq_memory_killer.md index 12381808523..bbf95bc45ce 100644 --- a/doc/administration/sidekiq/sidekiq_memory_killer.md +++ b/doc/administration/sidekiq/sidekiq_memory_killer.md @@ -1,7 +1,7 @@ --- stage: Data Stores -group: Memory -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +group: Application Performance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq MemoryKiller **(FREE SELF)** @@ -32,26 +32,12 @@ run as a process group leader (for example, using `chpst -P`). If using Omnibus The MemoryKiller is controlled using environment variables. -- `SIDEKIQ_DAEMON_MEMORY_KILLER`: defaults to 1. When set to 0, the MemoryKiller - works in _legacy_ mode. Otherwise, the MemoryKiller works in _daemon_ mode. - - In _legacy_ mode, the MemoryKiller checks the Sidekiq process RSS - ([Resident Set Size](https://github.com/mperham/sidekiq/wiki/Memory#rss)) - after each job. - - In _daemon_ mode, the MemoryKiller checks the Sidekiq process RSS every 3 seconds - (defined by `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`). - - `SIDEKIQ_MEMORY_KILLER_MAX_RSS` (KB): if this variable is set, and its value is greater than 0, the MemoryKiller is enabled. Otherwise the MemoryKiller is disabled. `SIDEKIQ_MEMORY_KILLER_MAX_RSS` defines the Sidekiq process allowed RSS. - In _legacy_ mode, if the Sidekiq process exceeds the allowed RSS then an irreversible - delayed graceful restart is triggered. The restart of Sidekiq happens - after `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` seconds. - - In _daemon_ mode, if the Sidekiq process exceeds the allowed RSS for longer than + If the Sidekiq process exceeds the allowed RSS for longer than `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` the graceful restart is triggered. If the Sidekiq process go below the allowed RSS within `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`, the restart is aborted. @@ -59,11 +45,11 @@ The MemoryKiller is controlled using environment variables. The default value for Omnibus packages is set [in the Omnibus GitLab repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb). -- `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` (KB): is used by _daemon_ mode. If the Sidekiq +- `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` (KB): If the Sidekiq process RSS (expressed in kilobytes) exceeds `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS`, an immediate graceful restart of Sidekiq is triggered. -- `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`: used in _daemon_ mode to define how +- `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`: Define how often to check process RSS, default to 3 seconds. - `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults to 900 seconds (15 minutes). diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md index 9bc8e473409..d2afe171e9c 100644 --- a/doc/administration/sidekiq/sidekiq_troubleshooting.md +++ b/doc/administration/sidekiq/sidekiq_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Sidekiq **(FREE SELF)** @@ -306,7 +306,7 @@ end ### Remove Sidekiq jobs for given parameters (destructive) The general method to kill jobs conditionally is the following command, which -removes jobs that are queued but not started. Running jobs can not be killed. +removes jobs that are queued but not started. Running jobs cannot be killed. ```ruby queue = Sidekiq::Queue.new('<queue name>') diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index c9647129104..4e49eef44df 100644 --- a/doc/administration/smime_signing_email.md +++ b/doc/administration/smime_signing_email.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Signing outgoing email with S/MIME **(FREE SELF)** diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 61d0b1ec50a..89a571946af 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Snippets settings **(FREE SELF)** diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index a288b19f164..ef89e38be6f 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md index 0d70744e942..56e73150616 100644 --- a/doc/administration/system_hooks.md +++ b/doc/administration/system_hooks.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 5a272025987..61fda91ba71 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform state administration **(FREE)** diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md index 93419751251..b0dc995c684 100644 --- a/doc/administration/timezone.md +++ b/doc/administration/timezone.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changing your time zone **(FREE SELF)** @@ -27,7 +27,7 @@ This Rake task does not list time zones in TZInfo format required by Omnibus Git GitLab defaults its time zone to UTC. It has a global time zone configuration parameter in `/etc/gitlab/gitlab.rb`. -To obtain a list of time zones, log in to your GitLab application server and run a command that generates a list of time zones in TZInfo format for the server. For example, install `timedatectl` and run `timedatectl list-timezones`. +To obtain a list of time zones, sign in to your GitLab application server and run a command that generates a list of time zones in TZInfo format for the server. For example, install `timedatectl` and run `timedatectl list-timezones`. To update, add the time zone that best applies to your location. For example: diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index faddf12b97d..32b07d8c4af 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -26,4 +26,4 @@ and summarize raw `strace` data. ## `kubesos` -The [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) utility retrieves GitLab cluster configuration and logs from GitLab Cloud Native chart deployments. +The [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) utility retrieves GitLab cluster configuration and logs from GitLab Helm chart deployments. diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 40bb15ecb70..20ce52a9094 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Rails Console Cheat Sheet **(FREE SELF)** @@ -62,308 +62,6 @@ Notify.test_email(e, "Test email for #{n}", 'Test email').deliver_now Notify.test_email(u.email, "Test email for #{u.name}", 'Test email').deliver_now ``` -## Open object in `irb` - -Sometimes it is easier to go through a method if you are in the context of the object. You can shim into the namespace of `Object` to let you open `irb` in the context of any object: - -```ruby -Object.define_method(:irb) { binding.irb } - -project = Project.last -# => #<Project id:2537 root/discard>> -project.irb -# Notice new context -irb(#<Project>)> web_url -# => "https://gitlab-example/root/discard" -``` - -## View all keys in cache - -```ruby -Rails.cache.instance_variable_get(:@data).keys -``` - -## Profile a page - -```ruby -url = '<url/of/the/page>' - -# Before 11.6.0 -logger = Logger.new($stdout) -admin_token = User.find_by_username('<admin-username>').personal_access_tokens.first.token -app.get("#{url}/?private_token=#{admin_token}") - -# From 11.6.0 -admin = User.find_by_username('<admin-username>') -Gitlab::Profiler.with_user(admin) { app.get(url) } -``` - -## Using the GitLab profiler inside console (used as of 10.5) - -```ruby -logger = Logger.new($stdout) -admin = User.find_by_username('<admin-username>') -Gitlab::Profiler.profile('<url/of/the/page>', logger: logger, user: admin) -``` - -## Time an operation - -```ruby -# A single operation -Benchmark.measure { <operation> } - -# A breakdown of multiple operations -Benchmark.bm do |x| - x.report(:label1) { <operation_1> } - x.report(:label2) { <operation_2> } -end -``` - -## Projects - -### Clear a project's cache - -```ruby -ProjectCacheWorker.perform_async(project.id) -``` - -### Expire the .exists? cache - -```ruby -project.repository.expire_exists_cache -``` - -### Make all projects private - -```ruby -Project.update_all(visibility_level: 0) -``` - -### Find projects that are pending deletion - -```ruby -# -# This section lists all the projects which are pending deletion -# -projects = Project.where(pending_delete: true) -projects.each do |p| - puts "Project ID: #{p.id}" - puts "Project name: #{p.name}" - puts "Repository path: #{p.repository.full_path}" -end - -# -# Assign a user (the root user does) -# -user = User.find_by_username('root') - -# -# For each project listed repeat these two commands -# - -# Find the project, update the xxx-changeme values from above -project = Project.find_by_full_path('group-changeme/project-changeme') - -# Immediately delete the project -::Projects::DestroyService.new(project, user, {}).execute -``` - -### Destroy a project - -```ruby -project = Project.find_by_full_path('<project_path>') -user = User.find_by_username('<username>') -ProjectDestroyWorker.perform_async(project.id, user.id, {}) -# or ProjectDestroyWorker.new.perform(project.id, user.id, {}) -# or Projects::DestroyService.new(project, user).execute -``` - -If this fails, display why it doesn't work with: - -```ruby -project = Project.find_by_full_path('<project_path>') -project.delete_error -``` - -### Remove fork relationship manually - -```ruby -p = Project.find_by_full_path('<project_path>') -u = User.find_by_username('<username>') -::Projects::UnlinkForkService.new(p, u).execute -``` - -### Make a project read-only (can only be done in the console) - -```ruby -# Make a project read-only -project.repository_read_only = true; project.save - -# OR -project.update!(repository_read_only: true) -``` - -### Transfer project from one namespace to another - -```ruby -p = Project.find_by_full_path('<project_path>') - - # To set the owner of the project - current_user= p.creator - -# Namespace where you want this to be moved. -namespace = Namespace.find_by_full_path("<new_namespace>") - -::Projects::TransferService.new(p, current_user).execute(namespace) -``` - -### Bulk update service integration password for _all_ projects - -For example, change the Jira user's password for all projects that have the Jira -integration active: - -```ruby -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'JiraService' AND s.active = true") - -p.each do |project| - project.jira_integration.update_attribute(:password, '<your-new-password>') -end -``` - -### Bulk update push rules for _all_ projects - -For example, enable **Check whether the commit author is a GitLab user** and **Do not allow users to remove Git tags with `git push`** checkboxes, and create a filter for allowing commits from a specific email domain only: - -``` ruby -Project.find_each do |p| - pr = p.push_rule || PushRule.new(project: p) - # Check whether the commit author is a GitLab user - pr.member_check = true - # Do not allow users to remove Git tags with `git push` - pr.deny_delete_tag = true - # Commit author's email - pr.author_email_regex = '@domain\.com$' - pr.save! -end -``` - -### Bulk update to change all the Jira integrations to Jira instance-level values - -To change all Jira project to use the instance-level integration settings: - -1. In a Rails console: - - ```ruby - jira_integration_instance_id = Integrations::Jira.find_by(instance: true).id - Integrations::Jira.where(active: true, instance: false, template: false, inherit_from_id: nil).find_each do |integration| - integration.update_attribute(:inherit_from_id, jira_integration_instance_id) - end - ``` - -1. Modify and save again the instance-level integration from the UI to propagate the changes to all the group-level and project-level integrations. - -### Check if Jira Cloud is linked to a namespace - -```ruby -JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup')) -``` - -### Check if Jira Cloud is linked to a project - -```ruby -Project.find_by_full_path('path/to/project').jira_subscription_exists? -``` - -### Check if Jira Cloud URL is linked to any namespace - -```ruby -installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net") -installation.subscriptions -``` - -### Bulk update to disable the Slack Notification service - -To disable notifications for all projects that have Slack service enabled, do: - -```ruby -# Grab all projects that have the Slack notifications enabled -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'SlackService' AND s.active = true") - -# Disable the service on each of the projects that were found. -p.each do |project| - project.slack_service.update_attribute(:active, false) -end -``` - -### Incorrect repository statistics shown in the GUI - -After [reducing a repository size with third-party tools](../../user/project/repository/reducing_the_repo_size_using_git.md) -the displayed size may still show old sizes or commit numbers. To force an update, do: - -```ruby -p = Project.find_by_full_path('<namespace>/<project>') -pp p.statistics -p.statistics.refresh! -pp p.statistics -# compare with earlier values - -# check the total artifact storage space separately -builds_with_artifacts = p.builds.with_downloadable_artifacts.all - -artifact_storage = 0 -builds_with_artifacts.find_each do |build| - artifact_storage += build.artifacts_size -end - -puts "#{artifact_storage} bytes" -``` - -### Identify deploy keys associated with blocked and non-member users - -When the user who created a deploy key is blocked or removed from the project, the key -can no longer be used to push to protected branches in a private project (see [issue #329742](https://gitlab.com/gitlab-org/gitlab/-/issues/329742)). -The following script identifies unusable deploy keys: - -```ruby -ghost_user_id = User.ghost.id - -DeployKeysProject.with_write_access.find_each do |deploy_key_mapping| - project = deploy_key_mapping.project - deploy_key = deploy_key_mapping.deploy_key - user = deploy_key.user - - access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project) - - # can_push_for_ref? tests if deploy_key can push to default branch, which is likely to be protected - can_push = access_checker.can_do_action?(:push_code) - can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref) - - next if access_checker.allowed? && can_push && can_push_to_default - - if user.nil? || user.id == ghost_user_id - username = 'none' - state = '-' - else - username = user.username - user_state = user.state - end - - puts "Deploy key: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') + - ", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') + - ", User: #{username}, User state: #{user_state}" -end -``` - -### Find projects using an SQL query - -Find and store an array of projects based on an SQL query: - -```ruby -# Finds projects that end with '%ject' -projects = Project.find_by_sql("SELECT * FROM projects WHERE name LIKE '%ject'") -=> [#<Project id:12 root/my-first-project>>, #<Project id:13 root/my-second-project>>] -``` - ## Imports and exports ### Import a project @@ -435,37 +133,6 @@ repeat the above procedure after, and report the output to [GitLab Support](https://about.gitlab.com/support/). -## Repository - -### Search sequence of pushes to a repository - -If it seems that a commit has gone "missing", search the sequence of pushes to a repository. -[This StackOverflow article](https://stackoverflow.com/questions/13468027/the-mystery-of-the-missing-commit-across-merges) -describes how you can end up in this state without a force push. Another cause can be a misconfigured [server hook](../server_hooks.md) that changes a HEAD ref via a `git reset` operation. - -If you look at the output from the sample code below for the target branch, you -see a discontinuity in the from/to commits as you step through the output. The `commit_from` of each new push should equal the `commit_to` of the previous push. A break in that sequence indicates one or more commits have been "lost" from the repository history. - -The following example checks the last 100 pushes and prints the `commit_from` and `commit_to` entries: - -```ruby -p = Project.find_by_full_path('u/p') -p.events.pushed_action.last(100).each do |e| - printf "%-20.20s %8s...%8s (%s) -", e.push_event_payload[:ref], e.push_event_payload[:commit_from], e.push_event_payload[:commit_to], e.author.try(:username) -end -``` - -Example output showing break in sequence at line 4: - -```plaintext -master f21b07713251e04575908149bdc8ac1f105aabc3...6bc56c1f46244792222f6c85b11606933af171de (root) -master 6bc56c1f46244792222f6c85b11606933af171de...132da6064f5d3453d445fd7cb452b148705bdc1b (root) -master 132da6064f5d3453d445fd7cb452b148705bdc1b...a62e1e693150a2e46ace0ce696cd4a52856dfa65 (root) -master 58b07b719a4b0039fec810efa52f479ba1b84756...f05321a5b5728bd8a89b7bf530aa44043c951dce (root) -master f05321a5b5728bd8a89b7bf530aa44043c951dce...7d02e575fd790e76a3284ee435368279a5eb3773 (root) -``` - ## Mirrors ### Find mirrors with "bad decrypt" errors @@ -474,36 +141,7 @@ This content has been converted to a Rake task, see [verify database values can ### Transfer mirror users and tokens to a single service account -Use case: If you have multiple users using their own GitHub credentials to set up -repository mirroring, mirroring breaks when people leave the company. Use this -script to migrate disparate mirroring users and tokens into a single service account: - -```ruby -svc_user = User.find_by(username: 'ourServiceUser') -token = 'githubAccessToken' - -Project.where(mirror: true).each do |project| - import_url = project.import_url - - # The url we want is https://token@project/path.git - repo_url = if import_url.include?('@') - # Case 1: The url is something like https://23423432@project/path.git - import_url.split('@').last - elsif import_url.include?('//') - # Case 2: The url is something like https://project/path.git - import_url.split('//').last - end - - next unless repo_url - - final_url = "https://#{token}@#{repo_url}" - - project.mirror_user = svc_user - project.import_url = final_url - project.username_only_import_url = final_url - project.save -end -``` +This content has been moved to [Troubleshooting Repository mirroring](../../user/project/repository/mirror/index.md#transfer-mirror-users-and-tokens-to-a-single-service-account-in-rails-console). ## Users @@ -627,147 +265,6 @@ group = Group.find_by_full_path 'group' user.max_member_access_for_group group.id ``` -## Groups - -### Transfer group to another location - -```ruby -user = User.find_by_username('<username>') -group = Group.find_by_name("<group_name>") -parent_group = Group.find_by(id: "<group_id>") -service = ::Groups::TransferService.new(group, user) -service.execute(parent_group) -``` - -### Count unique users in a group and subgroups - -```ruby -group = Group.find_by_path_or_name("groupname") -members = [] -for member in group.members_with_descendants - members.push(member.user_name) -end - -members.uniq.length -``` - -```ruby -group = Group.find_by_path_or_name("groupname") - -# Count users from subgroup and up (inherited) -group.members_with_parents.count - -# Count users from the parent group and down (specific grants) -parent.members_with_descendants.count -``` - -### Find groups that are pending deletion - -```ruby -# -# This section lists all the groups which are pending deletion -# -Group.all.each do |g| - if g.marked_for_deletion? - puts "Group ID: #{g.id}" - puts "Group name: #{g.name}" - puts "Group path: #{g.full_path}" - end -end -``` - -### Delete a group - -```ruby -GroupDestroyWorker.perform_async(group_id, user_id) -``` - -### Modify group project creation - -```ruby -# Project creation levels: 0 - No one, 1 - Maintainers, 2 - Developers + Maintainers -group = Group.find_by_path_or_name('group-name') -group.project_creation_level=0 -``` - -### Modify group - disable 2FA requirement - -WARNING: -When disabling the 2FA Requirement on a subgroup, the whole parent group (including all subgroups) is affected by this change. - -```ruby -group = Group.find_by_path_or_name('group-name') -group.require_two_factor_authentication=false -group.save -``` - -### Check and toggle a feature for all projects in a group - -```ruby -projects = Group.find_by_name('_group_name').projects -projects.each do |p| - state = p.<feature-name>? - - if state - puts "#{p.name} has <feature-name> already enabled. Skipping..." - else - puts "#{p.name} didn't have <feature-name> enabled. Enabling..." - p.project_feature.update!(builds_access_level: ProjectFeature::PRIVATE) - end -end -``` - -To find features that can be toggled, run `pp p.project_feature`. -Available permission levels are listed in -[concerns/featurable.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/featurable.rb). - -### Get all error messages associated with groups, subgroups, members, and requesters - -Collect error messages associated with groups, subgroups, members, and requesters. This -captures error messages that may not appear in the Web interface. This can be especially helpful -for troubleshooting issues with [LDAP group sync](../auth/ldap/ldap_synchronization.md#group-sync) -and unexpected behavior with users and their membership in groups and subgroups. - -```ruby -# Find the group and subgroup -group = Group.find_by_full_path("parent_group") -subgroup = Group.find_by_full_path("parent_group/child_group") - -# Group and subgroup errors -group.valid? -group.errors.map(&:full_messages) - -subgroup.valid? -subgroup.errors.map(&:full_messages) - -# Group and subgroup errors for the members AND requesters -group.requesters.map(&:valid?) -group.requesters.map(&:errors).map(&:full_messages) -group.members.map(&:valid?) -group.members.map(&:errors).map(&:full_messages) -group.members_and_requesters.map(&:errors).map(&:full_messages) - -subgroup.requesters.map(&:valid?) -subgroup.requesters.map(&:errors).map(&:full_messages) -subgroup.members.map(&:valid?) -subgroup.members.map(&:errors).map(&:full_messages) -subgroup.members_and_requesters.map(&:errors).map(&:full_messages) -``` - -## Routes - -### Remove redirecting routes - -See <https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41758#note_54828133>. - -```ruby -path = 'foo' -conflicting_permanent_redirects = RedirectRoute.matching_path_and_descendants(path) - -# Check that conflicting_permanent_redirects is as expected -conflicting_permanent_redirects.destroy_all -``` - ## Merge requests ### Close a merge request @@ -972,37 +469,7 @@ License.select(&TYPE).each(&:destroy!) ### Registry Disk Space Usage by Project -As a GitLab administrator, you may want to reduce disk space consumption. -A common culprit is Docker Registry images that are no longer in use. To find -the storage broken down by each project, run the following in the -[GitLab Rails console](../operations/rails_console.md): - -```ruby -projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]] -# You need to specify the projects that you want to look through. You can get these in any manner. -projects = Project.last(100) - -projects.each do |p| - project_total_size = 0 - container_repositories = p.container_repositories - - container_repositories.each do |c| - c.tags.each do |t| - project_total_size = project_total_size + t.total_size unless t.total_size.nil? - end - end - - if project_total_size > 0 - projects_and_size << [p.project_id, p.creator.id, project_total_size, p.full_path] - end -end - -# projects_and_size is filled out now -# maybe print it as comma separated output? -projects_and_size.each do |ps| - puts "%s,%s,%s,%s" % ps -end -``` +Find this content in the [Container Registry troubleshooting documentation](../packages/container_registry.md#registry-disk-space-usage-by-project). ### Run the Cleanup policy now @@ -1012,14 +479,6 @@ Find this content in the [Container Registry troubleshooting documentation](../p This content has been moved to [Troubleshooting Sidekiq](sidekiq.md). -## Redis - -### Connect to Redis (omnibus) - -```shell -/opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket -``` - ## LFS ### Get information about LFS objects and associated project @@ -1124,152 +583,19 @@ There is an [issue to implement this functionality in the Admin UI](https://gitl ### Artifacts -#### Find failed artifacts - -```ruby -Geo::JobArtifactRegistry.failed -``` - -#### Get a count of the synced artifacts - -```ruby -Geo::JobArtifactRegistry.synced.count -``` - -#### Find `ID` of synced artifacts that are missing on primary - -```ruby -Geo::JobArtifactRegistry.synced.missing_on_primary.pluck(:artifact_id) -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#find-failed-artifacts). ### Repository verification failures -#### Get the number of verification failed repositories - -```ruby -Geo::ProjectRegistry.verification_failed('repository').count -``` - -#### Find the verification failed repositories - -```ruby -Geo::ProjectRegistry.verification_failed('repository') -``` - -### Find repositories that failed to sync - -```ruby -Geo::ProjectRegistry.sync_failed('repository') -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#repository-verification-failures). ### Resync repositories -#### Queue up all repositories for resync. Sidekiq handles each sync - -```ruby -Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true) -``` - -#### Sync individual repository now - -```ruby -project = Project.find_by_full_path('<group/project>') - -Geo::RepositorySyncService.new(project).execute -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#resync-repositories). ### Blob types -- `Ci::JobArtifact` -- `Ci::PipelineArtifact` -- `LfsObject` -- `MergeRequestDiff` -- `Packages::PackageFile` -- `PagesDeployment` -- `Terraform::StateVersion` -- `Upload` - -`Packages::PackageFile` is used in the following examples, but things generally work the same for the other Blob types. - -#### The Replicator - -The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it): - -```ruby -model_record = Packages::PackageFile.last -model_record.replicator.registry.replicator.model_record # just showing that these methods exist -``` - -#### Replicate a package file, synchronously, given an ID - -```ruby -model_record = Packages::PackageFile.find(id) -model_record.replicator.send(:download) -``` - -#### Replicate a package file, synchronously, given a registry ID - -```ruby -registry = Geo::PackageFileRegistry.find(registry_id) -registry.replicator.send(:download) -``` - -#### Verify package files on the secondary manually - -This iterates over all package files on the secondary, looking at the -`verification_checksum` stored in the database (which came from the primary) -and then calculate this value on the secondary to check if they match. This -does not change anything in the UI: - -```ruby -# Run on secondary -status = {} - -Packages::PackageFile.find_each do |package_file| - primary_checksum = package_file.verification_checksum - secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path) - verification_status = (primary_checksum == secondary_checksum) - - status[verification_status.to_s] ||= [] - status[verification_status.to_s] << package_file.id -end - -# Count how many of each value we get -status.keys.each {|key| puts "#{key} count: #{status[key].count}"} - -# See the output in its entirety -status -``` - -### Repository types newer than project/wiki repositories - -- `SnippetRepository` -- `GroupWikiRepository` - -`SnippetRepository` is used in the examples below, but things generally work the same for the other Repository types. - -#### The Replicator - -The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it). - -```ruby -model_record = SnippetRepository.last -model_record.replicator.registry.replicator.model_record # just showing that these methods exist -``` - -#### Replicate a snippet repository, synchronously, given an ID - -```ruby -model_record = SnippetRepository.find(id) -model_record.replicator.send(:sync_repository) -``` - -#### Replicate a snippet repository, synchronously, given a registry ID - -```ruby -registry = Geo::SnippetRepositoryRegistry.find(registry_id) -registry.replicator.send(:sync_repository) -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#blob-types). ## Generate Service Ping @@ -1311,3 +637,24 @@ Prints the metrics saved in `conversational_development_index_metrics`. ```shell rake gitlab:usage_data:generate_and_send ``` + +## GraphQL + +Call a [GraphQL](../../api/graphql/getting_started.md) endpoint through the Rails console: + +```ruby +query = <<~EOQ +query securityGetProjects($search: String!) { + projects(search: $search) { + nodes { + path + } + } +} +EOQ + +variables = { "search": "gitlab" } + +result = GitlabSchema.execute(query, variables: variables, context: { current_user: current_user }) +result.to_h +``` diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md index 429dc79e95f..ce548f9e100 100644 --- a/doc/administration/troubleshooting/index.md +++ b/doc/administration/troubleshooting/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting a GitLab installation **(FREE SELF)** diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index c1a428018c2..0c6fcd31d1d 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 9e3d3d47a10..8a76d4f88ab 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL **(FREE SELF)** @@ -109,7 +109,7 @@ This section is for links to information elsewhere in the GitLab documentation. - Deploying PostgreSQL on Azure Database for PostgreSQL - Flexible Server may result in an error stating `extension "btree_gist" is not allow-listed for "azure_pg_admin" users in Azure Database for PostgreSQL` - To resolve the above error, [allow-list the extension](https://docs.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions) prior to install. + To resolve the above error, [allow-list the extension](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions) prior to install. ## Support topics diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index c5f3f0ed8d1..245ff9f4982 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -50,7 +50,7 @@ following issues: - `openssl` works when specifying the path to the certificate: ```shell - /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443 + /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443 -servername gitlab.domain.tld ``` If you have the previously described issues, add your certificate to diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index d240103a51c..a249d5bd133 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 2dd8f1ed819..f0def7320cc 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads administration **(FREE SELF)** diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index 0a3f351c695..a767132db0f 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,17 +1,24 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Modify global user settings **(FREE SELF)** GitLab administrators can modify user settings for the entire GitLab instance. -## Prevent new users from creating top-level groups +## Use configuration files to prevent new users from creating top-level groups By default, new users can create top-level groups. To disable new users' -ability to create top-level groups (does not affect existing users' setting): +ability to create top-level groups (does not affect existing users' setting), GitLab administrators can modify this setting: + +- In GitLab 15.5 and later, using either: + - The [GitLab UI](../user/admin_area/settings/account_and_limit_settings.md#prevent-users-from-creating-top-level-groups). + - The [application setting API](../api/settings.md#change-application-settings). +- In GitLab 15.4 and earlier, in a configuration file by following the steps in this section. + +To disable new users' ability to create top-level groups using the configuation file: **Omnibus GitLab installations** diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index d8003d579ac..d9c8a991577 100644 --- a/doc/administration/whats-new.md +++ b/doc/administration/whats-new.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: For assistance with this What's new page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this What's new page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # What's new **(FREE)** diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index 01c175e014e..f3442e23160 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Wiki settings **(FREE SELF)** |
