diff options
Diffstat (limited to 'doc/administration')
283 files changed, 3127 insertions, 2466 deletions
diff --git a/doc/administration/admin_area.md b/doc/administration/admin_area.md index a27fc04ff8f..ff18ac8ff3a 100644 --- a/doc/administration/admin_area.md +++ b/doc/administration/admin_area.md @@ -1,15 +1,15 @@ --- 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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Admin Area **(FREE SELF)** The Admin Area provides a web UI to manage and configure features of GitLab -self-managed instances. If you are an administrator,to access the Admin Area: +self-managed instances. If you are an administrator, to access the Admin Area: +- In GitLab 16.7 and later: on the left sidebar, at the bottom, select **Admin Area**. - In GitLab 16.1 and later: on the left sidebar, select **Search or go to**, then select **Admin Area**. - In GitLab 16.0 and earlier: on the top bar, select **Main menu > Admin**. @@ -22,8 +22,7 @@ You can administer all projects in the GitLab instance from the Admin Area's Pro To access the Projects page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Projects**. 1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that criteria. @@ -74,8 +73,7 @@ You can combine the filter options. For example, to list only public projects wi You can administer all users in the GitLab instance from the Admin Area's Users page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. To list users matching a specific criteria, select one of the following tabs on the **Users** page: @@ -119,8 +117,7 @@ This allows the administrator to "see what the user sees," and take actions on b You can impersonate a user in the following ways: - Through the UI: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. @@ -138,8 +135,7 @@ By default, impersonation is enabled. GitLab can be configured to [disable imper When using authentication providers, administrators can see the identities for a user: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Identities**. @@ -185,8 +181,7 @@ GitLab billing is based on the number of [**Billable users**](../subscriptions/s You must be an administrator to manually add emails to users: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Locate the user and select them. 1. Select **Edit**. @@ -202,8 +197,7 @@ The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and By default, users can create top level groups. To prevent a user from creating a top level group: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Locate the user and select them. 1. Select **Edit**. @@ -218,8 +212,7 @@ You can administer all groups in the GitLab instance from the Admin Area's Group To access the Groups page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, @@ -238,22 +231,20 @@ To [Create a new group](../user/group/index.md#create-a-group) select **New grou - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. - > Merging topics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366884) in GitLab 15.5. -[Topics](../user/project/working_with_projects.md#explore-topics) are used to categorize and find similar projects. +[Topics](../user/project/settings/project_features_permissions.md#project-topics) are used to categorize and find similar projects. ### View all topics To view all topics in the GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. For each topic, the page displays its name and the number of projects labeled with the topic. ### Search for topics -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. In the search box, enter your search criteria. The topic search is case-insensitive and applies partial matching. @@ -262,8 +253,7 @@ For each topic, the page displays its name and the number of projects labeled wi To create a topic: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. Select **New topic**. 1. Enter the **Topic slug (name)** and **Topic title**. @@ -282,8 +272,7 @@ Do not include sensitive information in the name of a topic. You can edit a topic's name, title, description, and avatar at any time. To edit a topic: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. Select **Edit** in that topic's row. 1. Edit the topic slug (name), title, description, or avatar. @@ -294,8 +283,7 @@ To edit a topic: If you no longer need a topic, you can permanently remove it. To remove a topic: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. To remove a topic, select **Remove** in that topic's row. @@ -307,8 +295,7 @@ After a merged topic is deleted, you cannot restore it. To merge topics: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. Select **Merge topics**. 1. From the **Source topic** dropdown list, select the topic you want to merge and remove. @@ -322,8 +309,7 @@ page. For more details, see [Gitaly](gitaly/index.md). To access the **Gitaly Servers** page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: @@ -347,8 +333,7 @@ You can administer all runners in the GitLab instance from the Admin Area's **Ru To access the **Runners** page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Runners**. #### Search and filter runners @@ -374,8 +359,7 @@ You can also filter runners by status, type, and tag. To filter: You can delete multiple runners at the same time. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Runners**. 1. To the left of the runners you want to delete, select the checkbox. To select all of the runners on the page, select the checkbox above @@ -405,8 +389,7 @@ You can administer all jobs in the GitLab instance from the Admin Area's Jobs pa To access the Jobs page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Jobs**. All jobs are listed, in descending order of job ID. 1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. diff --git a/doc/administration/analytics/dev_ops_reports.md b/doc/administration/analytics/dev_ops_reports.md index a5a3120489d..057dc5d48ee 100644 --- a/doc/administration/analytics/dev_ops_reports.md +++ b/doc/administration/analytics/dev_ops_reports.md @@ -1,19 +1,18 @@ --- stage: Plan group: Optimize -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DevOps Reports **(FREE SELF)** DevOps Reports give you an overview of your entire instance's adoption of -[Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) +[DevOps](https://about.gitlab.com/topics/devops/) from planning to monitoring. To see DevOps Reports: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Analytics > DevOps Reports**. ## DevOps Score diff --git a/doc/administration/analytics/index.md b/doc/administration/analytics/index.md index 5ba14222165..c5431efaf9b 100644 --- a/doc/administration/analytics/index.md +++ b/doc/administration/analytics/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level analytics **(FREE SELF)** @@ -12,14 +12,13 @@ Instance-level analytics provide insights into the feature and data usage of you ## View instance-level analytics -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To view instance-level analytics: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Analytics**, then one of the available analytics: - [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. diff --git a/doc/administration/analytics/usage_trends.md b/doc/administration/analytics/usage_trends.md index 20b732d028d..52ea20a2954 100644 --- a/doc/administration/analytics/usage_trends.md +++ b/doc/administration/analytics/usage_trends.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage Trends **(FREE SELF)** @@ -19,8 +19,7 @@ Usage Trends data refreshes daily. To view Usage Trends: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Analytics > Usage Trends**. ## Total counts diff --git a/doc/administration/appearance.md b/doc/administration/appearance.md index ceb4a4a30e9..3599c444134 100644 --- a/doc/administration/appearance.md +++ b/doc/administration/appearance.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Appearance **(FREE SELF)** @@ -9,8 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Several options are available for customizing the appearance of a self-managed instance of GitLab. To access these settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Appearance**. ## Navigation bar @@ -83,8 +82,7 @@ description, and icon. To configure the PWA settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Appearance**. 1. Scroll to the **Progressive Web App (PWA)** section. 1. Complete the fields. diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md index c14562c0e18..91392b2f0d9 100644 --- a/doc/administration/application_settings_cache.md +++ b/doc/administration/application_settings_cache.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application cache interval **(FREE SELF)** diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md deleted file mode 100644 index d6a6725210d..00000000000 --- a/doc/administration/audit_event_streaming.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'audit_event_streaming/index.md' -remove_date: '2023-09-12' ---- - -This document was moved to [another location](audit_event_streaming/index.md). - -<!-- This redirect file can be deleted after <2023-09-12>. --> -<!-- 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/audit_event_streaming/audit_event_types.md b/doc/administration/audit_event_streaming/audit_event_types.md index 88212045d8e..28cab04553a 100644 --- a/doc/administration/audit_event_streaming/audit_event_types.md +++ b/doc/administration/audit_event_streaming/audit_event_types.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- <!--- @@ -47,6 +47,7 @@ Audit event types belong to the following product categories. | [`create_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | | [`create_http_namespace_filter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136047) | Event triggered when a namespace filter for an external audit event destination for a top-level group is created.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.6](https://gitlab.com/gitlab-org/gitlab/-/issues/424176) | | [`create_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123882) | Event triggered when an instance level external audit event destination is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +| [`delete_http_namespace_filter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136302) | Event triggered when a namespace filter for an external audit event destination for a top-level group is deleted.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/424177) | | [`destroy_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | | [`destroy_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125846) | Event triggered when an instance level external audit event destination is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | | [`event_type_filters_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113081) | Event triggered when a new audit events streaming event type filter is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/344848) | @@ -54,12 +55,21 @@ Audit event types belong to the following product categories. | [`google_cloud_logging_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | | [`google_cloud_logging_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | | [`google_cloud_logging_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | +| [`instance_amazon_s3_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137651) | Triggered when instance Amazon S3 configuration for audit events streaming is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/423235) | +| [`instance_amazon_s3_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138318) | Triggered when instance-level Amazon S3 configuration for audit events streaming is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/423235) | +| [`instance_amazon_s3_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138310) | Triggered when instance-level Amazon S3 configuration for audit events streaming is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/423235) | | [`instance_google_cloud_logging_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130663) | Triggered when Instance level Google Cloud Logging configuration is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.4](https://gitlab.com/gitlab-org/gitlab/-/issues/423038) | | [`instance_google_cloud_logging_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131752) | Triggered when instance level Google Cloud Logging configuration is deleted.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/423040) | | [`instance_google_cloud_logging_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131790) | Triggered when instance level Google Cloud Logging configuration is updated.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/423039) | | [`update_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | | [`update_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125846) | Event triggered when an instance level external audit event destination is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +### Authorization + +| Name | Description | Saved to database | Streamed | Introduced in | +|:-----|:------------|:------------------|:---------|:--------------| +| [`member_role_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137087) | Event triggered when a custom role is created.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/388934) | + ### Code review | Name | Description | Saved to database | Streamed | Introduced in | @@ -170,6 +180,9 @@ Audit event types belong to the following product categories. | [`ci_group_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a CI variable is created at a group level| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_group_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a group's CI variable is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_group_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a group's CI variable is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_instance_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131882) | When an instance level CI variable is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/8070) | +| [`ci_instance_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131882) | When an instance level CI varialbe is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/8070) | +| [`ci_instance_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131882) | When an instance level CI variable is changed| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/8070) | | [`ci_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a CI variable is created at a project level| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a project's CI variable is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a project's CI variable is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | @@ -305,6 +318,7 @@ Audit event types belong to the following product categories. | Name | Description | Saved to database | Streamed | Introduced in | |:-----|:------------|:------------------|:---------|:--------------| | [`project_feature_model_experiments_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121027) | Model experiments access level was updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/412384) | +| [`project_feature_model_registry_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138399) | Model registry access level was updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) | ### Not categorized @@ -402,7 +416,7 @@ Audit event types belong to the following product categories. | [`user_access_locked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124169) | Event triggered when user access to the instance is locked| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/244) | | [`user_access_unlocked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124973) | Event triggered when user access to the instance is unlocked| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/244) | | [`user_disable_two_factor`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89598) | Audit event triggered when user disables two factor authentication| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/238177) | -| [`user_enable_admin_mode`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104754) | Event triggered on enabling admin mode| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/362101) | +| [`user_enable_admin_mode`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104754) | Event triggered on enabling Admin Mode| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/362101) | ### Team planning diff --git a/doc/administration/audit_event_streaming/examples.md b/doc/administration/audit_event_streaming/examples.md index b0d6190211c..ed7c0d5d97d 100644 --- a/doc/administration/audit_event_streaming/examples.md +++ b/doc/administration/audit_event_streaming/examples.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming examples @@ -40,7 +40,7 @@ X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN> X-Gitlab-Audit-Event-Type: repository_git_operation ``` -### Example payloads for SSH events +### Example payloads for Git over SSH events Fetch: @@ -106,7 +106,7 @@ Push: } ``` -### Example payloads for SSH events with Deploy Key +### Example payloads for Git over SSH events with Deploy Key > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363876) in GitLab 15.3. @@ -142,7 +142,7 @@ Fetch: } ``` -### Example payloads for HTTP and HTTPS events +### Example payloads for Git over HTTP and HTTPS events Fetch: @@ -208,7 +208,7 @@ Push: } ``` -### Example payloads for HTTP and HTTPS events with Deploy Token +### Example payloads for Git over HTTP and HTTPS events with Deploy Token Fetch: diff --git a/doc/administration/audit_event_streaming/graphql_api.md b/doc/administration/audit_event_streaming/graphql_api.md index 58668902b8e..06cae34b7ef 100644 --- a/doc/administration/audit_event_streaming/graphql_api.md +++ b/doc/administration/audit_event_streaming/graphql_api.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming GraphQL API **(ULTIMATE ALL)** @@ -378,7 +378,7 @@ Event streaming is enabled if: List all Google Cloud Logging configuration destinations for a top-level group. -Prerequisite: +Prerequisites: - Owner role for a top-level group. @@ -410,7 +410,7 @@ You need the ID values returned by this query for the update and delete mutation Update a Google Cloud Logging configuration destinations for a top-level group. -Prerequisite: +Prerequisites: - Owner role for a top-level group. @@ -446,7 +446,7 @@ Delete streaming destinations for a top-level group. When the last destination is successfully deleted, streaming is disabled for the group. -Prerequisite: +Prerequisites: - Owner role for a top-level group. @@ -786,7 +786,7 @@ Event streaming is enabled if: List all Google Cloud Logging configuration destinations for an instance. -Prerequisite: +Prerequisites: - You have administrator access to the instance. @@ -815,7 +815,7 @@ You need the ID values returned by this query for the update and delete mutation Update the Google Cloud Logging configuration destinations for an instance. -Prerequisite: +Prerequisites: - You have administrator access to the instance. @@ -851,7 +851,7 @@ Delete streaming destinations for an instance. When the last destination is successfully deleted, streaming is disabled for the instance. -Prerequisite: +Prerequisites: - You have administrator access to the instance. diff --git a/doc/administration/audit_event_streaming/index.md b/doc/administration/audit_event_streaming/index.md index 09474db1e08..71ae33b3d87 100644 --- a/doc/administration/audit_event_streaming/index.md +++ b/doc/administration/audit_event_streaming/index.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming **(ULTIMATE ALL)** @@ -49,7 +49,7 @@ To add streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. 1. In the **Name** and **Destination URL** fields, add a destination name and URL. 1. Optional. Locate the **Custom HTTP headers** table. @@ -68,7 +68,7 @@ To list the streaming destinations for a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand it and see all the custom HTTP headers. #### Update an HTTP destination @@ -81,7 +81,7 @@ To update a streaming destination's name: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. In the **Name** fields, add a destination name to update. 1. Select **Save** to update the streaming destination. @@ -90,7 +90,7 @@ To update a streaming destination's custom HTTP headers: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Custom HTTP headers** table. 1. Locate the header that you wish to update. @@ -146,7 +146,7 @@ To list streaming destinations and see the verification tokens: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select the **Streams**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Verification token** input. @@ -169,6 +169,25 @@ To update a streaming destination's event filters: 1. Select the dropdown list and select or clear the required event types. 1. Select **Save** to update the event filters. +#### Update namespace filters + +> Namespace filtering in the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390133) in GitLab 16.7. + +When this feature is enabled for a group, you can permit users to filter streamed audit events per destination. +If the feature is enabled with no filters, the destination receives all audit events. + +A streaming destination that has a namespace filter set has a **filtered** (**{filter}**) label. + +To update a streaming destination's namespace filters: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Secure > Audit events**. +1. On the main area, select the **Streams** tab. +1. Select the stream to expand. +1. Locate the **Filter by groups or projects** dropdown list. +1. Select the dropdown list and select or clear the required namespaces. +1. Select **Save** to update the namespace filter. + #### Override default content type header By default, streaming destinations use a `content-type` header of `application/x-www-form-urlencoded`. However, you @@ -204,7 +223,7 @@ To add Google Cloud Logging streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **Google Cloud Logging** to show the section for adding destinations. 1. Enter a random string to use as a name for the new destination. 1. Enter the Google project ID, Google client email, and Google private key from previously-created Google Cloud service account key to add to the new destination. @@ -221,7 +240,7 @@ To list Google Cloud Logging streaming destinations for a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand and see all the fields. #### Update a Google Cloud Logging destination @@ -236,7 +255,7 @@ To update Google Cloud Logging streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand. 1. Enter a random string to use as a name for the destination. 1. Enter the Google project ID and Google client email from previously-created Google Cloud service account key to update the destination. @@ -261,11 +280,8 @@ To delete Google Cloud Logging streaming destinations to a top-level group: ### AWS S3 destinations -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132603) in GitLab 16.6 [with a flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per group, an administrator can [disable the feature flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132603) in GitLab 16.6 [with a flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. Enabled by default. +> - [Feature flag `allow_streaming_audit_events_to_amazon_s3`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137391) removed in GitLab 16.7. Manage AWS S3 destinations for top-level groups. @@ -287,7 +303,7 @@ To add AWS S3 streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **AWS S3** to show the section for adding destinations. 1. Enter a random string to use as a name for the new destination. 1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to add to the new destination. @@ -303,7 +319,7 @@ To list AWS S3 streaming destinations for a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the AWS S3 stream to expand and see all the fields. #### Update a AWS S3 destination @@ -316,7 +332,7 @@ To update AWS S3 streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the AWS S3 stream to expand. 1. Enter a random string to use as a name for the destination. 1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to update the destination. @@ -360,10 +376,9 @@ Prerequisites: To add a streaming destination for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. 1. In the **Name** and **Destination URL** fields, add a destination name and URL. 1. Optional. To add custom HTTP headers, select **Add header** to create a new name and value pair, and input their values. Repeat this step for as many name and value pairs are required. You can add up to 20 headers per streaming destination. @@ -380,10 +395,9 @@ Prerequisites: To list the streaming destinations for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand it and see all the custom HTTP headers. #### Update an HTTP destination @@ -394,20 +408,18 @@ Prerequisites: To update a instance streaming destination's name: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. In the **Name** fields, add a destination name to update. 1. Select **Save** to update the streaming destination. To update a instance streaming destination's custom HTTP headers: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Custom HTTP headers** table. 1. Locate the header that you wish to update. @@ -427,9 +439,8 @@ Prerequisites: To delete the streaming destinations for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Select **Delete destination**. @@ -437,9 +448,8 @@ To delete the streaming destinations for an instance: To delete only the custom HTTP headers for a streaming destination: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. To the right of the item, **Edit** (**{pencil}**). 1. Locate the **Custom HTTP headers** table. @@ -465,9 +475,8 @@ Prerequisites: To list streaming destinations for an instance and see the verification tokens: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. View the verification token on the right side of each item. @@ -482,9 +491,8 @@ A streaming destination that has an event type filter set has a **filtered** (** To update a streaming destination's event filters: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Filter by audit event type** dropdown list. @@ -524,10 +532,9 @@ Prerequisites: To add Google Cloud Logging streaming destinations to an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **Google Cloud Logging** to show the section for adding destinations. 1. Enter a random string to use as a name for the new destination. 1. Enter the Google project ID, Google client email, and Google private key from previously-created Google Cloud service account key to add to the new destination. @@ -542,10 +549,9 @@ Prerequisites: To list Google Cloud Logging streaming destinations for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand and see all the fields. #### Update a Google Cloud Logging destination @@ -556,10 +562,9 @@ Prerequisites: To update Google Cloud Logging streaming destinations to an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand. 1. Enter a random string to use as a name for the destination. 1. Enter the Google project ID and Google client email from previously-created Google Cloud service account key to update the destination. @@ -575,14 +580,92 @@ Prerequisites: To delete Google Cloud Logging streaming destinations to an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand. 1. Select **Delete destination**. 1. Confirm by selecting **Delete destination** in the dialog. +### AWS S3 destinations + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138245) in GitLab 16.7 [with a flag](../feature_flags.md) named `allow_streaming_instance_audit_events_to_amazon_s3`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To enable the feature, an administrator can [enable the feature flag](../feature_flags.md) named +`allow_streaming_instance_audit_events_to_amazon_s3`. On GitLab.com, this feature is not available. + +Manage AWS S3 destinations for entire instance. + +#### Prerequisites + +Before setting up AWS S3 streaming audit events, you must: + +1. Create a access key for AWS with the appropriate credentials and permissions. This account is used to configure audit log streaming authentication. + For more information, see [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html?icmpid=docs_iam_console#Using_CreateAccessKey). +1. Create a AWS S3 bucket. This bucket is used to store audit log streaming data. For more information, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) + +#### Add a new AWS S3 destination + +Prerequisites: + +- Administrator access on the instance. + +To add AWS S3 streaming destinations to an instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select **Add streaming destination** and select **AWS S3** to show the section for adding destinations. +1. Enter a random string to use as a name for the new destination. +1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to add to the new destination. +1. Select **Add** to add the new streaming destination. + +#### List AWS S3 destinations + +Prerequisites: + +- Administrator access on the instance. + +To list AWS S3 streaming destinations for an instance. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the AWS S3 stream to expand and see all the fields. + +#### Update an AWS S3 destination + +Prerequisites: + +- Administrator access on the instance. + +To update AWS S3 streaming destinations to an instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the AWS S3 stream to expand. +1. Enter a random string to use as a name for the destination. +1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to update the destination. +1. Select **Add a new Secret Access Key** and enter a AWS Secret Access Key to update the Secret Access Key. +1. Select **Save** to update the streaming destination. + +#### Delete an AWS S3 streaming destination + +Prerequisites: + +- Administrator access on the instance. + +To delete AWS S3 streaming destinations on an instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the AWS S3 stream to expand. +1. Select **Delete destination**. +1. Confirm by selecting **Delete destination** in the dialog. + ## Payload schema > Documentation for an audit event streaming schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358149) in GitLab 15.3. diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index ba1a4ca05c4..d40e2c86dc9 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit events **(PREMIUM ALL)** @@ -37,7 +37,7 @@ Audit events can be viewed at the group, project, instance, and sign-in level. E To view a group's audit events: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Audit events**. +1. Select **Secure > Audit events**. 1. Filter the audit events by the member of the project (user) who performed the action and date range. Group audit events can also be accessed using the [Group Audit Events API](../api/audit_events.md#group-audit-events). Group audit event queries are limited to a maximum of 30 days. @@ -45,7 +45,7 @@ Group audit events can also be accessed using the [Group Audit Events API](../ap ### Project audit events 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Secure > Audit events**. +1. Select **Secure > Audit events**. 1. Filter the audit events by the member of the project (user) who performed the action and date range. Project audit events can also be accessed using the [Project Audit Events API](../api/audit_events.md#project-audit-events). Project audit event queries are limited to a maximum of 30 days. @@ -55,9 +55,8 @@ Project audit events can also be accessed using the [Project Audit Events API](. You can view audit events from user actions across an entire GitLab instance. To view instance audit events: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. Filter by the following: - Member of the project (user) who performed the action - Group @@ -82,9 +81,8 @@ After upgrading to a paid tier, you can also see successful sign-in events on au You can export the current view (including filters) of your instance audit events as a CSV(comma-separated values) file. To export the instance audit events to CSV: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. Select the available search filters. 1. Select **Export as CSV**. diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index 84425dd7b89..bfd061eb760 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments 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 09d68e82782..45475ab7b16 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auditor users **(PREMIUM SELF)** @@ -34,9 +34,8 @@ To create a new user account with auditor access (or change an existing user): To create a user account with auditor access: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Create a new user or edit an existing one. Set **Access Level** to **Auditor**. 1. If you created a user, select **Create user**. For an existing user, select **Save changes**. diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index cbb9663cfa6..36331799fec 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Atlassian as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index 2e2d9ec3d28..096243419c1 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -1,8 +1,7 @@ --- -type: concepts, howto stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use AWS Cognito as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 574b8967b02..ae9a46650f6 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -1,11 +1,10 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Use Atlassian Crowd as an OAuth 2.0 authentication provider (deprecated) **(FREE SELF)** +# Use Atlassian Crowd as an authentication provider (deprecated) **(FREE SELF)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369117) in GitLab 15.3 and is planned for diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 037a2943b2e..95268f6f39b 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -1,8 +1,7 @@ --- -type: index stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab authentication and authorization **(FREE SELF)** diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 67f72b3344e..f4e7ea09615 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use JWT as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 5b9bddc34c5..8338760ecb5 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Secure LDAP **(FREE SELF)** diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 0c42ce90346..62395ebdcd2 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate LDAP with GitLab **(FREE SELF)** diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 0a96e904f24..9cd306d979f 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting LDAP **(FREE SELF)** @@ -167,9 +166,8 @@ may see the following message: `Access denied for your LDAP account`. We have a workaround, based on toggling the access level of affected users: -1. As an administrator, on the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Select the name of the affected user. 1. In the upper-right corner, select **Edit**. 1. Change the user's access level from `Regular` to `Administrator` (or vice versa). @@ -225,9 +223,8 @@ field contains no data: To resolve this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, go to **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand both of the following: - **Account and limit**. - **Sign-up restrictions**. @@ -369,8 +366,7 @@ things to debug the situation. - Ensure the correct [LDAP group link is added to the GitLab group](ldap_synchronization.md#add-group-links). - Check that the user has an LDAP identity: 1. Sign in to GitLab as an administrator user. - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. Search for the user. 1. Open the user by selecting their name. Do not select **Edit**. @@ -661,6 +657,25 @@ end You can then [run a UserSync](#sync-all-users) **(PREMIUM SELF)** to sync the latest DN for each of these users. +## Could not authenticate from AzureActivedirectoryV2 because "Invalid grant" + +When converting from LDAP to SAML you might get an error in Azure that states the following: + +```plaintext +Authentication failure! invalid_credentials: OAuth2::Error, invalid_grant. +``` + +This issue occurs when both of the following are true: + +- LDAP identities still exist for users after SAML has been configured for those users. +- You disable LDAP for those users. + +You would receive both LDAP and Azure metadata in the logs, which generates the error in Azure. + +The workaround for a single user is to remove the LDAP identity from the user in **Admin > Identities**. + +To remove multiple LDAP identities, use either of the workarounds for the [`Could not authenticate you from Ldapmain because "Unknown provider"` error](#could-not-authenticate-you-from-ldapmain-because-unknown-provider). + ## `Could not authenticate you from Ldapmain because "Unknown provider"` You can receive the following error when authenticating with an LDAP server: diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 0a1c0bd9689..75c257c1009 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP synchronization **(PREMIUM SELF)** @@ -501,10 +501,9 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure LDAP](index.md#configure-ldap). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility and access controls** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Visibility and access controls**. 1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected. ### Change LDAP group synchronization settings management @@ -514,9 +513,8 @@ By default, group members with the Owner role can manage [LDAP group synchroniza GitLab administrators can remove this permission from group Owners: 1. [Configure LDAP](index.md#configure-ldap). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Ensure the **Allow group owners to manage LDAP-related settings** checkbox is not checked. diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index d3ecd2771e6..d20c9ee4412 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -1,18 +1,17 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use OpenID Connect as an OAuth 2.0 authentication provider **(FREE SELF)** -GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) +You can use GitLab as a client application with [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. -The OpenID Connect provides you with a client's details and secret for you to use. +The OpenID Connect provider provides you with a client's details and secret for you to use. 1. On your GitLab server, open the configuration file. diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index f4c64efb7b4..1d4ca87bcc0 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Smartcard authentication **(PREMIUM SELF)** diff --git a/doc/administration/auth/test_oidc_oauth.md b/doc/administration/auth/test_oidc_oauth.md index 49fb27af482..1f30da50dfa 100644 --- a/doc/administration/auth/test_oidc_oauth.md +++ b/doc/administration/auth/test_oidc_oauth.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test OIDC/OAuth in GitLab **(FREE SELF)** diff --git a/doc/administration/backup_restore/backup_gitlab.md b/doc/administration/backup_restore/backup_gitlab.md index 5c0fcbbc4ef..f38358810e3 100644 --- a/doc/administration/backup_restore/backup_gitlab.md +++ b/doc/administration/backup_restore/backup_gitlab.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up GitLab **(FREE SELF)** @@ -29,7 +29,7 @@ For more information, see [alternative backup strategies](#alternative-backup-st - [PostgreSQL databases](#postgresql-databases) - [Git repositories](#git-repositories) - [Blobs](#blobs) -- [Container Registry](#container-registry) +- [Container registry](#container-registry) - [Configuration files](#storing-configuration-files) - [Other data](#other-data) @@ -90,9 +90,9 @@ The [backup command](#backup-command) doesn't back up blobs that aren't stored o - [Amazon S3 backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html) - [Google Cloud Storage Transfer Service](https://cloud.google.com/storage-transfer-service) and [Google Cloud Storage Object Versioning](https://cloud.google.com/storage/docs/object-versioning) -### Container Registry +### Container registry -[GitLab Container Registry](../packages/container_registry.md) storage can be configured in either: +[GitLab container registry](../packages/container_registry.md) storage can be configured in either: - The file system in a specific location. - An [Object Storage](../object_storage.md) solution. Object Storage solutions can be: @@ -172,7 +172,7 @@ including: - CI/CD job artifacts - LFS objects - Terraform states ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331806) in GitLab 14.7) -- Container Registry images +- Container registry images - GitLab Pages content - Packages ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332006) in GitLab 14.7) - Snippets @@ -283,22 +283,11 @@ Dumping database tables: - Dumping table wikis... [DONE] Dumping repositories: - Dumping repository abcd... [DONE] -Creating backup archive: $TIMESTAMP_gitlab_backup.tar [DONE] +Creating backup archive: <backup-id>_gitlab_backup.tar [DONE] Deleting tmp directories...[DONE] Deleting old backups... [SKIPPING] ``` -### Backup timestamp - -The backup archive is saved in `backup_path`, which is specified in the -`config/gitlab.yml` file. The default path is `/var/opt/gitlab/backups`. The filename is `[TIMESTAMP]_gitlab_backup.tar`, -where `TIMESTAMP` identifies the time at which each backup was created, plus -the GitLab version. The timestamp is needed if you need to restore GitLab and -multiple backups are available. - -For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, -the timestamp is `1493107454_2018_04_25_10.6.4-ce`. - ### Backup options The command-line tool GitLab provides to back up your instance can accept more @@ -327,15 +316,14 @@ To use the `copy` strategy instead of the default streaming strategy, specify sudo gitlab-backup create STRATEGY=copy ``` -#### Backup filename +#### Backup file name WARNING: -If you use a custom backup filename, you can't +If you use a custom backup file name, you can't [limit the lifetime of the backups](#limit-backup-lifetime-for-local-files-prune-old-backups). -By default, a backup file is created according to the specification in the -previous [Backup timestamp](#backup-timestamp) section. You can, however, -override the `[TIMESTAMP]` portion of the filename by setting the `BACKUP` +Backup files are created with file names according to [specific defaults](index.md#backup-id). However, you can +override the `<backup-id>` portion of the file name by setting the `BACKUP` environment variable. For example: ```shell @@ -346,11 +334,102 @@ The resulting file is named `dump_gitlab_backup.tar`. This is useful for systems that make use of rsync and incremental backups, and results in considerably faster transfer speeds. +#### Backup compression + +By default, Gzip fast compression is applied during backup of: + +- [PostgreSQL database](#postgresql-databases) dumps. +- [blobs](#blobs), for example uploads, job artifacts, external merge request diffs. + +The default command is `gzip -c -1`. You can override this command with `COMPRESS_CMD`. Similarly, you can override the decompression command with `DECOMPRESS_CMD`. + +Caveats: + +- The compression command is used in a pipeline, so your custom command must output to `stdout`. +- If you specify a command that is not packaged with GitLab, then you must install it yourself. +- The resultant file names will still end in `.gz`. +- The default decompression command, used during restore, is `gzip -cd`. Therefore if you override the compression command to use a format that cannot be decompressed by `gzip -cd`, you must override the decompression command during restore. +- [Do not place environment variables after the backup command](https://gitlab.com/gitlab-org/gitlab/-/issues/433227). For example, `gitlab-backup create COMPRESS_CMD="pigz -c --best"` doesn't work as intended. + +##### Default compression: Gzip with fastest method + +```shell +gitlab-backup create +``` + +##### Gzip with slowest method + +```shell +COMPRESS_CMD="gzip -c --best" gitlab-backup create +``` + +If `gzip` was used for backup, then restore does not require any options: + +```shell +gitlab-backup restore +``` + +##### No compression + +If your backup destination has built-in automatic compression, then you may wish to skip compression. + +The `tee` command pipes `stdin` to `stdout`. + +```shell +COMPRESS_CMD=tee gitlab-backup create +``` + +And on restore: + +```shell +DECOMPRESS_CMD=tee gitlab-backup restore +``` + +##### Parallel compression with `pigz` + +WARNING: +While we support using `COMPRESS_CMD` and `DECOMPRESS_CMD` to override the default Gzip compression library, we currently only test the default Gzip library with default options on a routine basis. You are responsible for testing and validating the viability of your backups. We strongly recommend this as best practice in general for backups, whether overriding the compression command or not. If you encounter issues with another compression library, you should revert back to the default. Troubleshooting and fixing errors with alternative libraries are a lower priority for GitLab. + +NOTE: +`pigz` is not included in the GitLab Linux package. You must install it yourself. + +An example of compressing backups with `pigz` using 4 processes: + +```shell +COMPRESS_CMD="pigz --compress --stdout --fast --processes=4" sudo gitlab-backup create +``` + +Because `pigz` compresses to the `gzip` format, it is not required to use `pigz` to decompress backups which were compressed by `pigz`. However, it can still have a performance benefit over `gzip`. An example of decompressing backups with `pigz`: + +```shell +DECOMPRESS_CMD="pigz --decompress --stdout" sudo gitlab-backup restore +``` + +##### Parallel compression with `zstd` + +WARNING: +While we support using `COMPRESS_CMD` and `DECOMPRESS_CMD` to override the default Gzip compression library, we currently only test the default Gzip library with default options on a routine basis. You are responsible for testing and validating the viability of your backups. We strongly recommend this as best practice in general for backups, whether overriding the compression command or not. If you encounter issues with another compression library, you should revert back to the default. Troubleshooting and fixing errors with alternative libraries are a lower priority for GitLab. + +NOTE: +`zstd` is not included in the GitLab Linux package. You must install it yourself. + +An example of compressing backups with `zstd` using 4 threads: + +```shell +COMPRESS_CMD="zstd --compress --stdout --fast --threads=4" sudo gitlab-backup create +``` + +An example of decompressing backups with `zstd`: + +```shell +DECOMPRESS_CMD="zstd --decompress --stdout" sudo gitlab-backup restore +``` + #### Confirm archive can be transferred To ensure the generated archive is transferable by rsync, you can set the `GZIP_RSYNCABLE=yes` option. This sets the `--rsyncable` option to `gzip`, which is useful only in -combination with setting [the Backup filename option](#backup-filename). +combination with setting [the Backup file name option](#backup-file-name). The `--rsyncable` option in `gzip` isn't guaranteed to be available on all distributions. To verify that it's available in your distribution, run @@ -370,7 +449,7 @@ You can exclude specific directories from the backup by adding the environment v - `artifacts` (CI job artifacts) - `lfs` (LFS objects) - `terraform_state` (Terraform states) -- `registry` (Container Registry images) +- `registry` (Container registry images) - `pages` (Pages content) - `repositories` (Git repositories data) - `packages` (Packages) @@ -523,23 +602,23 @@ Incremental repository backups can be faster than full repository backups becaus The incremental backup archives are not linked to each other: each archive is a self-contained backup of the instance. There must be an existing backup to create an incremental backup from: -- In GitLab 14.9 and 14.10, use the `BACKUP=<timestamp_of_backup>` option to choose the backup to use. The chosen previous backup is overwritten. -- In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<timestamp_of_backup>` option to choose the backup to use. By default, a backup file is created - as documented in the [Backup timestamp](#backup-timestamp) section. You can override the `[TIMESTAMP]` portion of the filename by setting the - [`BACKUP` environment variable](#backup-filename). +- In GitLab 14.9 and 14.10, use the `BACKUP=<backup-id>` option to choose the backup to use. The chosen previous backup is overwritten. +- In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<backup-id>` option to choose the backup to use. By default, a backup file is created + as documented in the [Backup ID](index.md#backup-id) section. You can override the `<backup-id>` portion of the file name by setting the + [`BACKUP` environment variable](#backup-file-name). To create an incremental backup, run: - In GitLab 15.0 or later: ```shell - sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<timestamp_of_backup> + sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<backup-id> ``` - In GitLab 14.9 and 14.10: ```shell - sudo gitlab-backup create INCREMENTAL=yes BACKUP=<timestamp_of_backup> + sudo gitlab-backup create INCREMENTAL=yes BACKUP=<backup-id> ``` To create an [untarred](#skipping-tar-creation) incremental backup from a tarred backup, use `SKIP=tar`: @@ -1118,7 +1197,7 @@ When troubleshooting backup problems, however, replace `CRON=1` with `--trace` t #### Limit backup lifetime for local files (prune old backups) WARNING: -The process described in this section doesn't work if you used a [custom filename](#backup-filename) +The process described in this section doesn't work if you used a [custom file name](#backup-file-name) for your backups. To prevent regular backups from using all your disk space, you may want to set a limited lifetime @@ -1621,9 +1700,9 @@ You should verify that the secrets are the root cause before deleting any data. TRUNCATE integrations, chat_names, issue_tracker_data, jira_tracker_data, slack_integrations, web_hooks, zentao_tracker_data, web_hook_logs CASCADE; ``` -### Container Registry push failures after restoring from a backup +### Container registry push failures after restoring from a backup -If you use the [Container Registry](../../user/packages/container_registry/index.md), +If you use the [container registry](../../user/packages/container_registry/index.md), pushes to the registry may fail after restoring your backup on a Linux package (Omnibus) instance after restoring the registry data. @@ -1680,16 +1759,16 @@ During backup, you can get the `File name too long` error ([issue #354984](https Problem: <class 'OSError: [Errno 36] File name too long: ``` -This problem stops the backup script from completing. To fix this problem, you must truncate the filenames causing the problem. A maximum of 246 characters, including the file extension, is permitted. +This problem stops the backup script from completing. To fix this problem, you must truncate the file names causing the problem. A maximum of 246 characters, including the file extension, is permitted. WARNING: The steps in this section can potentially lead to **data loss**. All steps must be followed strictly in the order given. Consider opening a [Support Request](https://support.gitlab.com/hc/en-us/requests/new) if you're a Premium or Ultimate customer. -Truncating filenames to resolve the error involves: +Truncating file names to resolve the error involves: - Cleaning up remote uploaded files that aren't tracked in the database. -- Truncating the filenames in the database. +- Truncating the file names in the database. - Rerunning the backup task. #### Clean up remote uploaded files @@ -1713,15 +1792,15 @@ To fix these files, you must clean up all remote uploaded files that are in the bundle exec rake gitlab:cleanup:remote_upload_files RAILS_ENV=production DRY_RUN=false ``` -#### Truncate the filenames referenced by the database +#### Truncate the file names referenced by the database -You must truncate the files referenced by the database that are causing the problem. The filenames referenced by the database are stored: +You must truncate the files referenced by the database that are causing the problem. The file names referenced by the database are stored: - In the `uploads` table. - In the references found. Any reference found from other database tables and columns. - On the file system. -Truncate the filenames in the `uploads` table: +Truncate the file names in the `uploads` table: 1. Enter the database console: @@ -1749,9 +1828,9 @@ Truncate the filenames in the `uploads` table: sudo -u git -H bundle exec rails dbconsole -e production ``` -1. Search the `uploads` table for filenames longer than 246 characters: +1. Search the `uploads` table for file names longer than 246 characters: - The following query selects the `uploads` records with filenames longer than 246 characters in batches of 0 to 10000. This improves the performance on large GitLab instances with tables having thousand of records. + The following query selects the `uploads` records with file names longer than 246 characters in batches of 0 to 10000. This improves the performance on large GitLab instances with tables having thousand of records. ```sql CREATE TEMP TABLE uploads_with_long_filenames AS @@ -1764,9 +1843,9 @@ Truncate the filenames in the `uploads` table: SELECT u.id, u.path, - -- Current filename + -- Current file name (regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] AS current_filename, - -- New filename + -- New file name CONCAT( LEFT(SPLIT_PART((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1], '.', 1), 242), COALESCE(SUBSTRING((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] FROM '\.(?:.(?!\.))+$')) @@ -1796,13 +1875,13 @@ Truncate the filenames in the `uploads` table: Where: - - `current_filename`: a filename that is currently more than 246 characters long. - - `new_filename`: a filename that has been truncated to 246 characters maximum. + - `current_filename`: a file name that is currently more than 246 characters long. + - `new_filename`: a file name that has been truncated to 246 characters maximum. - `new_path`: new path considering the `new_filename` (truncated). After you validate the batch results, you must change the batch size (`row_id`) using the following sequence of numbers (10000 to 20000). Repeat this process until you reach the last record in the `uploads` table. -1. Rename the files found in the `uploads` table from long filenames to new truncated filenames. The following query rolls back the update so you can check the results safely in a transaction wrapper: +1. Rename the files found in the `uploads` table from long file names to new truncated file names. The following query rolls back the update so you can check the results safely in a transaction wrapper: ```sql CREATE TEMP TABLE uploads_with_long_filenames AS @@ -1837,7 +1916,7 @@ Truncate the filenames in the `uploads` table: After you validate the batch update results, you must change the batch size (`row_id`) using the following sequence of numbers (10000 to 20000). Repeat this process until you reach the last record in the `uploads` table. -1. Validate that the new filenames from the previous query are the expected ones. If you are sure you want to truncate the records found in the previous step to 246 characters, run the following: +1. Validate that the new file names from the previous query are the expected ones. If you are sure you want to truncate the records found in the previous step to 246 characters, run the following: WARNING: The following action is **irreversible**. @@ -1869,9 +1948,9 @@ Truncate the filenames in the `uploads` table: After you finish the batch update, you must change the batch size (`updatable_uploads.row_id`) using the following sequence of numbers (10000 to 20000). Repeat this process until you reach the last record in the `uploads` table. -Truncate the filenames in the references found: +Truncate the file names in the references found: -1. Check if those records are referenced somewhere. One way to do this is to dump the database and search for the parent directory name and filename: +1. Check if those records are referenced somewhere. One way to do this is to dump the database and search for the parent directory name and file name: 1. To dump your database, you can use the following command as an example: @@ -1879,15 +1958,15 @@ Truncate the filenames in the references found: pg_dump -h /var/opt/gitlab/postgresql/ -d gitlabhq_production > gitlab-dump.tmp ``` - 1. Then you can search for the references using the `grep` command. Combining the parent directory and the filename can be a good idea. For example: + 1. Then you can search for the references using the `grep` command. Combining the parent directory and the file name can be a good idea. For example: ```shell grep public/alongfilenamehere.txt gitlab-dump.tmp ``` -1. Replace those long filenames using the new filenames obtained from querying the `uploads` table. +1. Replace those long file names using the new file names obtained from querying the `uploads` table. -Truncate the filenames on the file system. You must manually rename the files in your file system to the new filenames obtained from querying the `uploads` table. +Truncate the file names on the file system. You must manually rename the files in your file system to the new file names obtained from querying the `uploads` table. #### Re-run the backup task diff --git a/doc/administration/backup_restore/backup_large_reference_architectures.md b/doc/administration/backup_restore/backup_large_reference_architectures.md index 4e11a707052..64d7b2168f5 100644 --- a/doc/administration/backup_restore/backup_large_reference_architectures.md +++ b/doc/administration/backup_restore/backup_large_reference_architectures.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up and restore large reference architectures **(FREE SELF)** @@ -17,7 +17,7 @@ This document is intended for environments using: - [Linux package (Omnibus) and cloud-native hybrid reference architectures 3,000 users and up](../reference_architectures/index.md) - [Amazon RDS](https://aws.amazon.com/rds/) for PostgreSQL data - [Amazon S3](https://aws.amazon.com/s3/) for object storage -- [Object storage](../object_storage.md) to store everything possible, including [blobs](backup_gitlab.md#blobs) and [Container Registry](backup_gitlab.md#container-registry) +- [Object storage](../object_storage.md) to store everything possible, including [blobs](backup_gitlab.md#blobs) and [container registry](backup_gitlab.md#container-registry) ## Configure daily backups @@ -48,7 +48,38 @@ There is a feature proposal to add the ability to back up repositories directly 1. Spin up a VM with 8 vCPU and 7.2 GB memory. This node will be used to back up Git repositories. Note that [a Praefect node cannot be used to back up Git data](https://gitlab.com/gitlab-org/gitlab/-/issues/396343#note_1385950340). - 1. Configure the node as another **GitLab Rails** node as defined in your [reference architecture](../reference_architectures/index.md). As with other GitLab Rails nodes, this node must have access to your main Postgres database as well as to Gitaly Cluster. + 1. Configure the node as another **GitLab Rails** node as defined in your [reference architecture](../reference_architectures/index.md). + As with other GitLab Rails nodes, this node must have access to your main PostgreSQL database, Redis, object storage, and Gitaly Cluster. + 1. Ensure the GitLab application isn't running on this node by disabling most services: + + 1. Edit `/etc/gitlab/gitlab.rb` to ensure the following services are disabled. + `roles(['application_role'])` disables Redis, PostgreSQL, and Consul, and + is the basis of the reference architecture Rails node definition. + + ```ruby + roles(['application_role']) + gitlab_workhorse['enable'] = false + puma['enable'] = false + sidekiq['enable'] = false + gitlab_kas['enable'] = false + gitaly['enable'] = false + prometheus_monitoring['enable'] = false + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + 1. The only service that should be left is `logrotate`, you can verify with: + + ```shell + gitlab-ctl status + ``` + + There is [a feature request](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6823) for a role in the Linux package + that meets these requirements. To back up the Git repositories: @@ -65,12 +96,12 @@ To back up the Git repositories: sudo gitlab-backup create SKIP=db ``` - The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the filename will end in `_gitlab_backup.tar`](backup_gitlab.md#backup-timestamp). + The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the file name will end in `_gitlab_backup.tar`](index.md#backup-id). Since we configured uploading backups to remote cloud storage, the tar file will be uploaded to the remote region and deleted from disk. -1. Note the [timestamp](backup_gitlab.md#backup-timestamp) of the backup file for the next step. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the timestamp is `1493107454_2018_04_25_10.6.4-ce`. -1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the timestamp of the source backup file. Using the example timestamp from the previous step, the command is: +1. Note the [backup ID](index.md#backup-id) of the backup file for the next step. For example, if the backup archive name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the backup ID is `1493107454_2018_04_25_10.6.4-ce`. +1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the backup ID of the source backup file. Using the example ID from the previous step, the command is: ```shell sudo gitlab-backup create SKIP=db INCREMENTAL=yes PREVIOUS_BACKUP=1493107454_2018_04_25_10.6.4-ce @@ -246,7 +277,7 @@ To restore Git repositories: sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar ``` -1. Restore the backup, specifying the timestamp of the backup you wish to restore: +1. Restore the backup, specifying the ID of the backup you wish to restore: WARNING: The restore command requires diff --git a/doc/administration/backup_restore/index.md b/doc/administration/backup_restore/index.md index 8c78e26db2a..d6e67ad4229 100644 --- a/doc/administration/backup_restore/index.md +++ b/doc/administration/backup_restore/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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up and restore GitLab **(FREE SELF)** @@ -25,196 +25,8 @@ For detailed information on restoring GitLab, see [Restore GitLab](restore_gitla ## Migrate to a new server -<!-- some details borrowed from GitLab.com move from Azure to GCP detailed at https://gitlab.com/gitlab-com/migration/-/blob/master/.gitlab/issue_templates/failover.md --> - -You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server. -If you're running GitLab Geo, an alternative option is [Geo disaster recovery for planned failover](../geo/disaster_recovery/planned_failover.md). - -WARNING: -Avoid uncoordinated data processing by both the new and old servers, where multiple -servers could connect concurrently and process the same data. For example, when using -[incoming email](../incoming_email.md), if both GitLab instances are -processing email at the same time, then both instances miss some data. -This type of problem can occur with other services as well, such as a -[non-packaged database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server), -a non-packaged Redis instance, or non-packaged Sidekiq. - -Prerequisites: - -- Some time before your migration, consider notifying your users of upcoming - scheduled maintenance with a [broadcast message banner](../broadcast_messages.md). -- Ensure your backups are complete and current. Create a complete system-level backup, or - take a snapshot of all servers involved in the migration, in case destructive commands - (like `rm`) are run incorrectly. - -### Prepare the new server - -To prepare the new server: - -1. Copy the - [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) - from the old server to avoid man-in-the-middle attack warnings. - See [Manually replicate the primary site's SSH host keys](../geo/replication/configuration.md#step-2-manually-replicate-the-primary-sites-ssh-host-keys) for example steps. -1. [Install and configure GitLab](https://about.gitlab.com/install/) except - [incoming email](../incoming_email.md): - 1. Install GitLab. - 1. Configure by copying `/etc/gitlab` files from the old server to the new server, and update as necessary. - Read the - [Linux package installation backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. - 1. If applicable, disable [incoming email](../incoming_email.md). - 1. Block new CI/CD jobs from starting upon initial startup after the backup and restore. - Edit `/etc/gitlab/gitlab.rb` and set the following: - - ```ruby - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" - ``` - - 1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Stop GitLab to avoid any potential unnecessary and unintentional data processing: - - ```shell - sudo gitlab-ctl stop - ``` - -1. Configure the new server to allow receiving the Redis database and GitLab backup files: - - ```shell - sudo rm -f /var/opt/gitlab/redis/dump.rdb - sudo chown <your-linux-username> /var/opt/gitlab/redis /var/opt/gitlab/backups - ``` - -### Prepare and transfer content from the old server - -1. Ensure you have an up-to-date system-level backup or snapshot of the old server. -1. Enable [maintenance mode](../maintenance_mode/index.md), - if supported by your GitLab edition. -1. Block new CI/CD jobs from starting: - 1. Edit `/etc/gitlab/gitlab.rb`, and set the following: - - ```ruby - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" - ``` - - 1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Disable periodic background jobs: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Monitoring > Background Jobs**. - 1. Under the Sidekiq dashboard, select **Cron** tab and then - **Disable All**. -1. Wait for the currently running CI/CD jobs to finish, or accept that jobs that have not completed may be lost. - To view jobs currently running, on the left sidebar, select **Overviews > Jobs**, - and then select **Running**. -1. Wait for Sidekiq jobs to finish: - 1. On the left sidebar, select **Monitoring > Background Jobs**. - 1. Under the Sidekiq dashboard, select **Queues** and then **Live Poll**. - Wait for **Busy** and **Enqueued** to drop to 0. - These queues contain work that has been submitted by your users; - shutting down before these jobs complete may cause the work to be lost. - Make note of the numbers shown in the Sidekiq dashboard for post-migration verification. -1. Flush the Redis database to disk, and stop GitLab other than the services needed for migration: - - ```shell - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && sudo gitlab-ctl stop && sudo gitlab-ctl start postgresql && sudo gitlab-ctl start gitaly - ``` - -1. Create a GitLab backup: - - ```shell - sudo gitlab-backup create - ``` - -1. Disable the following GitLab services and prevent unintentional restarts by adding the following to the bottom of `/etc/gitlab/gitlab.rb`: - - ```ruby - alertmanager['enable'] = false - gitlab_exporter['enable'] = false - gitlab_pages['enable'] = false - gitlab_workhorse['enable'] = false - grafana['enable'] = false - logrotate['enable'] = false - gitlab_rails['incoming_email_enabled'] = false - nginx['enable'] = false - node_exporter['enable'] = false - postgres_exporter['enable'] = false - postgresql['enable'] = false - prometheus['enable'] = false - puma['enable'] = false - redis['enable'] = false - redis_exporter['enable'] = false - registry['enable'] = false - sidekiq['enable'] = false - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Verify everything is stopped, and confirm no services are running: - - ```shell - sudo gitlab-ctl status - ``` - -1. Transfer the Redis database and GitLab backups to the new server: - - ```shell - sudo scp /var/opt/gitlab/redis/dump.rdb <your-linux-username>@new-server:/var/opt/gitlab/redis - sudo scp /var/opt/gitlab/backups/your-backup.tar <your-linux-username>@new-server:/var/opt/gitlab/backups - ``` - -### Restore data on the new server - -1. Restore appropriate file system permissions: - - ```shell - sudo chown gitlab-redis /var/opt/gitlab/redis - sudo chown gitlab-redis:gitlab-redis /var/opt/gitlab/redis/dump.rdb - sudo chown git:root /var/opt/gitlab/backups - sudo chown git:git /var/opt/gitlab/backups/your-backup.tar - ``` - -1. [Restore the GitLab backup](#restore-gitlab). -1. Verify that the Redis database restored correctly: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Monitoring > Background Jobs**. - 1. Under the Sidekiq dashboard, verify that the numbers - match with what was shown on the old server. - 1. While still under the Sidekiq dashboard, select **Cron** and then **Enable All** - to re-enable periodic background jobs. -1. Test that read-only operations on the GitLab instance work as expected. For example, browse through project repository files, merge requests, and issues. -1. Disable [Maintenance Mode](../maintenance_mode/index.md), if previously enabled. -1. Test that the GitLab instance is working as expected. -1. If applicable, re-enable [incoming email](../incoming_email.md) and test it is working as expected. -1. Update your DNS or load balancer to point at the new server. -1. Unblock new CI/CD jobs from starting by removing the custom NGINX configuration - you added previously: - - ```ruby - # The following line must be removed - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Remove the scheduled maintenance [broadcast message banner](../broadcast_messages.md). +For detailed information on using back up and restore to migrate to a new server, see +[Migrate to a new server](migrate_to_new_server.md). ## Additional notes @@ -224,6 +36,187 @@ methods to export or back up your data yourself from GitLab.com. Issues are stored in the database, and can't be stored in Git itself. +## GitLab backup archive creation process + +When working with GitLab backups, you might need to know how GitLab creates backup archives. To create backup archives, GitLab: + +1. If creating an incremental backup, extracts the previous backup archive and read its `backup_information.yml` file. +1. Updates or generates the `backup_information.yml` file. +1. Runs all backup sub-tasks: + - `db` to backup the GitLab PostgreSQL database (not Gitaly Cluster). + - `repositories` to back up Git repositories. + - `uploads` to back up attachments. + - `builds` to back up CI job output logs. + - `artifacts` to back up CI job artifacts. + - `pages` to back up page content. + - `lfs` to back up LFS objects. + - `terraform_state` to back up Terraform states. + - `registry` to back up container registry images. + - `packages` to back up packages. + - `ci_secure_files` to back up project-level secure files. +1. Archives the backup staging area into a tar file. +1. Optional. Uploads the new backup archive to object-storage. +1. Cleans up backup staging directory files that are now archived. + +## Backup ID + +Backup IDs identify individual backup archives. You need the backup ID of a backup archive if you need to restore GitLab and multiple backup archives are available. + +Backup archives are saved in a directory set in `backup_path`, which is specified in the `config/gitlab.yml` file. + +- By default, backup archives are stored in `/var/opt/gitlab/backups`. +- By default, backup archive file names are `<backup-id>_gitlab_backup.tar` where `<backup-id>` identifies the time when the + backup archive was created, the GitLab version, and the GitLab edition. + +For example, if the archive file name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, +the backup ID is `1493107454_2018_04_25_10.6.4-ce`. + +## Backup staging directory + +The backup staging directory is a place to temporarily: + +- Store backup artifacts on disk before the GitLab backup archive is created. +- Extract backup archives on disk before restoring a backup or creating an incremental backup. + +This directory is the same directory where completed GitLab backup archives are created. When creating an untarred backup, the backup artifacts are left in this directory and no +archive is created. + +Example backup staging directory with untarred backup: + +```plaintext +backups/ +├── 1701728344_2023_12_04_16.7.0-pre_gitlab_backup.tar +├── 1701728447_2023_12_04_16.7.0-pre_gitlab_backup.tar +├── artifacts.tar.gz +├── backup_information.yml +├── builds.tar.gz +├── ci_secure_files.tar.gz +├── db +│ ├── ci_database.sql.gz +│ └── database.sql.gz +├── lfs.tar.gz +├── packages.tar.gz +├── pages.tar.gz +├── repositories +│ ├── manifests/ +│ ├── @hashed/ +│ └── @snippets/ +├── terraform_state.tar.gz +└── uploads.tar.gz +``` + +## `backup_information.yml` file + +The `backup_information.yml` file saves all backup inputs that are not included in the backup itself. It includes information such as: + +- The time the backup was created. +- The version of GitLab that generated the backup. +- Any options that were specified, such as skipped sub-tasks. + +This information is used by some sub-tasks to determine how: + +- To restore. +- To link data in the backup with external services (such as server-side repository backups). + +This file is saved into the backup staging directory. + +## Database backups + +Database backups are created and restored by a GitLab backup sub-task called `db`. The database sub-task uses `pg_dump` to create [a SQL dump](https://www.postgresql.org/docs/14/backup-dump.html). The output of `pg_dump` is piped through `gzip` in order to create a compressed SQL file. This file is saved to the backup staging directory. + +## Repository backups + +Repository backups are created and restored by a GitLab backup sub-task called `repositories`. The repositories sub-task uses a Gitaly command +[`gitaly-backup`](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/gitaly-backup.md) to create Git repository backups: + +- GitLab uses its database to tell `gitaly-backup` which repositories to back up. +- `gitaly-backup` then calls a series of RPCs on Gitaly to collect the repository backup data for each repository. This data is streamed into a directory structure in the GitLab backup staging directory. + +```mermaid +sequenceDiagram + box Backup host + participant Repositories sub-task + participant gitaly-backup + end + + Repositories sub-task->>+gitaly-backup: List of repositories + + loop Each repository + gitaly-backup->>+Gitaly: ListRefs request + Gitaly->>-gitaly-backup: List of Git references + + gitaly-backup->>+Gitaly: CreateBundleFromRefList request + Gitaly->>-gitaly-backup: Git bundle file + + gitaly-backup->>+Gitaly: GetCustomHooks request + Gitaly->>-gitaly-backup: Custom hooks archive + end + + gitaly-backup->>-Repositories sub-task: Success/failure +``` + +Storages configured to Gitaly Cluster are backed up the same as standalone Gitaly. When Gitaly Cluster receives the RPC calls from `gitaly-backup`, it is responsible for +rebuilding its own database. This means that there is no need to backup the Gitaly Cluster database separately. Because backups operate through RPCs, each repository is only backed +up once no matter the replication factor. + +### Server-side repository backups + +You can configure repository backups as server-side repository backups. When specified, `gitaly-backup` makes a single RPC call for each repository to create the backup. This RPC +does not transmit any repository data. Instead, the RPC triggers the Gitaly node that stores that physical repository to upload the backup data directly to object-storage. Because +the data is no longer transmitted through RPCs from Gitaly, server-side backups require much less network transfer and require no disk storage on the machine that is running the +backup Rake task. The backups stored on object-storage are linked to the created backup archive by [the backup ID](#backup-id). + +```mermaid +sequenceDiagram + box Backup host + participant Repositories sub-task + participant gitaly-backup + end + + Repositories sub-task->>+gitaly-backup: List of repositories + + loop Each repository + gitaly-backup->>+Gitaly: BackupRepository request + + Gitaly->>+Object-storage: Git references file + Object-storage->>-Gitaly: Success/failure + + Gitaly->>+Object-storage: Git bundle file + Object-storage->>-Gitaly: Success/failure + + Gitaly->>+Object-storage: Custom hooks archive + Object-storage->>-Gitaly: Success/failure + + Gitaly->>+Object-storage: Backup manifest file + Object-storage->>-Gitaly: Success/failure + + Gitaly->>-gitaly-backup: Success/failure + end + + gitaly-backup->>-Repositories sub-task: Success/failure +``` + +## File backups + +The following GitLab backup sub-tasks back up files: + +- `uploads` +- `builds` +- `artifacts` +- `pages` +- `lfs` +- `terraform_state` +- `registry` +- `packages` +- `ci_secure_files` + +These file sub-tasks determine a set of files within a directory specific to the task. This set of files is then passed to `tar` +to create an archive. This archive is piped (not saved to disk) through `gzip` to save a compressed tar file to the backup staging directory. + +Because backups are created from live instances, the files that tar is trying to archive can sometimes be modified while creating the backup. In this case, an alternate "copy" +strategy can be used. When this strategy is used, `rsync` is first used to create a copy of the files to back up. Then, these copies are passed to `tar` as usual. In this case, +the machine running the backup Rake task must have enough storage for the copied files and the compressed archive. + ## Related features - [Geo](../geo/index.md) diff --git a/doc/administration/backup_restore/migrate_to_new_server.md b/doc/administration/backup_restore/migrate_to_new_server.md new file mode 100644 index 00000000000..7b04861cc7c --- /dev/null +++ b/doc/administration/backup_restore/migrate_to_new_server.md @@ -0,0 +1,208 @@ +--- +stage: Systems +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Migrate to a new server + +<!-- some details borrowed from GitLab.com move from Azure to GCP detailed at https://gitlab.com/gitlab-com/migration/-/blob/master/.gitlab/issue_templates/failover.md --> + +You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server. +If you're running GitLab Geo, an alternative option is [Geo disaster recovery for planned failover](../geo/disaster_recovery/planned_failover.md). + +WARNING: +Avoid uncoordinated data processing by both the new and old servers, where multiple +servers could connect concurrently and process the same data. For example, when using +[incoming email](../incoming_email.md), if both GitLab instances are +processing email at the same time, then both instances miss some data. +This type of problem can occur with other services as well, such as a +[non-packaged database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server), +a non-packaged Redis instance, or non-packaged Sidekiq. + +Prerequisites: + +- Some time before your migration, consider notifying your users of upcoming + scheduled maintenance with a [broadcast message banner](../broadcast_messages.md). +- Ensure your backups are complete and current. Create a complete system-level backup, or + take a snapshot of all servers involved in the migration, in case destructive commands + (like `rm`) are run incorrectly. + +## Prepare the new server + +To prepare the new server: + +1. Copy the + [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) + from the old server to avoid man-in-the-middle attack warnings. + See [Manually replicate the primary site's SSH host keys](../geo/replication/configuration.md#step-2-manually-replicate-the-primary-sites-ssh-host-keys) for example steps. +1. [Install and configure GitLab](https://about.gitlab.com/install/) except + [incoming email](../incoming_email.md): + 1. Install GitLab. + 1. Configure by copying `/etc/gitlab` files from the old server to the new server, and update as necessary. + Read the + [Linux package installation backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. + 1. If applicable, disable [incoming email](../incoming_email.md). + 1. Block new CI/CD jobs from starting upon initial startup after the backup and restore. + Edit `/etc/gitlab/gitlab.rb` and set the following: + + ```ruby + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Stop GitLab to avoid any potential unnecessary and unintentional data processing: + + ```shell + sudo gitlab-ctl stop + ``` + +1. Configure the new server to allow receiving the Redis database and GitLab backup files: + + ```shell + sudo rm -f /var/opt/gitlab/redis/dump.rdb + sudo chown <your-linux-username> /var/opt/gitlab/redis /var/opt/gitlab/backups + ``` + +## Prepare and transfer content from the old server + +1. Ensure you have an up-to-date system-level backup or snapshot of the old server. +1. Enable [maintenance mode](../maintenance_mode/index.md), + if supported by your GitLab edition. +1. Block new CI/CD jobs from starting: + 1. Edit `/etc/gitlab/gitlab.rb`, and set the following: + + ```ruby + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Disable periodic background jobs: + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, select **Cron** tab and then + **Disable All**. +1. Wait for the currently running CI/CD jobs to finish, or accept that jobs that have not completed may be lost. + To view jobs currently running, on the left sidebar, select **Overviews > Jobs**, + and then select **Running**. +1. Wait for Sidekiq jobs to finish: + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, select **Queues** and then **Live Poll**. + Wait for **Busy** and **Enqueued** to drop to 0. + These queues contain work that has been submitted by your users; + shutting down before these jobs complete may cause the work to be lost. + Make note of the numbers shown in the Sidekiq dashboard for post-migration verification. +1. Flush the Redis database to disk, and stop GitLab other than the services needed for migration: + + ```shell + sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && sudo gitlab-ctl stop && sudo gitlab-ctl start postgresql && sudo gitlab-ctl start gitaly + ``` + +1. Create a GitLab backup: + + ```shell + sudo gitlab-backup create + ``` + +1. Disable the following GitLab services and prevent unintentional restarts by adding the following to the bottom of `/etc/gitlab/gitlab.rb`: + + ```ruby + alertmanager['enable'] = false + gitlab_exporter['enable'] = false + gitlab_pages['enable'] = false + gitlab_workhorse['enable'] = false + grafana['enable'] = false + logrotate['enable'] = false + gitlab_rails['incoming_email_enabled'] = false + nginx['enable'] = false + node_exporter['enable'] = false + postgres_exporter['enable'] = false + postgresql['enable'] = false + prometheus['enable'] = false + puma['enable'] = false + redis['enable'] = false + redis_exporter['enable'] = false + registry['enable'] = false + sidekiq['enable'] = false + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Verify everything is stopped, and confirm no services are running: + + ```shell + sudo gitlab-ctl status + ``` + +1. Stop Redis on the **new server** before transferring the Redis database backup: + + ```shell + sudo gitlab-ctl stop redis + ``` + +1. Transfer the Redis database and GitLab backups to the new server: + + ```shell + sudo scp /var/opt/gitlab/redis/dump.rdb <your-linux-username>@new-server:/var/opt/gitlab/redis + sudo scp /var/opt/gitlab/backups/your-backup.tar <your-linux-username>@new-server:/var/opt/gitlab/backups + ``` + +## Restore data on the new server + +1. Restore appropriate file system permissions: + + ```shell + sudo chown gitlab-redis /var/opt/gitlab/redis + sudo chown gitlab-redis:gitlab-redis /var/opt/gitlab/redis/dump.rdb + sudo chown git:root /var/opt/gitlab/backups + sudo chown git:git /var/opt/gitlab/backups/your-backup.tar + ``` + +1. Start Redis: + + ```shell + sudo gitlab-ctl start redis + ``` + +1. [Restore the GitLab backup](restore_gitlab.md). +1. Verify that the Redis database restored correctly: + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, verify that the numbers + match with what was shown on the old server. + 1. While still under the Sidekiq dashboard, select **Cron** and then **Enable All** + to re-enable periodic background jobs. +1. Test that read-only operations on the GitLab instance work as expected. For example, browse through project repository files, merge requests, and issues. +1. Disable [Maintenance Mode](../maintenance_mode/index.md), if previously enabled. +1. Test that the GitLab instance is working as expected. +1. If applicable, re-enable [incoming email](../incoming_email.md) and test it is working as expected. +1. Update your DNS or load balancer to point at the new server. +1. Unblock new CI/CD jobs from starting by removing the custom NGINX configuration + you added previously: + + ```ruby + # The following line must be removed + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Remove the scheduled maintenance [broadcast message banner](../broadcast_messages.md). diff --git a/doc/administration/backup_restore/restore_gitlab.md b/doc/administration/backup_restore/restore_gitlab.md index 9b6c6eb557a..2dd85602f99 100644 --- a/doc/administration/backup_restore/restore_gitlab.md +++ b/doc/administration/backup_restore/restore_gitlab.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Restore GitLab **(FREE SELF)** @@ -100,7 +100,7 @@ sudo gitlab-ctl status Next, ensure you have completed the [restore prerequisites](#restore-prerequisites) steps and have run `gitlab-ctl reconfigure` after copying over the GitLab secrets file from the original installation. -Next, restore the backup, specifying the timestamp of the backup you wish to +Next, restore the backup, specifying the ID of the backup you wish to restore: ```shell @@ -301,8 +301,8 @@ options. ### Specify backup to restore when there are more than one -By default, backup files use a naming scheme [starting with a timestamp](backup_gitlab.md#backup-timestamp). When more than one backup exists, you must specify which -`*_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=timestamp_of_backup`. +Backup files use a naming scheme [starting with a backup ID](index.md#backup-id). When more than one backup exists, you must specify which +`<backup-id>_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=<backup-id>`. ### Disable prompts during restore @@ -340,7 +340,7 @@ You can exclude specific tasks on restore by adding the environment variable `SK - `artifacts` (CI job artifacts) - `lfs` (LFS objects) - `terraform_state` (Terraform states) -- `registry` (Container Registry images) +- `registry` (Container registry images) - `pages` (Pages content) - `repositories` (Git repositories data) - `packages` (Packages) @@ -350,13 +350,13 @@ To exclude specific tasks: - Linux package installations: ```shell - sudo gitlab-backup restore BACKUP=timestamp_of_backup SKIP=db,uploads + sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads ``` - Self-compiled installations: ```shell - sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup SKIP=db,uploads RAILS_ENV=production + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production ``` ### Restore specific repository storages @@ -373,13 +373,13 @@ For example: - Linux package installations: ```shell - sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 + sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2 ``` - Self-compiled installations: ```shell - sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2 ``` ### Restore specific repositories @@ -397,19 +397,19 @@ and skip the **Project D** in **Group A** (`group-a/project-d`): - Linux package installations: ```shell - sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d + sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d ``` - Self-compiled installations: ```shell - sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d ``` ### Restore untarred backups If an [untarred backup](backup_gitlab.md#skipping-tar-creation) (made with `SKIP=tar`) is found, -and no backup is chosen with `BACKUP=<timestamp>`, the untarred backup is used. +and no backup is chosen with `BACKUP=<backup-id>`, the untarred backup is used. For example: @@ -471,7 +471,7 @@ While restoring from backup, you can encounter an error when the following are t The error looks like: ```plaintext -{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupTimestamp>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"} +{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"} ``` To resolve this, you can update the Git [server hooks](../server_hooks.md) for GitLab version 15.11 and later, and create a new backup. diff --git a/doc/administration/broadcast_messages.md b/doc/administration/broadcast_messages.md index 4ed80010220..5a1cb88e876 100644 --- a/doc/administration/broadcast_messages.md +++ b/doc/administration/broadcast_messages.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Broadcast messages **(FREE SELF)** @@ -57,8 +56,7 @@ To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Messages**. 1. Select **Add new message**. 1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. @@ -86,8 +84,7 @@ If you must make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Messages**. 1. From the list of broadcast messages, select the edit button for the message. 1. After making the required changes, select **Update broadcast message**. @@ -101,8 +98,7 @@ You can delete a broadcast message while it's active. To delete a broadcast message: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Messages**. 1. From the list of broadcast messages, select the delete button for the message. diff --git a/doc/administration/cicd.md b/doc/administration/cicd.md index 10bc60fe399..4fd11041e91 100644 --- a/doc/administration/cicd.md +++ b/doc/administration/cicd.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD instance configuration **(FREE SELF)** diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index a6d20327802..9c87576aa80 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install the GitLab agent server for Kubernetes (KAS) **(FREE SELF)** diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 3f4d781e2a2..73583856cb0 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance features **(FREE SELF)** diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 8ff2ae5aa9d..8b4f8a9abc6 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure your GitLab installation **(FREE SELF)** diff --git a/doc/administration/consul.md b/doc/administration/consul.md index a65b2100237..0740c27dc7c 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to set up Consul **(PREMIUM SELF)** diff --git a/doc/administration/credentials_inventory.md b/doc/administration/credentials_inventory.md index d7b67dfd703..1bd4ce75891 100644 --- a/doc/administration/credentials_inventory.md +++ b/doc/administration/credentials_inventory.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Credentials inventory **(ULTIMATE SELF)** @@ -37,8 +36,7 @@ You can also [revoke](#revoke-a-users-personal-access-token), [delete](#delete-a You can revoke a user's personal access token. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Credentials**. 1. By the personal access token, select **Revoke**. @@ -58,8 +56,7 @@ When a PAT is revoked from the credentials inventory, the instance notifies the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Credentials**. 1. Select the **Project Access Tokens** tab. 1. By the project access token, select **Revoke**. @@ -72,8 +69,7 @@ The project access token is revoked and a background worker is queued to delete > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Credentials**. 1. Select the **SSH Keys** tab. 1. By the SSH key, select **Delete**. diff --git a/doc/administration/custom_project_templates.md b/doc/administration/custom_project_templates.md index 239ec09de86..3c3319c80f9 100644 --- a/doc/administration/custom_project_templates.md +++ b/doc/administration/custom_project_templates.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom instance-level project templates **(PREMIUM SELF)** @@ -24,9 +24,8 @@ might modify the template projects without understanding the side effects. To select the group to manage the project templates for your instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Templates**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Templates**. 1. Expand **Custom project templates**. 1. Select a group to use. 1. Select **Save changes**. @@ -51,7 +50,7 @@ Prerequisites: - **Public** and **Internal** projects can be selected by any authenticated user. - **Private** projects can be selected only by members of that project. 1. Review the project's - [feature settings](../user/project/settings/index.md#configure-project-features-and-permissions). + [feature settings](../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). All enabled project features should be set to **Everyone With Access**, except **GitLab Pages** and **Security and Compliance**. diff --git a/doc/administration/dedicated/index.md b/doc/administration/dedicated/index.md index 16efc353c84..ef9e53c8fb7 100644 --- a/doc/administration/dedicated/index.md +++ b/doc/administration/dedicated/index.md @@ -1,7 +1,7 @@ --- stage: SaaS Platforms group: GitLab Dedicated -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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: 'Learn how to configure your GitLab Dedicated instance.' --- @@ -60,7 +60,7 @@ It can take up to 3 hours to create the GitLab Dedicated tenant. When the setup Available scheduled maintenance windows, performed outside standard working hours: - APAC: Wednesday 1 PM - 5 PM UTC -- EU: Tuesday 1 AM - 5 AM UTC +- EMEA: Tuesday 1 AM - 5 AM UTC - AMER Option 1: Tuesday 7 AM - 11 AM UTC - AMER Option 2: Sunday 9 PM - Monday 1 AM UTC @@ -214,11 +214,33 @@ Make sure the AWS KMS keys are replicated to your desired primary, secondary and ## Configuration changes +### Configuration change policy + +Configuration changes requested with a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) are batched up and applied during your environment's weekly four-hour maintenance window. + +This policy does not apply to configuration changes made by a GitLab Dedicated tenant admin [using Switchboard](#configuration-changes-in-switchboard). + +To have a change considered for an upcoming weekly maintenance window, all required information +must be submitted in full two business days before the start of the window. + +A configuration change might not be applied during an upcoming weekly maintenance window, even if +it meets the minimum lead time. If GitLab needs to perform high-priority maintenance tasks that +run beyond the maintenance window, configuration changes will be postponed to the following week. + +Changes requested with a support ticket cannot be applied outside of a weekly maintenance window unless it qualifies for +[emergency support](https://about.gitlab.com/support/#how-to-engage-emergency-support). + +### Configuration changes in Switchboard + Switchboard empowers the user to make limited configuration changes to their Dedicated Tenant Instance. As Switchboard matures further configuration changes will be made available. -To change or update the configuration of your GitLab Dedicated instance, use Switchboard following the instructions in the relevant section or open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with your request. You can request configuration changes for the options originally specified during onboarding, or for any of the following optional features. +To change or update the configuration of your GitLab Dedicated instance, use Switchboard following the instructions in the relevant section or open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with your request. + +You can request configuration changes for some of the options originally specified during onboarding, or for any of the following optional features. + +Configuration changes made with Switchboard can be applied immediately or deferred until your next scheduled weekly [maintenance window](#maintenance-window). -The turnaround time to process configuration change requests is [documented in the GitLab handbook](https://about.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/#handling-configuration-changes-for-tenant-environments). +When applied immediately, changes may take up to 90 minutes to be deployed to your environment. Individual changes are applied in the order they are saved, or you may choose to save several changes at once before applying them in one batch. ### Inbound Private Link @@ -226,7 +248,7 @@ The turnaround time to process configuration change requests is [documented in t To enable the Inbound Private Link: -1. In the body of your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650), include the IAM Principal for the AWS user or role in your own AWS Organization that's establishing the VPC endpoint in your AWS account. GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service. +1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). In the body of your support ticket, include the IAM principal for the AWS user or role in your AWS organization that's establishing the VPC endpoint in your AWS account. The IAM principal must be an [IAM role principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-roles) or [IAM user principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-users). GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service. 1. After your IAM Principal has been allowlisted, GitLab [creates the Endpoint Service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) and communicates the `Service Endpoint Name` on the support ticket. The service name is generated by AWS upon creation of the service endpoint. - GitLab handles the domain verification for the Private DNS name, so that DNS resolution of the tenant instance domain name in your VPC resolves to the PrivateLink endpoint. - GitLab makes the Endpoint Service available in the Availability Zones you specified during the initial onboarding. If you did not specify any Availability Zones, GitLab randomly selects the Availability Zones IDs. @@ -304,7 +326,9 @@ GitLab Dedicated limits the number of reverse PrivateLink connections to 10. ### IP allowlist -GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. +GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. Once the IP allowlist has been enabled, when an IP not on the allowlist tries to access your instance an `HTTP 403 Forbidden` response is returned. + +IP addresses that have been added to your IP allowlist can be viewed on the Configuration page in Switchboard. You can add or remove IP addresses from your allowlist with Switchboard or a support request. #### Add an IP to the allowlist with Switchboard @@ -315,11 +339,11 @@ GitLab Dedicated allows you to control which IP addresses can access your instan 1. Select **Add Item**. 1. Enter the IP address and description. To add another IP address, repeat steps 5 and 6. 1. Select **Save**. -1. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window. +1. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window. After the changes are applied, the IP addresses are added to the IP allowlist for your instance. #### Add an IP to the allowlist with a Support Request -Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). After the configuration has been applied, when an IP not on the allowlist tries to access your instance, the connection is refused. +Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). The IP addresses are then added to the IP allowlist for your instance. ### SAML @@ -410,6 +434,23 @@ To enable group sync: 1. Add the [required elements](../../user/group/saml_sso/group_sync.md#configure-saml-group-sync) to the SAML configuration block you provide in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). 1. Configure the [Group Links](../../user/group/saml_sso/group_sync.md#configure-saml-group-links). +### Add users to a tenant instance + +Tenant administrators can add Switchboard users to their tenant instance. There are two types of users: + +- **Read only**: Users can only view tenant data. +- **Admin**: Users can edit the tenant configuration and manage users. + +To add a new user to your GitLab Dedicated instance: + +1. From the **Tenants** page, select **Manage** next to the tenant instance. +1. From the top of the page, select **Users**. +1. Select **New user**. +1. Enter the **Email** and select a **Role** for the user. +1. Select **Create**. + +An invitation to use Switchboard is sent to the user. + ### Access to application logs GitLab [application logs](../../administration/logs/index.md) are delivered to an S3 bucket in the GitLab tenant account, which can be shared with you. Logs stored in the S3 bucket are retained indefinitely, until the 1 year retention policy is fully enforced. GitLab team members can view more information in this confidential issue: @@ -419,3 +460,11 @@ To gain read only access to this bucket: 1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with the title "Customer Log Access". In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that are fetching the logs from S3. 1. GitLab then informs you of the name of the S3 bucket. Your nominated users/roles are then able to list and get all objects in the S3 bucket. + +You can use the [AWS CLI](https://aws.amazon.com/cli/) to verify that access to the S3 bucket works as expected. + +#### Bucket contents and structure + +The S3 bucket contains a combination of **infrastructure logs** and **application logs** from the GitLab [log system](../../administration/logs/index.md). The logs in the bucket are encrypted using an AWS KMS key that is managed by GitLab. If you choose to enable [BYOK](#encrypted-data-at-rest-byok), the application logs are not encrypted with the key you provide. + +The logs in the S3 bucket are organized by date in `YYYY/MM/DD/HH` format. For example, there would be a directory like `2023/10/12/13`. That directory would contain the logs from October 12, 2023 at 1300 UTC. The logs are streamed into the bucket with [Amazon Kinesis Data Firehose](https://aws.amazon.com/kinesis/data-firehose/). diff --git a/doc/administration/diff_limits.md b/doc/administration/diff_limits.md index dcf5a2b1b32..66a1e86b025 100644 --- a/doc/administration/diff_limits.md +++ b/doc/administration/diff_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Diff limits administration **(FREE SELF)** @@ -33,8 +32,7 @@ set values are presented as **Too large** are cannot be expanded in the UI. To configure these values: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for the diff limit. diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 1eecc139d1f..5b9bfe82294 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Host the GitLab product documentation **(FREE SELF)** @@ -82,7 +82,7 @@ To run the GitLab product documentation website in a Docker container: You can use GitLab Pages to host the GitLab product documentation. -Prerequisite: +Prerequisites: - Ensure the Pages site URL does not use a subfolder. Because of the way the site is pre-compiled, the CSS and JavaScript files are relative to the diff --git a/doc/administration/email_from_gitlab.md b/doc/administration/email_from_gitlab.md index ec231d25da2..0fe07c63169 100644 --- a/doc/administration/email_from_gitlab.md +++ b/doc/administration/email_from_gitlab.md @@ -1,43 +1,35 @@ --- 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/product/ux/technical-writing/#assignments -type: howto, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Email from GitLab **(PREMIUM SELF)** -GitLab provides a tool to administrators for emailing all users, or users of -a chosen group or project, right from the Admin Area. Users receive the email -at their primary email address. +Administrators can email all users, or users of a chosen group or project. +Users receive the email at their primary email address. -For information about email notifications originating from GitLab, read -[GitLab notification emails](../user/profile/notifications.md). +You might use this functionality to notify your users: -## Use-cases +- About a new project, a new feature, or a new product launch. +- About a new deployment, or that downtime is expected. -- Notify your users about a new project, a new feature, or a new product launch. -- Notify your users about a new deployment, or that downtime is expected - for a particular reason. +For information about email notifications originating from GitLab, read +[GitLab notification emails](../user/profile/notifications.md). ## Sending emails to users from GitLab -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select **Send email to users**. - -  +You can send email notifications to all users, or only to users in a specific group or project. +You can send email notifications once every 10 minutes. -1. Compose an email and choose where to send it (all users or users of a - chosen group or project). The email body only supports plain text messages. - HTML, Markdown, and other rich text formats are not supported, and is - sent as plain text to users. +To send an email: -  - -NOTE: -[Starting with GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/31509), email notifications can be sent only once every 10 minutes. This helps minimize performance issues. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. +1. In the upper-right corner, select **Send email to users** (**{mail}**). +1. Complete the fields. The email body supports only plain text and does not support HTML, Markdown, or other rich text formats. +1. From the **Select group or project** dropdown list, select the recipient. +1. Select **Send message**. ## Unsubscribing from emails diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 4ffb1495ec8..1346786446c 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Encrypted Configuration **(FREE SELF)** diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index 260095d12ac..c3bc4b0bc1f 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environment variables **(FREE SELF)** @@ -39,6 +38,8 @@ You can use the following environment variables to override certain values: | `RAILS_ENV` | string | The Rails environment; can be one of `production`, `development`, `staging`, or `test`. | | `GITLAB_RAILS_CACHE_DEFAULT_TTL_SECONDS` | integer | The default TTL used for entries stored in the Rails-cache. Default is `28800`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95042) in 15.3. | | `GITLAB_CI_CONFIG_FETCH_TIMEOUT_SECONDS` | integer | Timeout for resolving remote includes in CI config in seconds. Must be between `0` and `60`. Default is `30`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116383) in 15.11. | +| `GITLAB_LFS_MAX_OID_TO_FETCH` | integer | Sets the maximum number of LFS objects to link. Default is `100,000`. | +| `SIDEKIQ_SEMI_RELIABLE_FETCH_TIMEOUT` | integer | Sets the timeout for Sidekiq semi-reliable fetch. Default is `5`. [Before GitLab 16.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139583), default was `3`. If you experience high Redis CPU consumption on GitLab 16.6 and earlier, or if you have customized this variable, you should update this variable to `5`. | ## Adding more variables diff --git a/doc/administration/external_pipeline_validation.md b/doc/administration/external_pipeline_validation.md index 9d182a95fc9..5442bc74125 100644 --- a/doc/administration/external_pipeline_validation.md +++ b/doc/administration/external_pipeline_validation.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External pipeline validation **(FREE SELF)** diff --git a/doc/administration/external_users.md b/doc/administration/external_users.md index 5c3f3ae26b1..d8951631b72 100644 --- a/doc/administration/external_users.md +++ b/doc/administration/external_users.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External users **(FREE SELF)** @@ -30,7 +30,7 @@ For example, if an external user is added as Guest, and your project is internal private, they do not have access to the code; you need to grant the external user access at the Reporter level or above if you want them to have access to the code. You should always take into account the -[project's visibility](../user/public_access.md#change-project-visibility) and [permissions settings](../user/project/settings/index.md#configure-project-features-and-permissions) +[project's visibility](../user/public_access.md#change-project-visibility) and [permissions settings](../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions) as well as the permission level of the user. NOTE: @@ -40,8 +40,7 @@ An administrator can flag a user as external by either of the following methods: - [Through the API](../api/users.md#user-modification). - Using the GitLab UI: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. @@ -56,8 +55,7 @@ Additionally, users can be set as external users using: By default, new users are not set as external users. This behavior can be changed by an administrator: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 76bcc8c699e..b40334fe507 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags" --- diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index d1b46a9fec1..a16e1c2fde9 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -1,8 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # File hooks **(FREE SELF)** diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 8aec77d9d88..a927450d80f 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automatic background verification **(PREMIUM SELF)** @@ -27,9 +27,8 @@ the site more time before scheduling a planned failover. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Expand **Verification information** tab for that site to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work in gray, and failures in red. @@ -38,9 +37,8 @@ On the **primary** site: On the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Expand **Verification information** tab for that site to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work in gray, and failures in red. @@ -67,9 +65,8 @@ increase load and vice versa. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** for the **primary** site to customize the minimum re-verification interval: @@ -101,8 +98,7 @@ sudo gitlab-rake geo:verification:wiki:reset If the **primary** and **secondary** sites have a checksum verification mismatch, the cause may not be apparent. To find the cause of a checksum mismatch: 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Projects**. 1. Find the project that you want to check the checksum differences and select its name. diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 5f2cbd4d03b..be4f4d3f6a4 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bring a demoted primary site back online **(PREMIUM SELF)** diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 2f636dc6ba4..f97c892c3eb 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disaster Recovery (Geo) **(PREMIUM SELF)** diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index cdc52b55c3e..01e5c33a726 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disaster recovery for planned failover **(PREMIUM SELF)** @@ -45,7 +44,7 @@ be adapted for use with any other file-based data. ### Container registry By default, the container registry is not automatically replicated to secondary -sites and this needs to be manually configured, see [Container Registry for a secondary site](../replication/container_registry.md). +sites and this needs to be manually configured, see [container registry for a secondary site](../replication/container_registry.md). If you are using local storage on your current primary site for the container registry, you can `rsync` the container registry objects to the secondary @@ -154,9 +153,8 @@ ensure these processes are close to 100% as possible during active use. On the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of objects aren't yet replicated (shown in gray), consider giving the site more @@ -183,9 +181,8 @@ This [content was moved to another location](background_verification.md). On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Messages**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Messages**. 1. Add a message notifying users on the maintenance window. You can check under **Geo > Sites** to estimate how long it takes to finish syncing. @@ -197,9 +194,8 @@ To ensure that all data is replicated to a secondary site, updates (write reques be disabled on the **primary** site: 1. Enable [maintenance mode](../../maintenance_mode/index.md) on the **primary** site. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Background Jobs**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Cron**. 1. Select `Disable All` to disable non-Geo periodic background jobs. 1. Select `Enable` for the `geo_sidekiq_cron_config_worker` cron job. @@ -211,8 +207,7 @@ be disabled on the **primary** site: 1. If you are manually replicating any data not managed by Geo, trigger the final replication process now. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -227,8 +222,7 @@ be disabled on the **primary** site: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. 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 787e7c4669e..f24d2bba2a3 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,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- WARNING: @@ -65,9 +64,8 @@ promote a Geo replica and perform a failover. On the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites** to see its status. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites** to see its status. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of objects aren't replicated (shown in gray), consider giving the site more @@ -105,8 +103,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -121,8 +118,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. 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 e29b19ca040..0afd669e797 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,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- WARNING: @@ -115,8 +114,7 @@ follow these steps to avoid unnecessary data loss: connection. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Cron**. 1. Select `Disable All` to disable any non-Geo periodic background jobs. @@ -134,8 +132,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -150,8 +147,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md index d0f94ba39f5..138bf6c444c 100644 --- a/doc/administration/geo/glossary.md +++ b/doc/administration/geo/glossary.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index e8b2cb38563..6609bbed5a6 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo **(PREMIUM SELF)** @@ -115,15 +115,16 @@ The following are required to run Geo: The following operating systems are known to ship with a current version of OpenSSH: - [CentOS](https://www.centos.org) 7.4 or later - [Ubuntu](https://ubuntu.com) 16.04 or later -- PostgreSQL 12 or 13 with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) +- [Supported PostgreSQL versions](https://about.gitlab.com/handbook/engineering/development/enablement/data_stores/database/postgresql-upgrade-cadence.html) for your GitLab releases with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication). - Note,[PostgreSQL 12 is deprecated](../../update/deprecations.md#postgresql-12-deprecated) and is removed in GitLab 16.0. +- All sites must run [the same PostgreSQL versions](setup/database.md#postgresql-replication). + - Where possible, you should also use the same operating system version on all + Geo sites. If using different operating system versions between Geo sites, you + **must** [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) + across Geo sites to avoid silent corruption of database indexes. - Git 2.9 or later - Git-lfs 2.4.2 or later on the user side when using LFS - All sites must run the same GitLab version. -- All sites must run [the same PostgreSQL versions](setup/database.md#postgresql-replication). - - If using different operating system versions between Geo sites, - [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) - across Geo sites to avoid silent corruption of database indexes. - All sites must define the same [repository storages](../repository_storage_paths.md). Additionally, check the GitLab [minimum requirements](../../install/requirements.md), @@ -159,9 +160,8 @@ public URL of the primary site is used. To update the internal URL of the primary Geo site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** on the primary site. 1. Change the **Internal URL**, then select **Save changes**. @@ -245,17 +245,29 @@ Linux package-managed database. External databases are not supported. In some circumstances, like during [upgrades](replication/upgrading_the_geo_sites.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. -Pausing and resuming replication is done through a command-line tool from the node in the secondary site where the `postgresql` service is enabled. +If you plan to allow user activity on your secondary sites during the upgrade, +do not pause replication for a [zero downtime upgrade](../../update/zero_downtime.md). While paused, the secondary site gets more and more out-of-date. +One known effect is that more and more Git fetches get redirected or proxied to the primary site. There may be additional unknown effects. + +Pausing and resuming replication is done through a command-line tool from a specific node in the secondary site. Depending on your database architecture, +this will target either the `postgresql` or `patroni` service: + +- If you are using a single node for all services on your secondary site, you must run the commands on this single node. +- If you have a standalone PostgreSQL node on your secondary site, you must run the commands on this standalone PostgreSQL node. +- If your secondary site is using a Patroni cluster, you must run these commands on the secondary Patroni standby leader node. + +If you aren't using a single node for all services on your secondary site, ensure that the `/etc/gitlab/gitlab.rb` on your PostgreSQL or Patroni nodes +contains the configuration line `gitlab_rails['geo_node_name'] = 'node_name'`, where `node_name` is the same as the `geo_node_name` on the application node. -If `postgresql` is on a standalone database node, ensure that `gitlab.rb` on that node contains the configuration line `gitlab_rails['geo_node_name'] = 'node_name'`, where `node_name` is the same as the `geo_node_name` on the application node. +**To Pause: (from secondary site)** -**To Pause: (from secondary)** +Also, be aware that if PostgreSQL is restarted after pausing replication (either by restarting the VM or restarting the service with `gitlab-ctl restart postgresql`), PostgreSQL automatically resumes replication, which is something you wouldn't want during an upgrade or in a planned failover scenario. ```shell gitlab-ctl geo-replication-pause ``` -**To Resume: (from secondary)** +**To Resume: (from secondary site)** ```shell gitlab-ctl geo-replication-resume @@ -273,9 +285,9 @@ For information on configuring Geo with Object storage, see [Geo with Object sto For information on using Geo in disaster recovery situations to mitigate data-loss and restore services, see [Disaster Recovery](disaster_recovery/index.md). -### Replicating the Container Registry +### Replicating the container registry -For more information on how to replicate the Container Registry, see [Container Registry for a **secondary** site](replication/container_registry.md). +For more information on how to replicate the container registry, see [Container registry for a **secondary** site](replication/container_registry.md). ### Geo secondary proxy diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 8722ab574c3..b50f86dcf47 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo configuration **(PREMIUM SELF)** @@ -217,8 +216,7 @@ In the following steps, replace `<ssh_host_key_path>` with the one you're using: ``` 1. Navigate to the Primary Node GitLab Instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Geo > Sites**. 1. Select **Add site**.  @@ -327,9 +325,8 @@ method to be enabled. This is enabled by default, but if converting an existing On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. If using Git over SSH, then: 1. Ensure "Enabled Git access protocols" is set to "Both SSH and HTTP(S)". @@ -341,9 +338,8 @@ On the **primary** site: You can sign in to the **secondary** site with the same credentials you used with the **primary** site. After you sign in: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Verify that it's correctly identified as a **secondary** Geo site, and that Geo is enabled. diff --git a/doc/administration/geo/replication/container_registry.md b/doc/administration/geo/replication/container_registry.md index 65ecba0d04a..b9bee753089 100644 --- a/doc/administration/geo/replication/container_registry.md +++ b/doc/administration/geo/replication/container_registry.md @@ -1,17 +1,16 @@ --- 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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Container Registry for a secondary site **(PREMIUM SELF)** +# Container registry for a secondary site **(PREMIUM SELF)** -You can set up a Container Registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. +You can set up a container registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. NOTE: -The Container Registry replication is used only for disaster recovery purposes. We do not recommend -pulling the Container Registry data from the secondary. For a feature proposal to implement it in the +The container registry replication is used only for disaster recovery purposes. We do not recommend +pulling the container registry data from the secondary. For a feature proposal to implement it in the future, see [Geo: Accelerate container images by serving read request from secondary site](https://gitlab.com/gitlab-org/gitlab/-/issues/365864) for details. ## Supported container registries @@ -40,7 +39,7 @@ For more information on supported registry storage drivers see Read the [Load balancing considerations](https://docs.docker.com/registry/deploying/#load-balancing-considerations) when deploying the Registry, and how to set up the storage driver for the GitLab integrated -[Container Registry](../../packages/container_registry.md#use-object-storage). +[container registry](../../packages/container_registry.md#use-object-storage). ### Registries that support OCI artifacts @@ -55,26 +54,26 @@ The following registries support OCI artifacts: For more information, see the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). -## Configure Container Registry replication +## Configure container registry replication You can enable a storage-agnostic replication so it can be used for cloud or local storage. Whenever a new image is pushed to the **primary** site, each **secondary** site pulls it to its own container repository. -To configure Container Registry replication: +To configure container registry replication: 1. Configure the [**primary** site](#configure-primary-site). 1. Configure the [**secondary** site](#configure-secondary-site). -1. Verify Container Registry [replication](#verify-replication). +1. Verify container registry [replication](#verify-replication). ### Configure **primary** site -Make sure that you have Container Registry set up and working on +Make sure that you have container registry set up and working on the **primary** site before following the next steps. -To be able to replicate new container images, the Container Registry must send notification events to the -**primary** site for every push. The token shared between the Container Registry and the web nodes on the +To be able to replicate new container images, the container registry must send notification events to the +**primary** site for every push. The token shared between the container registry and the web nodes on the **primary** is used to make communication more secure. 1. SSH into your GitLab **primary** server and login as root (for GitLab HA, you only need a Registry node): @@ -124,17 +123,17 @@ To be able to replicate new container images, the Container Registry must send n ### Configure **secondary** site -Make sure you have Container Registry set up and working on +Make sure you have container registry set up and working on the **secondary** site before following the next steps. The following steps should be done on each **secondary** site you're expecting to see the container images replicated. Because we need to allow the **secondary** site to communicate securely with -the **primary** site Container Registry, we need to have a single key +the **primary** site container registry, we need to have a single key pair for all the sites. The **secondary** site uses this key to generate a short-lived JWT that is pull-only-capable to access the -**primary** site Container Registry. +**primary** site container registry. For each application and Sidekiq node on the **secondary** site: @@ -164,11 +163,10 @@ For each application and Sidekiq node on the **secondary** site: ### Verify replication -To verify Container Registry replication is working, on the **secondary** site: +To verify container registry replication is working, on the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. The initial replication, or "backfill", is probably still in progress. You can monitor the synchronization process on each Geo site from the **primary** site's **Geo Nodes** dashboard in your browser. diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 896501128f7..634a524e6f0 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported Geo data types **(PREMIUM SELF)** @@ -190,7 +189,7 @@ successfully, you must replicate their data using some other means. |Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | GitLab-managed object storage replication (added in GitLab version) | GitLab-managed object storage verification (added in GitLab version) | Notes | |:--------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------|:---------------------------------------------------------------------------|:--------------------------------------------------------------------|:----------------------------------------------------------------|:------| |[Application data in PostgreSQL](../../postgresql/index.md) | **Yes** (10.2) | **Yes** (10.2) | Not applicable | Not applicable | | -|[Project repository](../../../user/project/repository/index.md) | **Yes** (10.2) | **Yes** (10.7) | Not applicable | Not applicable | Migrated to [self-service framework](../../../development/geo/framework.md) in 16.2. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_repository_replication`, enabled by default in (16.3).<br /><br /> All projects, including [archived projects](../../../user/project/settings/index.md#archive-a-project), are replicated. | +|[Project repository](../../../user/project/repository/index.md) | **Yes** (10.2) | **Yes** (10.7) | Not applicable | Not applicable | Migrated to [self-service framework](../../../development/geo/framework.md) in 16.2. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_repository_replication`, enabled by default in (16.3).<br /><br /> All projects, including [archived projects](../../../user/project/settings/migrate_projects.md#archive-a-project), are replicated. | |[Project wiki repository](../../../user/project/wiki/index.md) | **Yes** (10.2)<sup>2</sup> | **Yes** (10.7)<sup>2</sup> | Not applicable | Not applicable | Migrated to [self-service framework](../../../development/geo/framework.md) in 15.11. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_wiki_repository_replication`, enabled by default in (15.11). | |[Group wiki repository](../../../user/project/wiki/group.md) | [**Yes** (13.10)](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | [**Yes** (16.3)](https://gitlab.com/gitlab-org/gitlab/-/issues/323897) | Not applicable | Not applicable | Behind feature flag `geo_group_wiki_repository_replication`, enabled by default. | |[Uploads](../../uploads.md) | **Yes** (10.2) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Replication is behind the feature flag `geo_upload_replication`, enabled by default. Verification was behind the feature flag `geo_upload_verification`, removed in 14.8. | @@ -200,10 +199,10 @@ successfully, you must replicate their data using some other means. |[CI job artifacts](../../../ci/jobs/job_artifacts.md) | **Yes** (10.4) | **Yes** (14.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | 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) | [**Yes** (16.4)](object_storage.md) | 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) | [**Yes** (16.4)](object_storage.md) | 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)<sup>1</sup> | **Yes** (15.10) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | See [instructions](container_registry.md) to set up the Container Registry replication. | +|[Container registry](../../packages/container_registry.md) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | See [instructions](container_registry.md) to set up the container registry replication. | |[Terraform Module Registry](../../../user/packages/terraform_module_registry/index.md) | **Yes** (14.0) | **Yes** (14.0) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | **Yes** (16.1) | Not applicable | Not applicable | 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) | [**Yes** (16.4)](object_storage.md) | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[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) | [**Yes** (16.4)](object_storage.md) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | **Yes** (13.12) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Replication is behind the feature flag `geo_terraform_state_version_replication`, enabled by default. Verification was behind the feature flag `geo_terraform_state_version_verification`, which was removed in 14.0. | |[External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification was behind the feature flag `geo_merge_request_diff_verification`, removed in 14.7.| |[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) | Not applicable | Not applicable | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | @@ -215,6 +214,7 @@ successfully, you must replicate their data using some other means. |[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) | [**Yes** (15.7)](https://gitlab.com/groups/gitlab-org/-/epics/8833) | [**Yes** (15.7)](https://gitlab.com/groups/gitlab-org/-/epics/8833) | [**Yes** (15.7)](https://gitlab.com/groups/gitlab-org/-/epics/8833) | [**Yes** (16.4)](object_storage.md) | | |[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. | +|Packages NPM metadata cache | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/408278) | No | No | No | Not planned because it would not notably improve disaster recovery capabilities nor response times at secondary sites. | <sup>1</sup> 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 42c37a79ec2..597bb08c188 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disabling Geo **(PREMIUM SELF)** @@ -36,9 +35,8 @@ to do that. To remove the **primary** site: 1. [Remove all secondary Geo sites](remove_geo_site.md) -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. 1. Select **Remove** for the **primary** node. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 311cdeee5b9..f29d7967feb 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Frequently Asked Questions **(PREMIUM SELF)** @@ -65,9 +65,9 @@ connectivity between your sites, and your hardware. That's totally fine. We use HTTP(s) to fetch repository changes from the **primary** site to all **secondary** sites. -## Is this possible to set up a Container Registry for a **secondary** site that mirrors the one on the **primary** site? +## Is this possible to set up a container registry for a **secondary** site that mirrors the one on the **primary** site? -Yes. See [Container Registry for a **secondary** site](container_registry.md). +Yes. See [container registry for a **secondary** site](container_registry.md). ## Can you sign in to a secondary site? diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 7897635e78f..b4f4374fd9b 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 a3abc945288..6849a648991 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Location-aware Git remote URL with AWS Route53 **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 786030736f6..850ab9f0707 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo for multiple nodes **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 3b6b214d9e3..9d1cb4387a0 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with Object storage **(PREMIUM SELF)** @@ -43,9 +42,8 @@ whether they are stored on the local file system or in object storage. To enable GitLab replication: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. 1. Select **Edit** on the **secondary** site. 1. In the **Synchronization Settings** section, find the **Allow this secondary node to replicate content on Object Storage** checkbox to enable it. diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index a55c05050a0..4787b949e2e 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.md @@ -1,17 +1,15 @@ --- 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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Removing secondary Geo sites **(PREMIUM SELF)** **Secondary** sites can be removed from the Geo cluster using the Geo administration page of the **primary** site. To remove a **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. 1. For the **secondary** site you want to remove, select **Remove**. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index e099c2b2e9d..a267ac23779 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo security review (Q&A) **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/single_sign_on.md b/doc/administration/geo/replication/single_sign_on.md index 15e24cdcefb..f8ca6209524 100644 --- a/doc/administration/geo/replication/single_sign_on.md +++ b/doc/administration/geo/replication/single_sign_on.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with Single Sign On (SSO) **(PREMIUM SELF)** @@ -15,7 +14,7 @@ This documentation only discusses Geo-specific SSO considerations and configurat [Instance-wide SAML](../../../integration/saml.md) must be working on your primary Geo site. -You only configure SAML on the primary site. Configuring `gitlab_rails['omniauth_providers']` in `gitlab.rb` in a secondary site has no effect. +You only configure SAML on the primary site. Configuring `gitlab_rails['omniauth_providers']` in `gitlab.rb` in a secondary site has no effect. The secondary site authenticates against the SAML provider configured on the primary site. Depending on the [URL type](#determine-the-type-of-url-your-secondary-site-uses) of the secondary site, [additional configuration](#saml-with-separate-url-with-proxying-enabled) might be needed on the primary site. ### Determine the type of URL your secondary site uses diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index dd021695800..6e60ae34a22 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Geo **(PREMIUM SELF)** @@ -27,9 +27,8 @@ Before attempting more advanced troubleshooting: On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. We perform the following health checks on each **secondary** site to help identify if something is wrong: @@ -199,7 +198,7 @@ http://secondary.example.com/ Last status report was: 1 minute ago ``` -There are up to three statuses for each item. For example, for `Project Repositories`, you see the following lines: +Each item can have up to three statuses. For example, for `Project Repositories`, you see the following lines: ```plaintext Project Repositories: succeeded 12345 / total 12345 (100%) @@ -466,9 +465,9 @@ For more information about recommended site names in the description of the Name ### Check OS locale data compatibility -If different operating systems or different operating system versions are deployed across Geo sites, you should perform a locale data compatibility check before setting up Geo. +If different operating systems or different operating system versions are deployed across Geo sites, you **must** perform a locale data compatibility check before setting up Geo. -Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, it can cause erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723). +Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, it causes erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723). For example, Ubuntu 18.04 (and earlier) and RHEL/Centos7 (and earlier) are incompatible with their later releases. See the [PostgreSQL wiki for more details](https://wiki.postgresql.org/wiki/Locale_data_changes). @@ -493,9 +492,9 @@ or the reverse order: 1-1 ``` -If the output is identical on all hosts, then they running compatible versions of locale data. +If the output is **identical** on all hosts, then they running compatible versions of locale data and you may proceed with Geo configuration. -If the output differs on some hosts, PostgreSQL replication does not work properly: indexes are corrupted on the database replicas. You should select operating system versions that are compatible. +If the output **differs** on any hosts, PostgreSQL replication will not work properly: indexes will become corrupted on the database replicas. You **must** select operating system versions that are compatible. A full index rebuild is required if the on-disk data is transferred 'at rest' to an operating system with an incompatible locale, or through replication. @@ -682,6 +681,19 @@ In GitLab 13.4, a seed project is added when GitLab is first installed. This mak on a new Geo secondary site. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618) when checking the database. +### Message: `FATAL: could not map anonymous shared memory: Cannot allocate memory` + +If you see this message, it means that the secondary site's PostgreSQL tries to request memory that is higher than the available memory. There is an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381585) that tracks this problem. + +Example error message in Patroni logs (located at `/var/log/gitlab/patroni/current` for Linux package installations): + +```plaintext +2023-11-21_23:55:18.63727 FATAL: could not map anonymous shared memory: Cannot allocate memory +2023-11-21_23:55:18.63729 HINT: This error usually means that PostgreSQL's request for a shared memory segment exceeded available memory, swap space, or huge pages. To reduce the request size (currently 17035526144 bytes), reduce PostgreSQL's shared memory usage, perhaps by reducing shared_buffers or max_connections. +``` + +The workaround is to increase the memory available to the secondary site's PostgreSQL nodes to match the memory requirements of the primary site's PostgreSQL nodes. + ## Synchronization errors ### Reverify all uploads (or any SSF data type which is verified) @@ -726,16 +738,75 @@ If large repositories are affected by this problem, their resync may take a long time and cause significant load on your Geo sites, storage and network systems. -If you see the error message `Synchronization failed - Error syncing repository` along with `fatal: fsck error in packed object`, this indicates -a consistency check error when syncing the repository. +The following error message indicates a consistency check error when syncing the repository: + +```plaintext +Synchronization failed - Error syncing repository [..] fatal: fsck error in packed object +``` + +Several issues can trigger this error. For example, problems with email addresses: + +```plaintext +Error syncing repository: 13:fetch remote: "error: object <SHA>: badEmail: invalid author/committer line - bad email + fatal: fsck error in packed object + fatal: fetch-pack: invalid index-pack output +``` + +Another issue that can trigger this error is `object <SHA>: hasDotgit: contains '.git'`. Check the specific errors because you might have more than one problem across all +your repositories. + +A second synchronization error can also be caused by repository check issues: + +```plaintext +Error syncing repository: 13:Received RST_STREAM with error code 2. +``` + +These errors can be observed by [immediately syncing all failed repositories](#sync-all-failed-repositories-now). + +Removing the malformed objects causing consistency errors involves rewriting the repository history, which is usually not an option. + +To ignore these consistency checks, reconfigure Gitaly **on the secondary Geo sites** to ignore these `git fsck` issues. +The following configuration example: + +- [Uses the new configuration structure](../../../update/versions/gitlab_16_changes.md#gitaly-configuration-structure-change) required from GitLab 16.0. +- Ignores five common check failures. + +[The Gitaly documentation has more details](../../gitaly/configure_gitaly.md#repository-consistency-checks) +about other Git check failures and older versions of GitLab. + +```ruby +gitaly['configuration'] = { + git: { + config: [ + { key: "fsck.duplicateEntries", value: "ignore" }, + { key: "fsck.badFilemode", value: "ignore" }, + { key: "fsck.missingEmail", value: "ignore" }, + { key: "fsck.badEmail", value: "ignore" }, + { key: "fsck.hasDotgit", value: "ignore" }, + { key: "fetch.fsck.duplicateEntries", value: "ignore" }, + { key: "fetch.fsck.badFilemode", value: "ignore" }, + { key: "fetch.fsck.missingEmail", value: "ignore" }, + { key: "fetch.fsck.badEmail", value: "ignore" }, + { key: "fetch.fsck.hasDotgit", value: "ignore" }, + { key: "receive.fsck.duplicateEntries", value: "ignore" }, + { key: "receive.fsck.badFilemode", value: "ignore" }, + { key: "receive.fsck.missingEmail", value: "ignore" }, + { key: "receive.fsck.badEmail", value: "ignore" }, + { key: "receive.fsck.hasDotgit", value: "ignore" }, + ], + }, +} +``` + +GitLab 16.1 and later [include an enhancement](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5879) that might resolve some of these issues. -One example of a consistency error is: `error: object f4a87a3be694fbbd6e50a668a31a8513caeaafe3: hasDotgit: contains '.git`. +[Gitaly issue 5625](https://gitlab.com/gitlab-org/gitaly/-/issues/5625) proposes to ensure that Geo replicates repositories even if the source repository contains +problematic commits. -Removing the malformed objects causing consistency errors require rewriting the repository history, which is not always an option. However, -it's possible to override the consistency checks instead. To do that, follow -[the instructions in the Gitaly docs](../../gitaly/configure_gitaly.md#repository-consistency-checks). +#### Related error `does not appear to be a git repository` -You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file +You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages. +This error indicates that the expected Geo remote is not present in the `.git/config` file of a repository on the secondary Geo site's file system: ```json @@ -839,7 +910,7 @@ This behavior affects only the following data types through GitLab 14.6: | Data type | From version | | ------------------------ | ------------ | -| Package Registry | 13.10 | +| Package registry | 13.10 | | CI Pipeline Artifacts | 13.11 | | Terraform State Versions | 13.12 | | Infrastructure Registry (renamed to Terraform Module Registry in GitLab 15.11) | 14.0 | @@ -953,6 +1024,11 @@ The following script: - Displays the project details and the reasons for the last failure. - Attempts to resync the repository. - Reports back if a failure occurs, and why. +- Might take some time to complete. Each repository check must complete + before reporting back the result. If your session times out, take measures + to allow the process to continue running such as starting a `screen` session, + or running it using [Rails runner](../../operations/rails_console.md#using-the-rails-runner) + and `nohup`. ```ruby Geo::ProjectRegistry.sync_failed('repository').find_each do |p| @@ -1450,9 +1526,8 @@ If you have updated the value of `external_url` in `/etc/gitlab/gitlab.rb` for t In this case, make sure to update the changed URL on all your sites: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Change the URL and save the change. ### Message: `ERROR: canceling statement due to conflict with recovery` during backup @@ -1556,9 +1631,8 @@ site's URL matches its external URL. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Find the affected **secondary** site and select **Edit**. 1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb` in `external_url "https://gitlab.example.com"` on the **Rails nodes of the secondary** site. diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 3a4366cfd63..c02571e21a8 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tuning Geo **(PREMIUM SELF)** @@ -14,9 +13,8 @@ in the background. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** of the secondary site you want to tune. 1. Under **Tuning settings**, there are several variables that can be tuned to improve the performance of Geo: diff --git a/doc/administration/geo/replication/upgrading_the_geo_sites.md b/doc/administration/geo/replication/upgrading_the_geo_sites.md index 6f02ef29f99..aae35d45bde 100644 --- a/doc/administration/geo/replication/upgrading_the_geo_sites.md +++ b/doc/administration/geo/replication/upgrading_the_geo_sites.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading the Geo sites **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index cfaa02e1a17..0594709b23d 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) --> @@ -41,5 +41,5 @@ Go modules can be pulled from secondary sites, with a number of limitations: - Git configuration (using `insteadOf`) is needed to fetch data from the Geo secondary site. - For private projects, authentication details need to be specified in `~/.netrc`. -Read more in the -[working with projects `go get` documentation](../../../user/project/working_with_projects.md#fetch-go-modules-from-geo-secondary-sites). +For more information, see +[Using a project as a Go package](../../../user/project/use_project_as_go_package.md#fetch-go-modules-from-geo-secondary-sites). diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index f6572ded4a9..22bb7dd721d 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo proxying for secondary sites **(PREMIUM SELF)** @@ -115,7 +114,7 @@ for details. - Non-Rails requests are not proxied, so other services may need to use a separate, non-unified URL to ensure requests are always sent to the primary. These services include: - - GitLab Container Registry - [can be configured to use a separate domain](../../packages/container_registry.md#configure-container-registry-under-its-own-domain). + - GitLab container registry - [can be configured to use a separate domain](../../packages/container_registry.md#configure-container-registry-under-its-own-domain). - GitLab Pages - should always use a separate domain, as part of [the prerequisites for running GitLab Pages](../../pages/index.md#prerequisites). - With a unified URL, Let's Encrypt can't generate certificates unless it can reach both IPs through the same domain. 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 ae701bb8482..4ff349d8741 100644 --- a/doc/administration/geo/secondary_proxy/location_aware_external_url.md +++ b/doc/administration/geo/secondary_proxy/location_aware_external_url.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Location-aware public URL **(PREMIUM SELF)** diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 471bae72c5b..13615825a14 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo database replication **(PREMIUM SELF)** @@ -763,7 +762,7 @@ defaults default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions frontend internal-postgresql-tcp-in - bind *:5000 + bind *:5432 mode tcp option tcplog @@ -900,6 +899,10 @@ For each node running a Patroni instance on the secondary site: gitlab_rails['auto_migrate'] = false ``` + When configuring `patroni['standby_cluster']['host']` and `patroni['standby_cluster']['port']`: + - `INTERNAL_LOAD_BALANCER_PRIMARY_IP` must point to the primary internal load balancer IP. + - `INTERNAL_LOAD_BALANCER_PRIMARY_PORT` must point to the frontend port [configured for the primary Patroni cluster leader](#step-2-configure-the-internal-load-balancer-on-the-primary-site). **Do not** use the PgBouncer frontend port. + 1. Reconfigure GitLab for the changes to take effect. This step is required to bootstrap PostgreSQL users and settings. @@ -952,8 +955,7 @@ If you want to run the Geo tracking database on a single node, see [Configure th A production-ready and secure setup for the tracking PostgreSQL DB requires at least three Consul nodes: two Patroni nodes, and one PgBouncer node on the secondary site. -Because of [issue 6587](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6587), Consul can't track multiple -services, so these must be different than the nodes used for the Standby Cluster database. +Consul can track multiple services, so you can choose to reuse the nodes used for the Standby Cluster database, though the instructions below do not show how to combine configurations when reusing Consul nodes. Be sure to use [password credentials](../../postgresql/replication_and_failover.md#database-authorization-for-patroni) and other database best practices. diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 6083d7331b6..2d0e9e45197 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with external PostgreSQL instances **(PREMIUM SELF)** diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md index f59dec17f8b..1868902cfcf 100644 --- a/doc/administration/geo/setup/index.md +++ b/doc/administration/geo/setup/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Setting up Geo **(PREMIUM SELF)** @@ -33,14 +32,14 @@ If both Geo sites are based on the [1K reference architecture](../../reference_a If using external PostgreSQL services, for example Amazon RDS, follow [Set up Geo for two single-node sites (with external PostgreSQL services)](two_single_node_external_services.md). -Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the container registry might be required. ### Multi-node Geo sites If one or more of your sites is using the [2K reference architecture](../../reference_architectures/2k_users.md) or larger, see [Configure Geo for multiple nodes](../replication/multiple_servers.md). -Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the container registry might be required. ### General steps for reference @@ -50,7 +49,7 @@ Depending on your GitLab deployment, [additional configuration](#additional-conf 1. [Configure GitLab](../replication/configuration.md) to set the **primary** and **secondary** sites. 1. Follow the [Using a Geo Site](../replication/usage.md) guide. -Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the container registry might be required. ### Additional configuration @@ -59,7 +58,7 @@ Depending on how you use GitLab, the following configuration might be required: - If the **primary** site uses object storage, [configure object storage replication](../replication/object_storage.md) for the **secondary** sites. - If you use LDAP, [configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** sites. For more information, see [LDAP with Geo](../replication/single_sign_on.md#ldap). -- If you use the Container Registry, [configure the Container Registry for replication](../replication/container_registry.md) on the **primary** and **secondary** sites. +- If you use the container registry, [configure the container registry for replication](../replication/container_registry.md) on the **primary** and **secondary** sites. You should [configure unified URLs](../secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites) to use a single, unified URL for all Geo sites. diff --git a/doc/administration/geo/setup/two_single_node_external_services.md b/doc/administration/geo/setup/two_single_node_external_services.md index 405a791fedc..a77bacb0587 100644 --- a/doc/administration/geo/setup/two_single_node_external_services.md +++ b/doc/administration/geo/setup/two_single_node_external_services.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Geo for two single-node sites (with external PostgreSQL services) **(PREMIUM SELF)** @@ -38,7 +38,7 @@ Prerequisites: ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -292,7 +292,7 @@ secondary site is a read-only copy. ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<secondary_site_name_here>' ``` @@ -306,8 +306,7 @@ secondary site is a read-only copy. ``` 1. Go to the primary node GitLab instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. Select **Geo > Sites**. 1. Select **Add site**. @@ -362,8 +361,7 @@ If you convert an existing site to Geo, you should check that the clone method i On the primary site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. If you use Git over SSH: @@ -378,8 +376,7 @@ the primary site. After you sign in: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Verify that the site is correctly identified as a secondary Geo site, and that Geo is enabled. diff --git a/doc/administration/geo/setup/two_single_node_sites.md b/doc/administration/geo/setup/two_single_node_sites.md index da7ec455c6a..edcb2f467ff 100644 --- a/doc/administration/geo/setup/two_single_node_sites.md +++ b/doc/administration/geo/setup/two_single_node_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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Geo for two single-node sites **(PREMIUM SELF)** @@ -38,7 +38,7 @@ Prerequisites: ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -538,7 +538,7 @@ You must manually replicate the secret file across all of your secondary sites, ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -552,8 +552,7 @@ You must manually replicate the secret file across all of your secondary sites, ``` 1. Navigate to the primary node GitLab instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Select **Add site**. @@ -608,8 +607,7 @@ If you convert an existing site to Geo, you should check that the clone method i On the primary site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. If you use Git over SSH: @@ -624,8 +622,7 @@ the primary site. After you sign in: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Verify that the site is correctly identified as a secondary Geo site, and that Geo is enabled. diff --git a/doc/administration/geo_sites.md b/doc/administration/geo_sites.md index f0c3e24f643..fa650bade47 100644 --- a/doc/administration/geo_sites.md +++ b/doc/administration/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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo sites Admin Area **(PREMIUM SELF)** @@ -11,8 +11,7 @@ You can configure various settings for GitLab Geo sites. For more information, s On either the primary or secondary site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. ## Common settings @@ -72,8 +71,7 @@ the primary uses the secondary's internal URL to contact it directly. The internal URL defaults to external URL. To change it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Select **Edit** on the site you want to customize. 1. Edit the internal URL. diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 978ea519305..336ed743a47 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -1,5 +1,5 @@ --- -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: Tutorials --- diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 7fb241b8d1f..7ff676e3512 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Set and configure Git protocol v2" --- diff --git a/doc/administration/gitaly/concurrency_limiting.md b/doc/administration/gitaly/concurrency_limiting.md new file mode 100644 index 00000000000..321bb9efe20 --- /dev/null +++ b/doc/administration/gitaly/concurrency_limiting.md @@ -0,0 +1,244 @@ +--- +stage: Systems +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Concurrency limiting + +To avoid overwhelming the servers running Gitaly, you can limit concurrency of: + +- RPCs. +- Pack objects. + +These limits can be fixed, or set as adaptive. + +WARNING: +Enabling limits on your environment should be done with caution and only +in select circumstances, such as to protect against unexpected traffic. +When reached, limits _do_ result in disconnects that negatively impact users. +For consistent and stable performance, you should first explore other options such as +adjusting node specifications, and [reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. + +## Limit RPC concurrency + +When cloning or pulling repositories, various RPCs run in the background. In particular, the Git pack RPCs: + +- `SSHUploadPackWithSidechannel` (for Git SSH). +- `PostUploadPackWithSidechannel` (for Git HTTP). + +These RPCs can consume a large amount of resources, which can have a significant impact in situations such as: + +- Unexpectedly high traffic. +- Running against [large repositories](../../user/project/repository/managing_large_repositories.md) that don't follow best practices. + +You can limit these processes from overwhelming your Gitaly server in these scenarios using the concurrency limits in the Gitaly configuration file. For +example: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['configuration'] = { + # ... + concurrency: [ + { + rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', + max_per_repo: 20, + max_queue_wait: '1s', + max_queue_size: 10, + }, + { + rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', + max_per_repo: 20, + max_queue_wait: '1s', + max_queue_size: 10, + }, + ], +} +``` + +- `rpc` is the name of the RPC to set a concurrency limit for per repository. +- `max_per_repo` is the maximum number of in-flight RPC calls for the given RPC per repository. +- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to + be picked up by Gitaly. +- `max_queue_size` is the maximum size the concurrency queue (per RPC method) can grow to before requests are rejected by + Gitaly. + +This limits the number of in-flight RPC calls for the given RPCs. The limit is applied per +repository. In the example above: + +- Each repository served by the Gitaly server can have at most 20 simultaneous `PostUploadPackWithSidechannel` and + `SSHUploadPackWithSidechannel` RPC calls in flight. +- If another request comes in for a repository that has used up its 20 slots, that request gets + queued. +- If a request waits in the queue for more than 1 second, it is rejected with an error. +- If the queue grows beyond 10, subsequent requests are rejected with an error. + +NOTE: +When these limits are reached, users are disconnected. + +You can observe the behavior of this queue using the Gitaly logs and Prometheus. For more +information, see the [relevant documentation](monitoring.md#monitor-gitaly-concurrency-limiting). + +## Limit pack-objects concurrency + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7891) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `gitaly_pack_objects_limiting_remote_ip`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5772) in GitLab 16.0. Feature flag `gitaly_pack_objects_limiting_remote_ip` removed. + +Gitaly triggers `git-pack-objects` processes when handling both SSH and HTTPS traffic to clone or pull repositories. These processes generate a `pack-file` and can +consume a significant amount of resources, especially in situations such as unexpectedly high traffic or concurrent pulls from a large repository. On GitLab.com, we also +observe problems with clients that have slow internet connections. + +You can limit these processes from overwhelming your Gitaly server by setting pack-objects concurrency limits in the Gitaly configuration file. This setting limits the +number of in-flight pack-object processes per remote IP address. + +WARNING: +Only enable these limits on your environment with caution and only in select circumstances, such as to protect against unexpected traffic. When reached, these limits +disconnect users. For consistent and stable performance, you should first explore other options such as adjusting node specifications, and +[reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. + +Example configuration: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['pack_objects_limiting'] = { + 'max_concurrency' => 15, + 'max_queue_length' => 200, + 'max_queue_wait' => '60s', +} +``` + +- `max_concurrency` is the maximum number of in-flight pack-object processes per key. +- `max_queue_length` is the maximum size the concurrency queue (per key) can grow to before requests are rejected by Gitaly. +- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to be picked up by Gitaly. + +In the example above: + +- Each remote IP can have at most 15 simultaneous pack-object processes in flight on a Gitaly node. +- If another request comes in from an IP that has used up its 15 slots, that request gets queued. +- If a request waits in the queue for more than 1 minute, it is rejected with an error. +- If the queue grows beyond 200, subsequent requests are rejected with an error. + +When the pack-object cache is enabled, pack-objects limiting kicks in only if the cache is missed. For more, see [Pack-objects cache](configure_gitaly.md#pack-objects-cache). + +You can observe the behavior of this queue using Gitaly logs and Prometheus. For more information, see +[Monitor Gitaly pack-objects concurrency limiting](monitoring.md#monitor-gitaly-pack-objects-concurrency-limiting). + +## Adaptive concurrency limiting + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6. + +Gitaly supports two concurrency limits: + +- An [RPC concurrency limit](#limit-rpc-concurrency), which allow you to configure a maximum number of simultaneous in-flight requests for each + Gitaly RPC. The limit is scoped by RPC and repository. +- A [Pack-objects concurrency limit](#limit-pack-objects-concurrency), which restricts the number of concurrent Git data transfer request by IP. + +If this limit is exceeded, either: + +- The request is put in a queue. +- The request is rejected if the queue is full or if the request remains in the queue for too long. + +Both of these concurrency limits can be configured statically. Though static limits can yield good protection results, they have some drawbacks: + +- Static limits are not good for all usage patterns. There is no one-size-fits-all value. If the limit is too low, big repositories are + negatively impacted. If the limit is too high, the protection is essentially lost. +- It's tedious to maintain a sane value for the concurrency limit, especially when the workload of each repository changes over time. +- A request can be rejected even though the server is idle because the rate doesn't factor in the load on the server. + +You can overcome all of these drawbacks and keep the benefits of concurrency limiting by configuring adaptive concurrency limits. Adaptive +concurrency limits are optional and build on the two concurrency limiting types. It uses Additive Increase/Multiplicative Decrease (AIMD) +algorithm. Each adaptive limit: + +- Gradually increases up to a certain upper limit during typical process functioning. +- Quickly decreases when the host machine has a resource problem. + +This mechanism provides some headroom for the machine to "breathe" and speeds up current inflight requests. + + + +The adaptive limiter calibrates the limits every 30 seconds and: + +- Increases the limits by one until reaching the upper limit. +- Decreases the limits by half when the top-level cgroup has either memory usage that exceeds 90%, excluding highly-evictable page caches, + or CPU throttled for 50% or more of the observation time. + +Otherwise, the limits increase by one until reaching the upper bound. For more information about technical implementation +of this system, refer to [this blueprint](../../architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md). + +Adaptive limiting is enabled for each RPC or pack-objects cache individually. However, limits are calibrated at the same time. + +### Enable adaptiveness for RPC concurrency + +Prerequisites: + +- Because adaptive limiting depends on [control groups](configure_gitaly.md#control-groups), control groups must be enabled before using adaptive limiting. + +The following is an example to configure an adaptive limit for RPC concurrency: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['configuration'] = { + # ... + concurrency: [ + { + rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', + max_queue_wait: '1s', + max_queue_size: 10, + adaptive: true, + min_limit: 10, + initial_limit: 20, + max_limit: 40 + }, + { + rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', + max_queue_wait: '10s', + max_queue_size: 20, + adaptive: true, + min_limit: 10, + initial_limit: 50, + max_limit: 100 + }, + ], +} +``` + +In this example: + +- `adaptive` sets whether the adaptiveness is enabled. If set, the `max_per_repo` value is ignored in favor of the following configuration. +- `initial_limit` is the per-repository concurrency limit to use when Gitaly starts. +- `max_limit` is the minimum per-repository concurrency limit of the configured RPC. Gitaly increases the current limit + until it reaches this number. +- `min_limit` is the is the minimum per-repository concurrency limit of the configured RPC. When the host machine has a resource problem, + Gitaly quickly reduces the limit until reaching this value. + +For more information, see [RPC concurrency](#limit-rpc-concurrency). + +### Enable adaptiveness for pack-objects concurrency + +Prerequisites: + +- Because adaptive limiting depends on [control groups](configure_gitaly.md#control-groups), control groups must be enabled before using adaptive limiting. + +The following is an example to configure an adaptive limit for pack-objects concurrency: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['pack_objects_limiting'] = { + 'max_queue_length' => 200, + 'max_queue_wait' => '60s', + 'adaptive' => true, + 'min_limit' => 10, + 'initial_limit' => 20, + 'max_limit' => 40 +} +``` + +In this example: + +- `adaptive` sets whether the adaptiveness is enabled. If set, the value of `max_concurrency` is ignored in favor of the following configuration. +- `initial_limit` is the per-IP concurrency limit to use when Gitaly starts. +- `max_limit` is the minimum per-IP concurrency limit for pack-objects. Gitaly increases the current limit until it reaches this number. +- `min_limit` is the is the minimum per-IP concurrency limit for pack-objects. When the host machine has a resources problem, Gitaly quickly + reduces the limit until it reaches this value. + +For more information, see [pack-objects concurrency](#limit-pack-objects-concurrency). diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index 15ace9c4ed9..d89413b2cf4 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly **(FREE SELF)** @@ -25,9 +25,9 @@ Configure Gitaly in one of two ways: The following configuration options are also available: -- Enabling [TLS support](#enable-tls-support). -- Limiting [RPC concurrency](#limit-rpc-concurrency). -- Limiting [pack-objects concurrency](#limit-pack-objects-concurrency). +- Enabling [TLS support](tls_support.md). +- Limiting [RPC concurrency](concurrency_limiting.md#limit-rpc-concurrency). +- Limiting [pack-objects concurrency](concurrency_limiting.md#limit-pack-objects-concurrency). ## About the Gitaly token @@ -95,7 +95,7 @@ the default ports for HTTP and HTTPs communication. WARNING: Gitaly servers must not be exposed to the public internet as Gitaly network traffic is unencrypted by default. The use of firewall is highly recommended to restrict access to the Gitaly server. -Another option is to [use TLS](#enable-tls-support). +Another option is to [use TLS](tls_support.md). In the following sections, we describe how to configure two Gitaly servers with secret token `abc123secret`: @@ -441,22 +441,14 @@ Configure Gitaly clients in one of two ways: default: gitaly_address: tcp://gitaly1.internal:8075 gitaly_token: AUTH_TOKEN_1 - path: /some/local/path storage1: gitaly_address: tcp://gitaly1.internal:8075 gitaly_token: AUTH_TOKEN_1 - path: /some/local/path storage2: gitaly_address: tcp://gitaly2.internal:8075 gitaly_token: AUTH_TOKEN_2 - path: /some/local/path ``` - NOTE: - `/some/local/path` should be set to a local folder that exists, however no data is stored in - this folder. This requirement is scheduled to be removed when - [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. - 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Run `sudo -u git -H bundle exec rake gitlab:gitaly:check RAILS_ENV=production` to confirm the Gitaly client can connect to Gitaly servers. @@ -575,457 +567,6 @@ Disable Gitaly on a GitLab server in one of two ways: ::EndTabs -## Enable TLS support - -Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure -connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding -storage entry in the GitLab configuration. - -Gitaly provides the same server certificates as client certificates in TLS -connections to GitLab. This can be used as part of a mutual TLS authentication strategy -when combined with reverse proxies (for example, NGINX) that validate client certificate -to grant access to GitLab. - -You must supply your own certificates as this isn't provided automatically. The certificate -corresponding to each Gitaly server must be installed on that Gitaly server. - -Additionally, the certificate (or its certificate authority) must be installed on all: - -- Gitaly servers. -- Gitaly clients that communicate with it. - -If you use a load balancer, it must be able to negotiate HTTP/2 using the ALPN TLS extension. - -### 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 - -Configure Gitaly with TLS in one of two ways: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. Create certificates for Gitaly servers. -1. On the Gitaly clients, copy the certificates (or their certificate authority) into - `/etc/gitlab/trusted-certs`: - - ```shell - sudo cp cert.pem /etc/gitlab/trusted-certs/ - ``` - -1. On the Gitaly clients, edit `git_data_dirs` in `/etc/gitlab/gitlab.rb` as follows: - - ```ruby - git_data_dirs({ - 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, - 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, - 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, - }) - ``` - -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). -1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate - there: - - ```shell - sudo mkdir -p /etc/gitlab/ssl - sudo chmod 755 /etc/gitlab/ssl - sudo cp key.pem cert.pem /etc/gitlab/ssl/ - sudo chmod 644 key.pem cert.pem - ``` - -1. Copy all Gitaly server certificates (or their certificate authority) to - `/etc/gitlab/trusted-certs` on all Gitaly servers and clients - so that Gitaly servers and clients trust the certificate when calling into themselves - or other Gitaly servers: - - ```shell - sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/ - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and add: - - <!-- Updates to following example must also be made at https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab --> - - ```ruby - gitaly['configuration'] = { - # ... - tls_listen_addr: '0.0.0.0:9999', - tls: { - certificate_path: '/etc/gitlab/ssl/cert.pem', - key_path: '/etc/gitlab/ssl/key.pem', - }, - } - ``` - -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). -1. Run `sudo gitlab-rake gitlab:gitaly:check` on the Gitaly client (for example, the - Rails application) to confirm it can connect to Gitaly servers. -1. Verify Gitaly traffic is being served over TLS by - [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). -1. Optional. Improve security by: - 1. Disabling non-TLS connections by commenting out or deleting `gitaly['configuration'][:listen_addr]` in - `/etc/gitlab/gitlab.rb`. - 1. Saving the file. - 1. [Reconfiguring GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - -:::TabTitle Self-compiled (source) - -1. Create certificates for Gitaly servers. -1. On the Gitaly clients, copy the certificates into the system trusted certificates: - - ```shell - sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt - sudo update-ca-certificates - ``` - -1. On the Gitaly clients, edit `storages` in `/home/git/gitlab/config/gitlab.yml` as follows: - - ```yaml - gitlab: - repositories: - storages: - default: - gitaly_address: tls://gitaly1.internal:9999 - path: /some/local/path - storage1: - gitaly_address: tls://gitaly1.internal:9999 - path: /some/local/path - storage2: - gitaly_address: tls://gitaly2.internal:9999 - path: /some/local/path - ``` - - NOTE: - `/some/local/path` should be set to a local folder that exists, however no data is stored - in this folder. This requirement is scheduled to be removed when - [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. - -1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). -1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add: - - ```shell - export SSL_CERT_DIR=/etc/gitlab/ssl - ``` - -1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate there: - - ```shell - sudo mkdir -p /etc/gitlab/ssl - sudo chmod 755 /etc/gitlab/ssl - sudo cp key.pem cert.pem /etc/gitlab/ssl/ - sudo chmod 644 key.pem cert.pem - ``` - -1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted - certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly - servers. - - ```shell - sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt - sudo update-ca-certificates - ``` - -1. Edit `/home/git/gitaly/config.toml` and add: - - ```toml - tls_listen_addr = '0.0.0.0:9999' - - [tls] - certificate_path = '/etc/gitlab/ssl/cert.pem' - key_path = '/etc/gitlab/ssl/key.pem' - ``` - -1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). -1. Verify Gitaly traffic is being served over TLS by - [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). -1. Optional. Improve security by: - 1. Disabling non-TLS connections by commenting out or deleting `listen_addr` in - `/home/git/gitaly/config.toml`. - 1. Saving the file. - 1. [Restarting GitLab](../restart_gitlab.md#self-compiled-installations). - -::EndTabs - -#### Update the certificates - -To update the Gitaly certificates after initial configuration: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, but no configuration changes have been made to -`/etc/gitlab/gitlab.rb`, then reconfiguring GitLab doesn’t affect Gitaly. Instead, you must restart Gitaly manually for the certificates to be loaded -by the Gitaly process: - -```shell -sudo gitlab-ctl restart gitaly -``` - -If you change or update the certificates in `/etc/gitlab/trusted-certs` without making changes to the `/etc/gitlab/gitlab.rb` file, you must: - -1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) so the symlinks for the trusted certificates are updated. -1. Restart Gitaly manually for the certificates to be loaded by the Gitaly process: - - ```shell - sudo gitlab-ctl restart gitaly - ``` - -:::TabTitle Self-compiled (source) - -If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, you must -[restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. - -If you change or update the certificates in `/usr/local/share/ca-certificates`, you must: - -1. Run `sudo update-ca-certificates` to update the system's trusted store. -1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. - -::EndTabs - -### Observe type of Gitaly connections - -For information on observing the type of Gitaly connections being served, see the -[relevant documentation](monitoring.md#queries). - -## Limit RPC concurrency - -WARNING: -Enabling limits on your environment should be done with caution and only -in select circumstances, such as to protect against unexpected traffic. -When reached, limits _do_ result in disconnects that negatively impact users. -For consistent and stable performance, you should first explore other options such as -adjusting node specifications, and [reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. - -When cloning or pulling repositories, various RPCs run in the background. In particular, the Git pack RPCs: - -- `SSHUploadPackWithSidechannel` (for Git SSH). -- `PostUploadPackWithSidechannel` (for Git HTTP). - -These RPCs can consume a large amount of resources, which can have a significant impact in situations such as: - -- Unexpectedly high traffic. -- Running against [large repositories](../../user/project/repository/managing_large_repositories.md) that don't follow best practices. - -You can limit these processes from overwhelming your Gitaly server in these scenarios using the concurrency limits in the Gitaly configuration file. For -example: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['configuration'] = { - # ... - concurrency: [ - { - rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', - max_per_repo: 20, - max_queue_wait: '1s', - max_queue_size: 10, - }, - { - rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', - max_per_repo: 20, - max_queue_wait: '1s', - max_queue_size: 10, - }, - ], -} -``` - -- `rpc` is the name of the RPC to set a concurrency limit for per repository. -- `max_per_repo` is the maximum number of in-flight RPC calls for the given RPC per repository. -- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to - be picked up by Gitaly. -- `max_queue_size` is the maximum size the concurrency queue (per RPC method) can grow to before requests are rejected by - Gitaly. - -This limits the number of in-flight RPC calls for the given RPCs. The limit is applied per -repository. In the example above: - -- Each repository served by the Gitaly server can have at most 20 simultaneous `PostUploadPackWithSidechannel` and - `SSHUploadPackWithSidechannel` RPC calls in flight. -- If another request comes in for a repository that has used up its 20 slots, that request gets - queued. -- If a request waits in the queue for more than 1 second, it is rejected with an error. -- If the queue grows beyond 10, subsequent requests are rejected with an error. - -NOTE: -When these limits are reached, users are disconnected. - -You can observe the behavior of this queue using the Gitaly logs and Prometheus. For more -information, see the [relevant documentation](monitoring.md#monitor-gitaly-concurrency-limiting). - -## Limit pack-objects concurrency - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7891) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `gitaly_pack_objects_limiting_remote_ip`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5772) in GitLab 16.0. Feature flag `gitaly_pack_objects_limiting_remote_ip` removed. - -Gitaly triggers `git-pack-objects` processes when handling both SSH and HTTPS traffic to clone or pull repositories. These processes generate a `pack-file` and can -consume a significant amount of resources, especially in situations such as unexpectedly high traffic or concurrent pulls from a large repository. On GitLab.com, we also -observe problems with clients that have slow internet connections. - -You can limit these processes from overwhelming your Gitaly server by setting pack-objects concurrency limits in the Gitaly configuration file. This setting limits the -number of in-flight pack-object processes per remote IP address. - -WARNING: -Only enable these limits on your environment with caution and only in select circumstances, such as to protect against unexpected traffic. When reached, these limits -disconnect users. For consistent and stable performance, you should first explore other options such as adjusting node specifications, and -[reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. - -Example configuration: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['pack_objects_limiting'] = { - 'max_concurrency' => 15, - 'max_queue_length' => 200, - 'max_queue_wait' => '60s', -} -``` - -- `max_concurrency` is the maximum number of in-flight pack-object processes per key. -- `max_queue_length` is the maximum size the concurrency queue (per key) can grow to before requests are rejected by Gitaly. -- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to be picked up by Gitaly. - -In the example above: - -- Each remote IP can have at most 15 simultaneous pack-object processes in flight on a Gitaly node. -- If another request comes in from an IP that has used up its 15 slots, that request gets queued. -- If a request waits in the queue for more than 1 minute, it is rejected with an error. -- If the queue grows beyond 200, subsequent requests are rejected with an error. - -When the pack-object cache is enabled, pack-objects limiting kicks in only if the cache is missed. For more, see [Pack-objects cache](#pack-objects-cache). - -You can observe the behavior of this queue using Gitaly logs and Prometheus. For more information, see -[Monitor Gitaly pack-objects concurrency limiting](monitoring.md#monitor-gitaly-pack-objects-concurrency-limiting). - -## Adaptive concurrency limiting - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6. - -Gitaly supports two concurrency limits: - -- An [RPC concurrency limit](#limit-rpc-concurrency), which allow you to configure a maximum number of simultaneous in-flight requests for each - Gitaly RPC. The limit is scoped by RPC and repository. -- A [Pack-objects concurrency limit](#limit-pack-objects-concurrency), which restricts the number of concurrent Git data transfer request by IP. - -If this limit is exceeded, either: - -- The request is put in a queue. -- The request is rejected if the queue is full or if the request remains in the queue for too long. - -Both of these concurrency limits can be configured statically. Though static limits can yield good protection results, they have some drawbacks: - -- Static limits are not good for all usage patterns. There is no one-size-fits-all value. If the limit is too low, big repositories are - negatively impacted. If the limit is too high, the protection is essentially lost. -- It's tedious to maintain a sane value for the concurrency limit, especially when the workload of each repository changes over time. -- A request can be rejected even though the server is idle because the rate doesn't factor in the load on the server. - -You can overcome all of these drawbacks and keep the benefits of concurrency limiting by configuring adaptive concurrency limits. Adaptive -concurrency limits are optional and build on the two concurrency limiting types. It uses Additive Increase/Multiplicative Decrease (AIMD) -algorithm. Each adaptive limit: - -- Gradually increases up to a certain upper limit during typical process functioning. -- Quickly decreases when the host machine has a resource problem. - -This mechanism provides some headroom for the machine to "breathe" and speeds up current inflight requests. - - - -The adaptive limiter calibrates the limits every 30 seconds and: - -- Increases the limits by one until reaching the upper limit. -- Decreases the limits by half when the top-level cgroup has either memory usage that exceeds 90%, excluding highly-evictable page caches, - or CPU throttled for 50% or more of the observation time. - -Otherwise, the limits increase by one until reaching the upper bound. For more information about technical implementation -of this system, please refer to [this blueprint](../../architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md). - -Adaptive limiting is enabled for each RPC or pack-objects cache individually. However, limits are calibrated at the same time. - -### Enable adaptiveness for RPC concurrency - -Prerequisites: - -- Because adaptive limiting depends on [control groups](#control-groups), control groups must be enabled before using adaptive limiting. - -The following is an example to configure an adaptive limit for RPC concurrency: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['configuration'] = { - # ... - concurrency: [ - { - rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', - max_queue_wait: '1s', - max_queue_size: 10, - adaptive: true, - min_limit: 10, - initial_limit: 20, - max_limit: 40 - }, - { - rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', - max_queue_wait: '10s', - max_queue_size: 20, - adaptive: true, - min_limit: 10, - initial_limit: 50, - max_limit: 100 - }, - ], -} -``` - -In this example: - -- `adaptive` sets whether the adaptiveness is enabled. If set, the `max_per_repo` value is ignored in favor of the following configuration. -- `initial_limit` is the per-repository concurrency limit to use when Gitaly starts. -- `max_limit` is the minimum per-repository concurrency limit of the configured RPC. Gitaly increases the current limit - until it reaches this number. -- `min_limit` is the is the minimum per-repository concurrency limit of the configured RPC. When the host machine has a resource problem, - Gitaly quickly reduces the limit until reaching this value. - -For more information, see [RPC concurrency](#limit-rpc-concurrency). - -### Enable adaptiveness for pack-objects concurrency - -Prerequisites: - -- Because adaptive limiting depends on [control groups](#control-groups), control groups must be enabled before using adaptive limiting. - -The following is an example to configure an adaptive limit for pack-objects concurrency: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['pack_objects_limiting'] = { - 'max_queue_length' => 200, - 'max_queue_wait' => '60s', - 'adaptive' => true, - 'min_limit' => 10, - 'initial_limit' => 20, - 'max_limit' => 40 -} -``` - -In this example: - -- `adaptive` sets whether the adaptiveness is enabled. If set, the value of `max_concurrency` is ignored in favor of the following configuration. -- `initial_limit` is the per-IP concurrency limit to use when Gitaly starts. -- `max_limit` is the minimum per-IP concurrency limit for pack-objects. Gitaly increases the current limit until it reaches this number. -- `min_limit` is the is the minimum per-IP concurrency limit for pack-objects. When the host machine has a resources problem, Gitaly quickly - reduces the limit until it reaches this value. - -For more information, see [pack-objects concurrency](#limit-pack-objects-concurrency). - ## Control groups WARNING: @@ -1430,7 +971,7 @@ By default, the cache storage directory is set to a subdirectory of the first Gi defined in the configuration file. Multiple Gitaly processes can use the same directory for cache storage. Each Gitaly process -uses a unique random string as part of the cache filenames it creates. This means: +uses a unique random string as part of the cache file names it creates. This means: - They do not collide. - They do not reuse another process's files. @@ -1708,8 +1249,15 @@ By default, Gitaly doesn't sign commits made using GitLab UI. For example, commi - Web IDE. - Merge requests. -You can configure Gitaly to sign commits made with the GitLab UI. The commits show as unverified and signed by an unknown -user. Support for improvements is proposed in [issue 19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185). +You can configure Gitaly to sign commits made with the GitLab UI. + +By default, Gitaly sets the author of a commit as the committer. In this case, +it is harder to [Verify commits locally](../../user/project/repository/signed_commits/ssh.md#verify-commits-locally) +because the signature belongs to neither the author nor the committer of the commit. + +You can configure Gitaly to reflect that a commit has been committed by your instance by +setting `committer_email` and `committer_name`. For example, on GitLab.com these configuration options are +set to `noreply@gitlab.com` and `GitLab`. Configure Gitaly to sign commits made with the GitLab UI in one of two ways: @@ -1740,7 +1288,10 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways: # ... git: { # ... + committer_name: 'Your Instance', + committer_email: 'noreply@yourinstance.com', signing_key: '/etc/gitlab/gitaly/signing_key.gpg', + # ... }, } ``` @@ -1769,6 +1320,8 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways: ```toml [git] + committer_name = "Your Instance" + committer_email = "noreply@yourinstance.com" signing_key = "/etc/gitlab/gitaly/signing_key.gpg" ``` @@ -2001,50 +1554,3 @@ go_cloud_url = "s3://gitaly-backups?region=minio&endpoint=my.minio.local:8080&di ``` ::EndTabs - -## Configure negotiation timeouts - -> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5574) in GitLab 16.5. - -Gitaly supports configurable negotiation timeouts. - -Negotiation timeouts can be configured for the `git-upload-pack(1)` and `git-upload-archive(1)` -operations, which are invoked by a Gitaly node when you execute the `git fetch` and -`git archive --remote` commands respectively. You might need to increase the negotiation timeout: - -- For particularly large repositories. -- When performing these commands in parallel. - -These timeouts affect only the [negotiation phase](https://git-scm.com/docs/pack-protocol/2.2.3#_packfile_negotiation) of -remote Git operations, not the entire transfer. - -Valid values for timeouts follow the format of [`ParseDuration`](https://pkg.go.dev/time#ParseDuration) in Go. - -How you configure negotiation timeouts depends on the type of installation you have: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -Edit `/etc/gitlab/gitlab.rb`: - -```ruby -gitaly['configuration'] = { - timeout: { - upload_pack_negotiation: '10m', # 10 minutes - upload_archive_negotiation: '20m', # 20 minutes - } -} -``` - -:::TabTitle Self-compiled (source) - -Edit `/home/git/gitaly/config.toml`: - -```toml -[timeout] -upload_pack_negotiation = "10m" -upload_archive_negotiation = "20m" -``` - -::EndTabs diff --git a/doc/administration/gitaly/gitaly_geo_capabilities.md b/doc/administration/gitaly/gitaly_geo_capabilities.md index a98477318f2..7fee435ee36 100644 --- a/doc/administration/gitaly/gitaly_geo_capabilities.md +++ b/doc/administration/gitaly/gitaly_geo_capabilities.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly and Geo capabilities diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 6784ff4d970..4744959ce13 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly and Gitaly Cluster **(FREE SELF)** @@ -171,6 +171,17 @@ Gitaly comes pre-configured with a Linux package installation, which is a config GitLab installations for more than 2000 active users performing daily Git write operation may be best suited by using Gitaly Cluster. +### Gitaly CLI + +The `gitaly` command is a command-line interface that provides additional subcommands for Gitaly administrators. For example, +the Gitaly CLI is used to: + +- [Configure custom Git hooks](../server_hooks.md) for a repository. +- Validate Gitaly configuration files. +- Verify the internal Gitaly API is accessible. + +For more information on the other subcommands, run `gitaly --help`. + ### Backing up repositories When backing up or syncing repositories using tools other than GitLab, you must [prevent writes](../../administration/backup_restore/backup_gitlab.md#prevent-writes-and-copy-the-git-repository-data) diff --git a/doc/administration/gitaly/monitoring.md b/doc/administration/gitaly/monitoring.md index 5d8de42666b..83d843971d7 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring Gitaly and Gitaly Cluster @@ -31,7 +31,7 @@ of requests dropped due to request limiting. The `reason` label indicates why a ## Monitor Gitaly concurrency limiting -You can observe specific behavior of [concurrency-queued requests](configure_gitaly.md#limit-rpc-concurrency) using Gitaly logs and Prometheus. +You can observe specific behavior of [concurrency-queued requests](concurrency_limiting.md#limit-rpc-concurrency) using Gitaly logs and Prometheus. In the [Gitaly logs](../logs/index.md#gitaly-logs), you can identify logs related to the pack-objects concurrency limiting with entries such as: @@ -62,7 +62,7 @@ In Prometheus, look for the following metrics: ## Monitor Gitaly pack-objects concurrency limiting -You can observe specific behavior of [pack-objects limiting](configure_gitaly.md#limit-pack-objects-concurrency) using Gitaly logs and Prometheus. +You can observe specific behavior of [pack-objects limiting](concurrency_limiting.md#limit-pack-objects-concurrency) using Gitaly logs and Prometheus. In the [Gitaly logs](../logs/index.md#gitaly-logs), you can identify logs related to the pack-objects concurrency limiting with entries such as: @@ -94,7 +94,7 @@ In Prometheus, look for the following metrics: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6. -You can observe specific behavior of [adaptive concurrency limiting](configure_gitaly.md#adaptive-concurrency-limiting) using Gitaly logs and Prometheus. +You can observe specific behavior of [adaptive concurrency limiting](concurrency_limiting.md#adaptive-concurrency-limiting) using Gitaly logs and Prometheus. In the [Gitaly logs](../logs/index.md#gitaly-logs), you can identify logs related to the adaptive concurrency limiting when the current limits are adjusted. You can filter the content of the logs (`msg`) for "Multiplicative decrease" and "Additive increase" messages. @@ -176,12 +176,26 @@ gitaly_streamcache_filestore_removed_total{dir="/var/opt/gitlab/git-data/reposit gitaly_streamcache_index_entries{dir="/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache"} 1 ``` +## Monitor Gitaly server-side backups + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5358) in GitLab 16.7. + +Monitor [server-side repository backups](configure_gitaly.md#configure-server-side-backups) with the following metrics: + +- `gitaly_backup_latency_seconds`, a histogram measuring the amount of time in seconds that each phase of a server-side + backup takes. The different phases are `refs`, `bundle`, and `custom_hooks` and represent the type of data being + processed at each stage. +- `gitaly_backup_bundle_bytes`, a histogram measuring the upload data rate of Git bundles being pushed to object + storage by the Gitaly backup service. + +Use these metrics especially if your GitLab instance contains large repositories. + ## Queries The following are some queries for monitoring Gitaly: - Use the following Prometheus query to observe the - [type of connections](configure_gitaly.md#enable-tls-support) Gitaly is serving a production + [type of connections](tls_support.md) Gitaly is serving a production environment: ```prometheus @@ -189,7 +203,7 @@ The following are some queries for monitoring Gitaly: ``` - Use the following Prometheus query to monitor the - [authentication behavior](configure_gitaly.md#observe-type-of-gitaly-connections) of your GitLab + [authentication behavior](tls_support.md#observe-type-of-gitaly-connections) of your GitLab installation: ```prometheus diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 0297f295e6f..66e220dacc2 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly Cluster **(FREE SELF)** @@ -50,7 +50,7 @@ default value. The default value depends on the GitLab version. Network latency for Gitaly Cluster should ideally be measurable in single-digit milliseconds. Latency is particularly important for: -- Gitaly node health checks. Nodes must be able to respond 1 second or faster. +- Gitaly node health checks. Nodes must be able to respond within 1 second. - Reference transactions that enforce [strong consistency](index.md#strong-consistency). Lower latencies mean Gitaly nodes can agree on changes faster. @@ -278,6 +278,7 @@ praefect['configuration'] = { database: { # ... host: POSTGRESQL_HOST, + user: 'praefect', port: 5432, password: PRAEFECT_SQL_PASSWORD, dbname: 'praefect_production', @@ -725,7 +726,7 @@ Updates to example must be made at: Praefect supports TLS encryption. To communicate with a Praefect instance that listens for secure connections, you must: -- Ensure Gitaly is [configured for TLS](configure_gitaly.md#enable-tls-support) and use a `tls://` URL scheme in the `gitaly_address` +- Ensure Gitaly is [configured for TLS](tls_support.md) and use a `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. - Bring your own certificates because this isn't provided automatically. The certificate corresponding to each Praefect server must be installed on that Praefect server. @@ -739,7 +740,7 @@ Note the following: - The certificate must specify the address you use to access the Praefect server. You must add the hostname or IP address as a Subject Alternative Name to the certificate. - When running Praefect sub-commands such as `dial-nodes` and `list-untracked-repositories` from the command line with - [Gitaly TLS enabled](configure_gitaly.md#enable-tls-support), you must set the `SSL_CERT_DIR` or `SSL_CERT_FILE` + [Gitaly TLS enabled](tls_support.md), you must set the `SSL_CERT_DIR` or `SSL_CERT_FILE` environment variable so that the Gitaly certificate is trusted. For example: ```shell @@ -843,14 +844,8 @@ For self-compiled installations: storages: default: gitaly_address: tls://PRAEFECT_LOADBALANCER_HOST:3305 - path: /some/local/path ``` - NOTE: - `/some/local/path` should be set to a local folder that exists, however no - data is stored in this folder. This requirement is scheduled to be removed when - [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. - 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Copy all Praefect server certificates, or their certificate authority, to the system trusted certificates on each Gitaly server so the Praefect server trusts the @@ -980,14 +975,8 @@ with Praefect service discovery address, such as `praefect.service.consul`. storages: default: gitaly_address: dns:PRAEFECT_SERVICE_DISCOVERY_ADDRESS:2305 - path: /some/local/path ``` - NOTE: - `/some/local/path` should be set to a local folder that exists, however no - data is stored in this folder. [Issue 375254](https://gitlab.com/gitlab-org/gitlab/-/issues/375254) - proposes to remove this requirement. - 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -1337,8 +1326,7 @@ Particular attention should be shown to: 1. Check that the Praefect storage is configured to store new repositories: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand the **Repository storage** section. diff --git a/doc/administration/gitaly/recovery.md b/doc/administration/gitaly/recovery.md index 6779823c941..78e7cc6995d 100644 --- a/doc/administration/gitaly/recovery.md +++ b/doc/administration/gitaly/recovery.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly Cluster recovery options and tools diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 5b26c93cea8..946be6c8af3 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly reference **(FREE SELF)** @@ -89,7 +89,7 @@ certificate_path = '/home/git/cert.cert' key_path = '/home/git/key.pem' ``` -[Read more](configure_gitaly.md#enable-tls-support) about TLS in Gitaly. +[Read more](tls_support.md) about TLS in Gitaly. ### Storage diff --git a/doc/administration/gitaly/tls_support.md b/doc/administration/gitaly/tls_support.md new file mode 100644 index 00000000000..90a1a6bd2fe --- /dev/null +++ b/doc/administration/gitaly/tls_support.md @@ -0,0 +1,228 @@ +--- +stage: Systems +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Gitaly TLS support + +Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure +connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding +storage entry in the GitLab configuration. + +Gitaly provides the same server certificates as client certificates in TLS +connections to GitLab. This can be used as part of a mutual TLS authentication strategy +when combined with reverse proxies (for example, NGINX) that validate client certificate +to grant access to GitLab. + +You must supply your own certificates as this isn't provided automatically. The certificate +corresponding to each Gitaly server must be installed on that Gitaly server. + +Additionally, the certificate (or its certificate authority) must be installed on all: + +- Gitaly servers. +- Gitaly clients that communicate with it. + +If you use a load balancer, it must be able to negotiate HTTP/2 using the ALPN TLS extension. + +## 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 + +[Configure Gitaly](configure_gitaly.md) before configuring TLS support. + +The process for configuring TLS support depends on your installation type. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Create certificates for Gitaly servers. +1. On the Gitaly clients, copy the certificates (or their certificate authority) into + `/etc/gitlab/trusted-certs`: + + ```shell + sudo cp cert.pem /etc/gitlab/trusted-certs/ + ``` + +1. On the Gitaly clients, edit `git_data_dirs` in `/etc/gitlab/gitlab.rb` as follows: + + ```ruby + git_data_dirs({ + 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, + 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, + 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, + }) + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate + there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + +1. Copy all Gitaly server certificates (or their certificate authority) to + `/etc/gitlab/trusted-certs` on all Gitaly servers and clients + so that Gitaly servers and clients trust the certificate when calling into themselves + or other Gitaly servers: + + ```shell + sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/ + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add: + + <!-- Updates to following example must also be made at https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab --> + + ```ruby + gitaly['configuration'] = { + # ... + tls_listen_addr: '0.0.0.0:9999', + tls: { + certificate_path: '/etc/gitlab/ssl/cert.pem', + key_path: '/etc/gitlab/ssl/key.pem', + }, + } + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +1. Run `sudo gitlab-rake gitlab:gitaly:check` on the Gitaly client (for example, the + Rails application) to confirm it can connect to Gitaly servers. +1. Verify Gitaly traffic is being served over TLS by + [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). +1. Optional. Improve security by: + 1. Disabling non-TLS connections by commenting out or deleting `gitaly['configuration'][:listen_addr]` in + `/etc/gitlab/gitlab.rb`. + 1. Saving the file. + 1. [Reconfiguring GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + +:::TabTitle Self-compiled (source) + +1. Create certificates for Gitaly servers. +1. On the Gitaly clients, copy the certificates into the system trusted certificates: + + ```shell + sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt + sudo update-ca-certificates + ``` + +1. On the Gitaly clients, edit `storages` in `/home/git/gitlab/config/gitlab.yml` as follows: + + ```yaml + gitlab: + repositories: + storages: + default: + gitaly_address: tls://gitaly1.internal:9999 + path: /some/local/path + storage1: + gitaly_address: tls://gitaly1.internal:9999 + path: /some/local/path + storage2: + gitaly_address: tls://gitaly2.internal:9999 + path: /some/local/path + ``` + + NOTE: + `/some/local/path` should be set to a local folder that exists, however no data is stored + in this folder. This requirement is scheduled to be removed when + [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. + +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). +1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add: + + ```shell + export SSL_CERT_DIR=/etc/gitlab/ssl + ``` + +1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + +1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted + certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly + servers. + + ```shell + sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt + sudo update-ca-certificates + ``` + +1. Edit `/home/git/gitaly/config.toml` and add: + + ```toml + tls_listen_addr = '0.0.0.0:9999' + + [tls] + certificate_path = '/etc/gitlab/ssl/cert.pem' + key_path = '/etc/gitlab/ssl/key.pem' + ``` + +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). +1. Verify Gitaly traffic is being served over TLS by + [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). +1. Optional. Improve security by: + 1. Disabling non-TLS connections by commenting out or deleting `listen_addr` in + `/home/git/gitaly/config.toml`. + 1. Saving the file. + 1. [Restarting GitLab](../restart_gitlab.md#self-compiled-installations). + +::EndTabs + +### Update the certificates + +To update the Gitaly certificates after initial configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, but no configuration changes have been made to +`/etc/gitlab/gitlab.rb`, then reconfiguring GitLab doesn’t affect Gitaly. Instead, you must restart Gitaly manually for the certificates to be loaded +by the Gitaly process: + +```shell +sudo gitlab-ctl restart gitaly +``` + +If you change or update the certificates in `/etc/gitlab/trusted-certs` without making changes to the `/etc/gitlab/gitlab.rb` file, you must: + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) so the symlinks for the trusted certificates are updated. +1. Restart Gitaly manually for the certificates to be loaded by the Gitaly process: + + ```shell + sudo gitlab-ctl restart gitaly + ``` + +:::TabTitle Self-compiled (source) + +If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, you must +[restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. + +If you change or update the certificates in `/usr/local/share/ca-certificates`, you must: + +1. Run `sudo update-ca-certificates` to update the system's trusted store. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. + +::EndTabs + +## Observe type of Gitaly connections + +For information on observing the type of Gitaly connections being served, see the +[relevant documentation](monitoring.md#queries). diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 17687cbb181..7d0255a3efb 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Gitaly and Gitaly Cluster **(FREE SELF)** @@ -20,9 +20,8 @@ and our advice on [parsing the `gitaly/current` file](../logs/log_parsing.md#par When using standalone Gitaly servers, you must make sure they are the same version as GitLab to ensure full compatibility: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Gitaly Servers**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Gitaly Servers**. 1. Confirm all Gitaly servers indicate that they are up to date. ### Find storage resource details @@ -89,7 +88,7 @@ Check whether `Verify return code` field indicates a [known Linux package installation configuration problem](https://docs.gitlab.com/omnibus/settings/ssl/index.html). If `openssl` succeeds but `gitlab-rake gitlab:gitaly:check` fails, -check [certificate requirements](configure_gitaly.md#certificate-requirements) for Gitaly. +check [certificate requirements](tls_support.md#certificate-requirements) for Gitaly. ### Server side gRPC logs @@ -389,7 +388,7 @@ One way to resolve this is to make sure the entry is correct for the GitLab inte ### Changes (diffs) don't load for new merge requests when using Gitaly TLS -After enabling [Gitaly with TLS](configure_gitaly.md#enable-tls-support), changes (diffs) for new merge requests are not generated +After enabling [Gitaly with TLS](tls_support.md), changes (diffs) for new merge requests are not generated and you see the following message in GitLab: ```plaintext @@ -424,7 +423,7 @@ and: 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) so the certificates are symlinked 1. Restart Gitaly manually `sudo gitlab-ctl restart gitaly` for the certificates to be loaded by the Gitaly process. -## Gitaly fails to fork processes stored on `noexec` file systems +### Gitaly fails to fork processes stored on `noexec` file systems Because of changes [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5999) in GitLab 14.10, applying the `noexec` option to a mount point (for example, `/var`) causes Gitaly to throw `permission denied` errors related to forking processes. For example: @@ -577,7 +576,7 @@ To determine the primary node of a repository: Praefect node: ```shell - curl localhost:9652/metrics | grep gitaly_praefect_primaries` + curl localhost:9652/metrics | grep gitaly_praefect_primaries ``` ### View repository metadata @@ -684,8 +683,8 @@ The documented examples specify `-virtual-storage default`. Check the Praefect s ### Check that repositories are in sync Is [some cases](index.md#known-issues) the Praefect database can get out of sync with the underlying Gitaly nodes. To check that -a given repository is fully synced on all nodes, run the [`gitlab:praefect:replicas` Rake task](../raketasks/praefect.md#replica-checksums) -that checksums the repository on all Gitaly nodes. +a given repository is fully synced on all nodes, run the [`gitlab:praefect:replicas` Rake task](../raketasks/praefect.md#replica-checksums) on your Rails node. +This Rake task checksums the repository on all Gitaly nodes. The [Praefect `dataloss`](recovery.md#check-for-data-loss) command only checks the state of the repository in the Praefect database, and cannot be relied to detect sync problems in this scenario. diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index f4815e0f04f..7ee29035de4 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Housekeeping **(FREE SELF)** @@ -76,9 +76,8 @@ frequently. You can change how often Gitaly is asked to optimize a repository. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Repository maintenance**. 1. In the **Housekeeping** section, configure the housekeeping options. 1. Select **Save changes**. @@ -110,7 +109,7 @@ housekeeping tasks. The manual trigger can be useful when either: To trigger housekeeping tasks manually: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Run housekeeping**. @@ -137,7 +136,7 @@ reduce the likelihood of such race conditions. To trigger a manual prune of unreachable objects: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Run housekeeping**. 1. Wait 30 minutes for the operation to complete. diff --git a/doc/administration/img/email1.png b/doc/administration/img/email1.png Binary files differdeleted file mode 100644 index e79ccc3e9a9..00000000000 --- a/doc/administration/img/email1.png +++ /dev/null diff --git a/doc/administration/img/email2.png b/doc/administration/img/email2.png Binary files differdeleted file mode 100644 index d073c0e42da..00000000000 --- a/doc/administration/img/email2.png +++ /dev/null diff --git a/doc/administration/inactive_project_deletion.md b/doc/administration/inactive_project_deletion.md index 7ccd3455011..3c340448cee 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Inactive project deletion **(FREE SELF)** @@ -23,9 +23,8 @@ For the default setting on GitLab.com, see the [GitLab.com settings page](../use To configure deletion of inactive projects: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Repository maintenance**. 1. In the **Inactive project deletion** section, select **Delete inactive projects**. 1. Configure the settings. @@ -35,7 +34,7 @@ To configure deletion of inactive projects: Inactive projects that meet the criteria are scheduled for deletion and a warning email is sent. If the projects remain inactive, they are deleted after the specified duration. These projects are deleted even if -[the project is archived](../user/project/settings/index.md#archive-a-project). +[the project is archived](../user/project/settings/migrate_projects.md#archive-a-project). ### Configuration example diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 33afaf19220..2d2d9d34019 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incoming email **(FREE SELF)** @@ -995,3 +995,35 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre ``` ::EndTabs + +## Troubleshooting + +### Email ingestion doesn't work in 16.6.0 + +GitLab self-managed `16.6.0` introduced a regression that prevents `mail_room` (email ingestion) from starting. +Service Desk and other reply-by-email features don't work. +[Issue 432257](https://gitlab.com/gitlab-org/gitlab/-/issues/432257) tracks fixing this problem. + +The workaround is to run the following commands in your GitLab installation +to patch the affected files: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +:::TabTitle Docker + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +cd /opt/gitlab/embedded/service/gitlab-rails +patch -p1 < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +::EndTabs diff --git a/doc/administration/index.md b/doc/administration/index.md index ded6eabdba7..fcda1c4b413 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/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index d5855e3c832..259a0c961d2 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab application limits **(FREE SELF)** @@ -21,7 +20,7 @@ Depending on which limits you have configured, you can see: - SSH host keys information - CI/CD limits - GitLab Pages limits -- Package Registry limits +- Package registry limits - Rate limits - Size limits @@ -88,10 +87,10 @@ Read more about [protected path rate limits](settings/protected_paths.md). - **Default rate limit**: After 10 requests, the client must wait 60 seconds before trying again. -### Package Registry +### Package registry This setting limits the request rate on the Packages API per user or IP. For more information, see -[Package Registry Rate Limits](settings/package_registry_rate_limits.md). +[package registry rate limits](settings/package_registry_rate_limits.md). - **Default rate limit**: Disabled by default. @@ -202,7 +201,7 @@ Read more about [pipeline creation rate limits](settings/rate_limit_on_pipelines Clone traffic can put a large strain on your Gitaly service. To prevent such workloads from overwhelming your Gitaly server, you can set concurrency limits in the Gitaly configuration file. -Read more about [Gitaly concurrency limits](gitaly/configure_gitaly.md#limit-rpc-concurrency). +Read more about [Gitaly concurrency limits](gitaly/concurrency_limiting.md#limit-rpc-concurrency). - **Default rate limit**: Disabled. @@ -436,7 +435,7 @@ You can change the maximum time a job can run before it times out: - At the project-level in the [project's CI/CD settings](../ci/pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) for a given project. This limit must be between 10 minutes and 1 month. -- At the [runner level](../ci/runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +- At the [runner level](../ci/runners/configure_runners.md#set-the-maximum-job-timeout). This limit must be 10 minutes or longer. ### Maximum number of deployment jobs in a pipeline @@ -961,7 +960,7 @@ Reports that go over the 20 MB limit aren't loaded. Affected reports: ### Maximum file size indexed You can set a limit on the content of repository files that are indexed in -Elasticsearch. Any files larger than this limit only index the filename. +Elasticsearch. Any files larger than this limit only index the file name. The file content is neither indexed nor searchable. Setting a limit helps reduce the memory usage of the indexing processes and @@ -1052,11 +1051,11 @@ individual push events or a bulk push event are created. More information can be found in the [Push event activities limit and bulk push events documentation](settings/push_event_activities_limit.md). -## Package Registry Limits +## Package registry limits -### File Size Limits +### File size limits -The default maximum file size for a package that's uploaded to the [GitLab Package Registry](../user/packages/package_registry/index.md) varies by format: +The default maximum file size for a package that's uploaded to the [GitLab package registry](../user/packages/package_registry/index.md) varies by format: - Conan: 3 GB - Generic: 5 GB @@ -1105,7 +1104,7 @@ Set the limit to `0` to allow any file size. ### Package versions returned -When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 versions. +When asking for versions of a given NuGet package name, the GitLab package registry returns a maximum of 300 versions. ## Dependency Proxy Limits @@ -1134,7 +1133,7 @@ In addition to application-based limits, GitLab.com is configured to use Cloudfl ## Container Repository tag deletion limit -Container repository tags are in the Container Registry and, as such, each tag deletion triggers network requests to the Container Registry. Because of this, we limit the number of tags that a single API call can delete to 20. +Container repository tags are in the container registry and, as such, each tag deletion triggers network requests to the container registry. Because of this, we limit the number of tags that a single API call can delete to 20. ## Project-level Secure Files API limits diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 6a2ead82538..a33bf0f70b1 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance review **(FREE SELF)** diff --git a/doc/administration/integration/diagrams_net.md b/doc/administration/integration/diagrams_net.md index 13be572d524..42286428bb1 100644 --- a/doc/administration/integration/diagrams_net.md +++ b/doc/administration/integration/diagrams_net.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Diagrams.net **(FREE SELF)** @@ -46,9 +45,8 @@ For more information, see [Run your own diagrams.net server with Docker](https:/ ## Enable Diagrams.net integration 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Diagrams.net**. 1. Select the **Enable Diagrams.net** checkbox. 1. Enter the Diagrams.net URL. To connect to: diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index 926833cfa1a..b3c55e6f772 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kroki **(FREE SELF)** @@ -61,8 +61,7 @@ read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images You need to enable Kroki integration from Settings under Admin Area. To do that, sign in with an administrator account and follow these steps: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Go to **Settings > General**. 1. Expand the **Kroki** section. 1. Select **Enable Kroki** checkbox. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md index 4fe846e99a6..a4e8c826ef7 100644 --- a/doc/administration/integration/mailgun.md +++ b/doc/administration/integration/mailgun.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mailgun **(FREE SELF)** @@ -43,8 +42,7 @@ After configuring your Mailgun domain for the webhook endpoints, you're ready to enable the Mailgun integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. 1. Select the **Enable Mailgun** checkbox. 1. Enter the Mailgun HTTP webhook signing key as described in diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index dae400ff755..fbd3e636123 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # PlantUML **(FREE SELF)** @@ -316,8 +315,7 @@ stop; After configuring your local PlantUML server, you're ready to enable the PlantUML integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, go to **Settings > General** and expand the **PlantUML** section. 1. Select the **Enable PlantUML** checkbox. 1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`, diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index baeabdc6964..cb7d51f882a 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web terminals (deprecated) **(FREE SELF)** @@ -112,7 +112,6 @@ they receive a `Connection failed` message. By default, terminal sessions do not expire. To limit the terminal session lifetime in your GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Web terminal**. 1. Set a `max session time`. diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 5db08075449..e58d56b2aed 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Markdown cache **(FREE SELF)** diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index d179b77530a..cf61b930800 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Issue closing pattern **(FREE SELF)** diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 442e9638d86..33dc2020331 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs artifacts administration **(FREE SELF)** diff --git a/doc/administration/job_artifacts_troubleshooting.md b/doc/administration/job_artifacts_troubleshooting.md index c2be485a9ad..138803a2675 100644 --- a/doc/administration/job_artifacts_troubleshooting.md +++ b/doc/administration/job_artifacts_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job artifact troubleshooting for administrators diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index c8702260ccb..364927b4726 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job logs **(FREE SELF)** diff --git a/doc/administration/labels.md b/doc/administration/labels.md index adc621a2982..25a86b8c2fc 100644 --- a/doc/administration/labels.md +++ b/doc/administration/labels.md @@ -1,13 +1,12 @@ --- 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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels administration **(FREE SELF)** -To manage labels for the GitLab instance, select **Labels** (**{labels}**) from the Admin Area sidebar. For more details on how to manage labels, see [Labels](../user/project/labels.md). +To manage labels for the GitLab instance, in the Admin Area, on the left sidebar, select **Labels**. For more details on how to manage labels, see [Labels](../user/project/labels.md). Labels created in the Admin Area are automatically added to new projects. They are not available to new groups. diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index 26034ce1d01..5eccbf9e951 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/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # GitLab Git Large File Storage (LFS) Administration **(FREE SELF)** diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index 899269fb9d1..d91f286c633 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using the Libravatar service with GitLab **(FREE SELF)** diff --git a/doc/administration/license.md b/doc/administration/license.md index 05b60955ed9..1dc39d9ac23 100644 --- a/doc/administration/license.md +++ b/doc/administration/license.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Provision -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** @@ -15,7 +15,7 @@ your instance with an activation code. In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate your instance. -Prerequisite: +Prerequisites: - You must [purchase a subscription](https://about.gitlab.com/pricing/). - You must be running GitLab Enterprise Edition (EE). @@ -28,8 +28,7 @@ To activate your instance with an activation code: - Your subscription confirmation email. - The [Customers Portal](https://customers.gitlab.com/customers/sign_in), on the **Manage Purchases** page. 1. Sign in to your GitLab self-managed instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. 1. Paste the activation code in **Activation code**. 1. Read and accept the terms of service. diff --git a/doc/administration/license_file.md b/doc/administration/license_file.md index 2086e4888a7..fc1de38bb11 100644 --- a/doc/administration/license_file.md +++ b/doc/administration/license_file.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Provision -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- To promote the workflow described in license.md, this page is not included in global left nav. --> @@ -18,8 +18,7 @@ link to the **Add license** page should be displayed. Otherwise, to add your license: 1. Sign in to GitLab as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. In the **Add License** area, add a license by either uploading the file or entering the key. 1. Select the **Terms of Service** checkbox. @@ -45,7 +44,7 @@ If you have a license, you can also import it when you install GitLab. - For self-compiled installations: - Place the `Gitlab.gitlab-license` file in the `config/` directory. - - To specify a custom location and filename for the license, set the + - To specify a custom location and file name for the license, set the `GITLAB_LICENSE_FILE` environment variable with the path to the file: ```shell @@ -54,7 +53,7 @@ If you have a license, you can also import it when you install GitLab. - For Linux package installations: - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. - - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: + - To specify a custom location and file name for the license, add this entry to `gitlab.rb`: ```ruby gitlab_rails['initial_license_file'] = "/path/to/license/file" @@ -96,8 +95,7 @@ To go back to Free features, [delete all expired licenses](#remove-a-license). To remove a license from a self-managed instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. 1. Select **Remove license**. @@ -107,8 +105,7 @@ Repeat these steps to remove all licenses, including those applied in the past. To view your license details: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. You can add and view more than one license, but only the latest license in diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 1662febc8cc..d58b70865df 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Balancer for multi-node GitLab **(FREE SELF)** diff --git a/doc/administration/logs/index.md b/doc/administration/logs/index.md index 3bb26681fae..1b1591a36d9 100644 --- a/doc/administration/logs/index.md +++ b/doc/administration/logs/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Log system **(FREE SELF)** @@ -985,8 +985,15 @@ For example: ## `geo.log` **(PREMIUM SELF)** -Geo stores structured log messages in a `geo.log` file. For Linux package -installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. +Geo stores structured log messages in a `geo.log` file. For Linux package installations, +this file is at `/var/log/gitlab/gitlab-rails/geo.log`. + +For Helm chart installations, it's stored in the Sidekiq pod, at `/var/log/gitlab/geo.log`. +It can be read by either directly accessing the file, or by using `kubectl` to fetch the Sidekiq logs, and subsequently filtering the results by `"subcomponent"=="geo"`. The example below uses `jq` to grab only Geo logs: + +```shell +kubectl logs -l app=sidekiq --max-log-requests=50 | jq 'select(."subcomponent"=="geo")' +``` This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be @@ -1037,7 +1044,7 @@ This file is located at: ## Registry logs -For Linux package installations, Container Registry logs are in `/var/log/gitlab/registry/current`. +For Linux package installations, container registry logs are in `/var/log/gitlab/registry/current`. ## NGINX logs @@ -1047,8 +1054,8 @@ For Linux package installations, NGINX logs are in: - `/var/log/gitlab/nginx/gitlab_error.log`: A log of NGINX errors for GitLab - `/var/log/gitlab/nginx/gitlab_pages_access.log`: A log of requests made to Pages static sites - `/var/log/gitlab/nginx/gitlab_pages_error.log`: A log of NGINX errors for Pages static sites -- `/var/log/gitlab/nginx/gitlab_registry_access.log`: A log of requests made to the Container Registry -- `/var/log/gitlab/nginx/gitlab_registry_error.log`: A log of NGINX errors for the Container Registry +- `/var/log/gitlab/nginx/gitlab_registry_access.log`: A log of requests made to the container registry +- `/var/log/gitlab/nginx/gitlab_registry_error.log`: A log of NGINX errors for the container registry - `/var/log/gitlab/nginx/gitlab_mattermost_access.log`: A log of requests made to Mattermost - `/var/log/gitlab/nginx/gitlab_mattermost_error.log`: A log of NGINX errors for Mattermost diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md index b281620fcf3..3ac24fbb9ab 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Parsing GitLab logs with `jq` **(FREE SELF)** @@ -24,7 +24,7 @@ include use cases targeted for parsing GitLab log files. ## Parsing Logs The examples listed below address their respective log files by -their relative Linux package installation paths and default filenames. +their relative Linux package installation paths and default file names. Find the respective full paths in the [GitLab logs sections](../logs/index.md#production_jsonlog). ### General Commands diff --git a/doc/administration/logs/tracing_correlation_id.md b/doc/administration/logs/tracing_correlation_id.md index 79c8dcf4d81..f6b341ff114 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Find relevant log entries with a correlation ID **(FREE SELF)** diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 36c702bbda1..f4823ce9af1 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Maintenance Mode **(PREMIUM SELF)** @@ -21,8 +21,7 @@ Maintenance Mode allows most external actions that do not change internal state. Enable Maintenance Mode as an administrator in one of these ways: - **Web UI**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -46,8 +45,7 @@ Enable Maintenance Mode as an administrator in one of these ways: Disable Maintenance Mode in one of three ways: - **Web UI**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -162,13 +160,13 @@ You should disable auto deploys during Maintenance Mode, and enable them when it Terraform integration depends on running CI pipelines, hence it is blocked. -### Container Registry +### Container registry `docker push` fails with this error: `denied: requested access to the resource is denied`, but `docker pull` works. -### Package Registry +### Package registry -Package Registry allows you to install but not publish packages. +Package registry allows you to install but not publish packages. ### Background jobs @@ -181,9 +179,8 @@ you should disable all cron jobs except for those related to Geo. To monitor queues and disable jobs: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Background Jobs**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Background Jobs**. 1. In the Sidekiq dashboard, select **Cron** and disable jobs individually or all at once by selecting **Disable All**. ### Incident management diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 9c4ddcdc094..a3874091f34 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request diffs storage **(FREE SELF)** diff --git a/doc/administration/merge_requests_approvals.md b/doc/administration/merge_requests_approvals.md index 8c554b00048..9e766633d56 100644 --- a/doc/administration/merge_requests_approvals.md +++ b/doc/administration/merge_requests_approvals.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approvals **(PREMIUM SELF)** @@ -19,8 +18,7 @@ and can no longer be changed: To enable merge request approval settings for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Push Rules**. 1. Expand **Merge request approvals**. 1. Choose the required options. diff --git a/doc/administration/moderate_users.md b/doc/administration/moderate_users.md index c12eb2b9a95..c2c3491b6fc 100644 --- a/doc/administration/moderate_users.md +++ b/doc/administration/moderate_users.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moderate users (administration) **(FREE SELF)** @@ -42,8 +41,7 @@ sign in. To view user sign ups pending approval: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Pending approval** tab. @@ -53,8 +51,7 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Pending approval** tab. 1. For the user sign up you want to approve or reject, select the vertical ellipsis (**{ellipsis_v}**), then **Approve** or **Reject**. @@ -68,34 +65,37 @@ Approving a user: ## Block and unblock users GitLab administrators can block and unblock users. +You should block a user when you don't want them to access the instance, but you want to retain their data. + +A blocked user: + +- Cannot sign in or access any repositories. The blocked user's data remains in those repositories. +- Cannot use slash commands. For more information, see [slash commands](../user/project/integrations/gitlab_slack_application.md#slash-commands). +- Does not occupy a seat. For more information, see [billable users](../subscriptions/self_managed/index.md#billable-users). ### Block a user -Prerequisite: +Prerequisites: - You must be an administrator for the instance. -You can block a user's access to the instance. When you block a user, they receive an email notification that their account has been blocked. After this email, they no longer receive notifications. A blocked user: - -- Cannot sign in or access any repositories, but all of their data remains in those repositories. -- Cannot use slash commands. For more information, see [slash commands](../user/project/integrations/gitlab_slack_application.md#slash-commands). -- Does not occupy a seat. For more information, see [billable users](../subscriptions/self_managed/index.md#billable-users). +You can block a user's access to the instance. To block a user: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to block, select the vertical ellipsis (**{ellipsis_v}**), then **Block**. +The user receives an email notification that their account has been blocked. After this email, they no longer receive notifications. + To report abuse from other users, see [report abuse](../user/report_abuse.md). For more information on abuse reports in the Admin area, see [resolving abuse reports](../administration/review_abuse_reports.md#resolving-abuse-reports). ### Unblock a user A blocked user can be unblocked from the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Blocked** tab. 1. For the user you want to unblock, select the vertical ellipsis (**{ellipsis_v}**), then **Unblock**. @@ -109,8 +109,7 @@ Users can also be unblocked using the [GitLab API](../api/users.md#unblock-user) The unblock option may be unavailable for LDAP users. To enable the unblock option, the LDAP identity first needs to be deleted: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Blocked** tab. 1. Select a user. @@ -120,30 +119,35 @@ the LDAP identity first needs to be deleted: ## Activate and deactivate users GitLab administrators can deactivate and activate users. +You should deactivate a user if they have no recent activity, and you don't want them to occupy a seat on the instance. -### Deactivate a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. - -You can temporarily deactivate a user who has no recent activity. - -The user you deactivate must be dormant. When you deactivate a user, their projects, group, and history remain. A deactivated user: +A deactivated user: +- Can sign in to GitLab. + - If a deactivated user signs in, they are automatically activated. - Cannot access repositories or the API. - Cannot use slash commands. For more information, see [slash commands](../user/project/integrations/gitlab_slack_application.md#slash-commands). - Does not occupy a seat. For more information, see [billable users](../subscriptions/self_managed/index.md#billable-users). -Deactivation is similar to blocking, but there are a few important differences. Deactivating a user does not prohibit the user from signing into the GitLab UI. A deactivated user can become active again by signing in. +When you deactivate a user, their projects, groups, and history remain. + +### Deactivate a user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. + +Prerequisites: + +- The user has had no activity in the last 90 days. -To deactivate a user from the Admin Area: +To deactivate a user: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to deactivate, select the vertical ellipsis (**{ellipsis_v}**) and then **Deactivate**. 1. On the dialog, select **Deactivate**. -Email notifications stop after deactivation. GitLab sends email notifications to users when their account has been deactivated. For more information about this feature, see [user deactivation emails](../administration/settings/email.md#user-deactivation-emails). +The user receives an email notification that their account has been deactivated. After this email, they no longer receive notifications. +For more information, see [user deactivation emails](../administration/settings/email.md#user-deactivation-emails). To deactivate users with the GitLab API, see [deactivate user](../api/users.md#deactivate-user). For information about permanent user restrictions, see [block and unblock users](#block-and-unblock-users). @@ -161,8 +165,7 @@ Administrators can enable automatic deactivation of users who either: To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Under **Dormant users**, check **Deactivate dormant users after a period of inactivity**. @@ -212,8 +215,7 @@ A deactivated user can be activated from the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Deactivated** tab. 1. For the user you want to activate, select the vertical ellipsis (**{ellipsis_v}**), then **Activate**. @@ -233,7 +235,13 @@ Users can also be activated using the [GitLab API](../api/users.md#activate-user > - Hiding comments of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112973) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `hidden_notes`. Disabled by default. > - Hiding projects of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121488) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `hide_projects_of_banned_users`. Disabled by default. -GitLab administrators can ban and unban users. Banned users are blocked, and their projects, issues, merge requests, and comments are hidden. +GitLab administrators can ban and unban users. +You should ban a user when you want to block them and hide their activity from the instance. + +A banned user: + +- Is blocked from the instance. The banned user's projects, issues, merge requests, and comments are hidden. +- Does not occupy a [seat](../subscriptions/self_managed/index.md#billable-users). ### Ban a user @@ -241,19 +249,15 @@ To block a user and hide their contributions, administrators can ban the user. Users can be banned using the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to ban, select the vertical ellipsis (**{ellipsis_v}**), then **Ban user**. -The banned user does not consume a [seat](../subscriptions/self_managed/index.md#billable-users). - ### Unban a user A banned user can be unbanned using the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Banned** tab. 1. For the user you want to unban, select the vertical ellipsis (**{ellipsis_v}**), then **Unban user**. @@ -265,8 +269,7 @@ The user's state is set to active and they consume a Use the Admin Area to delete users. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to delete, select the vertical ellipsis (**{ellipsis_v}**), then **Delete user**. 1. Type the username. @@ -277,8 +280,7 @@ You can only delete a user if there are inherited or direct owners of a group. Y You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to delete, select the vertical ellipsis (**{ellipsis_v}**), then **Delete user and contributions**. 1. Type the username. @@ -295,7 +297,7 @@ You can trust and untrust users from the Admin Area. By default, a user is not trusted and is blocked from creating issues, notes, and snippets considered to be spam. When you trust a user, they can create issues, notes, and snippets without being blocked. -Prerequisite: +Prerequisites: - You must be an administrator. @@ -303,8 +305,7 @@ Prerequisite: :::TabTitle Trust a user -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select a user. 1. From the **User administration** dropdown list, select **Trust user**. @@ -314,8 +315,7 @@ The user is trusted. :::TabTitle Untrust a user -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Trusted** tab. 1. Select a user. diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index 74e584db3a0..28dbc3d8209 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitHub imports **(FREE SELF)** diff --git a/doc/administration/monitoring/health_check.md b/doc/administration/monitoring/health_check.md index 4dbbdf6f3c9..b688387ded6 100644 --- a/doc/administration/monitoring/health_check.md +++ b/doc/administration/monitoring/health_check.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Health Check **(FREE SELF)** diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md index 622a772a638..10fe1486484 100644 --- a/doc/administration/monitoring/index.md +++ b/doc/administration/monitoring/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab **(FREE SELF)** diff --git a/doc/administration/monitoring/ip_allowlist.md b/doc/administration/monitoring/ip_allowlist.md index b3ddc05776c..d861a24ba2d 100644 --- a/doc/administration/monitoring/ip_allowlist.md +++ b/doc/administration/monitoring/ip_allowlist.md @@ -1,15 +1,15 @@ --- stage: Data Stores group: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# IP whitelist **(FREE SELF)** +# IP allowlist **(FREE SELF)** GitLab provides some [monitoring endpoints](health_check.md) that provide health check information when probed. -To control access to those endpoints via IP whitelisting, you can add single +To control access to those endpoints through IP allowlisting, you can add single hosts or use IP ranges: ::Tabs @@ -32,7 +32,7 @@ You can set the required IPs under the `gitlab.webservice.monitoring.ipWhitelist gitlab: webservice: monitoring: - # Monitoring IP whitelist + # Monitoring IP allowlist ipWhitelist: - 0.0.0.0/0 # Default ``` diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index a32a38a11e5..7dc4f34e514 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Configuration **(FREE SELF)** @@ -9,10 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab Performance Monitoring is disabled by default. To enable it and change any of its settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling** - (`/admin/application_settings/metrics_and_profiling`). +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Add the necessary configuration changes. 1. Restart all GitLab for the changes to take effect: diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index a69eb67e77e..0d264972073 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Grafana **(FREE SELF)** @@ -34,10 +34,9 @@ see the [GitLab Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashbo After setting up Grafana, you can enable a link to access it from the GitLab sidebar: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling** - and expand **Metrics - Grafana**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. +1. Expand **Metrics - Grafana**. 1. Select the **Add a link to Grafana** checkbox. 1. Configure the **Grafana URL**. Enter the full URL of the Grafana instance. 1. Select **Save changes**. diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index 935ee4719c5..88faf071cfe 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Performance Monitoring **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 95717f0c54f..a8bf39761ed 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance bar **(FREE SELF)** @@ -107,11 +107,9 @@ The performance bar is disabled by default for non-administrators. To enable it for a given group: 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling** - (`admin/application_settings/metrics_and_profiling`), and expand - **Profiling - Performance bar**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. +1. Expand **Profiling - Performance bar**. 1. Select **Allow non-administrators access to the performance bar**. 1. In the **Allow access to members of the following group** field, provide the full path of the group allowed to access the performance. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 75400535e60..96f666db0ed 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 2eb482cae69..80121c7c235 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -1,7 +1,7 @@ --- stage: Shared responsibility based on functional area group: Shared responsibility based on functional area -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Prometheus metrics **(FREE SELF)** @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w To enable the GitLab Prometheus metrics: 1. Log in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Find the **Metrics - Prometheus** section, and select **Enable GitLab Prometheus metrics endpoint**. 1. [Restart GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -178,6 +177,9 @@ The following metrics are available: | `gitlab_ci_queue_iteration_duration_seconds` | Histogram | 16.3 | Time it takes to find a build in CI/CD queue | | `gitlab_ci_queue_retrieval_duration_seconds` | Histogram | 16.3 | Time it takes to execute a SQL query to retrieve builds queue | | `gitlab_ci_queue_active_runners_total` | Histogram | 16.3 | The amount of active runners that can process queue in a project | +| `gitlab_connection_pool_size` | Gauge | 16.7 | Size of connection pool | +| `gitlab_connection_pool_available_count` | Gauge | 16.7 | Number of available connections in the pool | +| `gitlab_security_policies_scan_result_process_duration_seconds` | Histogram | 16.7 | The amount of time to process scan result policies | ## Metrics controlled by a feature flag diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 01b1851ab7f..bd3f2a20006 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab with Prometheus **(FREE SELF)** @@ -42,10 +42,14 @@ monitoring target for Prometheus, unless individually disabled. To disable Prometheus and all of its exporters, as well as any added in the future: 1. Edit `/etc/gitlab/gitlab.rb` -1. Add or find and uncomment the following line, making sure it's set to `false`: +1. Add or find and uncomment the following lines, making sure they are set to `false`: ```ruby prometheus_monitoring['enable'] = false + sidekiq['metrics_enabled'] = false + + # Already set to `false` by default, but you can explicitly disable it to be sure + puma['exporter_enabled'] = false ``` 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to @@ -98,7 +102,7 @@ prometheus['scrape_configs'] = [ 'metrics_path': '/probe', 'params' => { 'param_a' => ['test'], - 'param_b' => ['additional_test'] + 'param_b' => ['additional_test'], }, 'static_configs' => [ 'targets' => ['1.1.1.1:8060'], @@ -212,7 +216,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. On **all** GitLab Rails(Puma, Sidekiq) servers, set the Prometheus server IP address and listen port. For example: +1. On **all** GitLab Rails (Puma, Sidekiq) servers, set the Prometheus server IP address and listen port. For example: ```ruby gitlab_rails['prometheus_address'] = '192.168.0.1:9090' @@ -236,7 +240,7 @@ To use an external Prometheus server: nginx['status']['options'] = { "server_tokens" => "off", "access_log" => "off", - "allow" => ["192.168.0.1", "192.168.0.2"] + "allow" => ["192.168.0.1", "192.168.0.2"], "deny" => "all", } ``` diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index 4de05034fff..6b395f77ce2 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -1,7 +1,7 @@ --- stage: Shared responsibility based on functional area group: Shared responsibility based on functional area -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Node exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index 6f925cb7fb6..e1773301047 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PgBouncer exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index 20cfb078994..fe04ae3f797 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL Server Exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 25c76fac743..fde07c68c0a 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -1,7 +1,7 @@ --- stage: Shared responsibility based on functional area group: Shared responsibility based on functional area -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 1c46224f7b3..8dde7086d79 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Registry exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/web_exporter.md b/doc/administration/monitoring/prometheus/web_exporter.md index fbf4a109813..2831ca17c81 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: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web exporter (dedicated metrics server) **(FREE SELF)** diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index 119f757bfbc..5f12c141540 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using NFS with GitLab **(FREE SELF)** @@ -258,7 +257,6 @@ following are the 4 locations need to be shared: | Location | Description | Default configuration | | -------- | ----------- | --------------------- | -| `/var/opt/gitlab/git-data` | Git repository data. This accounts for a large portion of your data | `git_data_dirs({"default" => { "path" => "/var/opt/gitlab/git-data"} })` | `/var/opt/gitlab/gitlab-rails/uploads` | User uploaded attachments | `gitlab_rails['uploads_directory'] = '/var/opt/gitlab/gitlab-rails/uploads'` | `/var/opt/gitlab/gitlab-rails/shared` | Objects such as build artifacts, GitLab Pages, LFS objects, and temp files. If you're using LFS this may also account for a large portion of your data | `gitlab_rails['shared_path'] = '/var/opt/gitlab/gitlab-rails/shared'` | `/var/opt/gitlab/gitlab-ci/builds` | GitLab CI/CD build traces | `gitlab_ci['builds_directory'] = '/var/opt/gitlab/gitlab-ci/builds'` diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 0b12d41eb4e..9a9b2811cf0 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Object storage **(FREE SELF)** @@ -157,13 +157,13 @@ For the storage-specific form, because it does not require a shared folder. For configuring object storage in GitLab 13.1 and earlier, _or_ for storage types not -For storage types not supported by the consolidated form, refer to the following guides: +supported by the consolidated form, refer to the following guides: | Object storage type | Supported by consolidated form? | |---------------------|------------------------------------------| | [Secure Files](secure_files.md#using-object-storage) | **{dotted-circle}** No | | [Backups](../administration/backup_restore/backup_gitlab.md#upload-backups-to-a-remote-cloud-storage) | **{dotted-circle}** No | -| [Container Registry](packages/container_registry.md#use-object-storage) (optional feature) | **{dotted-circle}** No | +| [Container registry](packages/container_registry.md#use-object-storage) (optional feature) | **{dotted-circle}** No | | [Mattermost](https://docs.mattermost.com/configure/file-storage-configuration-settings.html)| **{dotted-circle}** No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | **{dotted-circle}** No | | [Job artifacts](job_artifacts.md#using-object-storage) including archived job logs | **{check-circle}** Yes | @@ -814,7 +814,7 @@ or add fault tolerance and redundancy, you may be looking at removing dependencies on block or network file systems. See the following additional guides: -1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk. +1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#move-the-home-directory-for-a-user) is on local disk. 1. Configure [database lookup of SSH keys](operations/fast_ssh_key_lookup.md) to eliminate the need for a shared `authorized_keys` file. 1. [Prevent local disk usage for job logs](job_logs.md#prevent-local-disk-usage). diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 888ec79d4b6..2170abf8700 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fast lookup of authorized SSH keys in the database **(FREE SELF)** @@ -121,9 +121,8 @@ users as long as a large file exists. To disable writes to the `authorized_keys` file: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Performance optimization**. 1. Clear the **Use authorized_keys file to authenticate SSH keys** checkbox. 1. Select **Save changes**. @@ -141,8 +140,7 @@ This overview is brief. Refer to the above instructions for more context. 1. [Rebuild the `authorized_keys` file](../raketasks/maintenance.md#rebuild-authorized_keys-file). 1. Enable writes to the `authorized_keys` file. - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. 1. Select the **Use authorized_keys file to authenticate SSH keys** checkbox. diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index bd37bd4b1a8..7b0bb012624 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File system performance benchmarking **(FREE SELF)** diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md index 43ca6251a0e..86c6d9d7fba 100644 --- a/doc/administration/operations/gitlab_sshd.md +++ b/doc/administration/operations/gitlab_sshd.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # `gitlab-sshd` **(FREE SELF)** diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index be90b0a073f..33f407b2dbf 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintain your GitLab installation **(FREE SELF)** diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 49746c7cc72..2c2762d92b7 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving repositories managed by GitLab **(FREE SELF)** diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 89f1574697f..ec236f52c5b 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the bundled Puma instance of the GitLab package **(FREE SELF)** diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index b3e7a97428a..f15fdd32c90 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails console **(FREE SELF)** @@ -108,13 +108,24 @@ Notify.test_email(u.email, "Test email for #{u.name}", 'Test email').deliver_now ## Disable database statement timeout You can disable the PostgreSQL statement timeout for the current Rails console -session by running: +session. + +In GitLab 15.11 and earlier, to disable the database statement timeout, run: + +```ruby +ActiveRecord::Base.connection.execute('SET statement_timeout TO 0') +``` + +In GitLab 16.0 and later, [GitLab uses two database connections by default](../../update/versions/gitlab_16_changes.md#1600). To disable the database statement timeout, run: ```ruby ActiveRecord::Base.connection.execute('SET statement_timeout TO 0') +Ci::ApplicationRecord.connection.execute('SET statement_timeout TO 0') ``` -This change only affects the current Rails console session and is +Instances running GitLab 16.0 and later reconfigured to use a single database connection should disable the database statement timeout using the code for GitLab 15.11 and earlier. + +Disabling the database statement timeout affects only the current Rails console session and is not persisted in the GitLab production environment or in the next Rails console session. @@ -707,7 +718,7 @@ irb(#<Project>)> web_url The `gitlab-rails` command executes Rails Runner using a non-root account and group, by default: `git:git`. -If the non-root account cannot find the Ruby script filename passed to `gitlab-rails runner` +If the non-root account cannot find the Ruby script file name passed to `gitlab-rails runner` you may get a syntax error, not an error that the file couldn't be accessed. A common reason for this is that the script has been put in the root account's home directory. diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index bdd1045f7a7..ca24b2e0721 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User lookup via OpenSSH's AuthorizedPrincipalsCommand **(FREE SELF)** diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md index f85ada3c782..93f01d71879 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package defaults **(FREE SELF)** diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md index f2d23da2b7e..7cc589990db 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linux package deprecation policy **(FREE SELF)** diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md index 503fdfe3ba8..59086579965 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package information **(FREE SELF)** diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md index cad9c0e6075..2f907ba9df3 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Licensing **(FREE SELF)** diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md index d16783034dc..8f8fa0097f7 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages and images from the Linux package **(FREE SELF)** diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md index 3a499be43b3..5140d795892 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL versions shipped with the Linux package **(FREE SELF)** @@ -29,19 +29,21 @@ The lowest supported PostgreSQL versions are listed in the Read more about update policies and warnings in the PostgreSQL [upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). -| GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | +| First GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | | -------------- | ------------------- | ---------------------------------- | ---------------------------- | ----- | -| 16.2.0 | 13.11, 14.8 | 13.11 | 13.11 | For upgrades, users can manually upgrade to 14.8 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-162-and-later). | +| 16.7.0 | 13.12, 14.9 | 14.9 | 14.9 | | +| 16.4.3, 16.5.3, 16.6.1 | 13.12, 14.9 | 13.12 | 13.12 | For upgrades, you can manually upgrade to 14.9 following the [upgrade documentation](../../update/versions/gitlab_16_changes.md#linux-package-installations-2). | +| 16.2.0 | 13.11, 14.8 | 13.11 | 13.11 | For upgrades, you can manually upgrade to 14.8 following the [upgrade documentation](../../update/versions/gitlab_16_changes.md#linux-package-installations-2). | | 16.0.2 | 13.11 | 13.11 | 13.11 | | | 16.0.0 | 13.8 | 13.8 | 13.8 | | | 15.11.7 | 13.11 | 13.11 | 12.12 | | | 15.10.8 | 13.11 | 13.11 | 12.12 | | -| 15.6 | 12.12, 13.8 | 13.8 | 12.12 | For upgrades, users can manually upgrade to 13.8 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-150-and-later). | -| 15.0 | 12.10, 13.6 | 13.6 | 12.10 | For upgrades, users can manually upgrade to 13.6 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-150-and-later). | +| 15.6 | 12.12, 13.8 | 13.8 | 12.12 | For upgrades, you can manually upgrade to 13.8 following the [upgrade documentation](../../update/versions/gitlab_15_changes.md#linux-package-installations-2). | +| 15.0 | 12.10, 13.6 | 13.6 | 12.10 | For upgrades, you can manually upgrade to 13.6 following the [upgrade documentation](../../update/versions/gitlab_15_changes.md#linux-package-installations-2). | | 14.1 | 12.7, 13.3 | 12.7 | 12.7 | PostgreSQL 13 available for fresh installations if not using [Geo](../geo/index.md#requirements-for-running-geo) or [Patroni](../postgresql/index.md#postgresql-replication-and-failover-for-linux-package-installations). | 14.0 | 12.7 | 12.7 | 12.7 | HA installations with repmgr are no longer supported and are prevented from upgrading to Linux package 14.0 | | 13.8 | 11.9, 12.4 | 12.4 | 12.4 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or HA cluster. | -| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-133-and-later). | +| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). | | 13.4 | 11.9, 12.4 | 11.9 | 11.9 | Package upgrades aborted if users not running PostgreSQL 11 already | | 13.3 | 11.7, 12.3 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | | 13.0 | 11.7 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md index b2aab96e52c..22ac472c590 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Signatures **(FREE SELF)** diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md index ab579ca93c6..89b2f78f6d9 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported operating systems **(FREE SELF)** diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 74dd71c19bf..bfeca7c56b9 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -1,12 +1,12 @@ --- stage: Package group: Container Registry -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Container Registry administration **(FREE SELF)** +# GitLab container registry administration **(FREE SELF)** -With the GitLab Container Registry, every project can have its +With the GitLab container registry, every project can have its own space to store Docker images. For more details about the Distribution Registry: @@ -18,24 +18,24 @@ For more details about the Distribution Registry: This document is the administrator's guide. To learn how to use the GitLab Container Registry, see the [user documentation](../../user/packages/container_registry/index.md). -## Enable the Container Registry +## Enable the container registry -The process for enabling the Container Registry depends on the type of installation you use. +The process for enabling the container registry depends on the type of installation you use. ### Linux package installations -If you installed GitLab by using the Linux package, the Container Registry +If you installed GitLab by using the Linux package, the container registry may or may not be available by default. -The Container Registry is automatically enabled and available on your GitLab domain, port 5050 if +The container registry is automatically enabled and available on your GitLab domain, port 5050 if you're using the built-in [Let's Encrypt integration](https://docs.gitlab.com/omnibus/settings/ssl/index.html#enable-the-lets-encrypt-integration). -Otherwise, the Container Registry is not enabled. To enable it: +Otherwise, the container registry is not enabled. To enable it: - You can configure it for your [GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain), or - You can configure it for [a different domain](#configure-container-registry-under-its-own-domain). -The Container Registry works under HTTPS by default. You can use HTTP +The container registry works under HTTPS by default. You can use HTTP but it's not recommended and is beyond the scope of this document. ### Self-compiled installations @@ -96,7 +96,7 @@ auth: WARNING: If `auth` is not set up, users can pull Docker images without authentication. -## Container Registry domain configuration +## Container registry domain configuration You can configure the Registry's external domain in either of these ways: @@ -105,19 +105,19 @@ You can configure the Registry's external domain in either of these ways: - [Use a completely separate domain](#configure-container-registry-under-its-own-domain) with a new TLS certificate for that domain. -Because the Container Registry requires a TLS certificate, cost may be a factor. +Because the container registry requires a TLS certificate, cost may be a factor. -Take this into consideration before configuring the Container Registry +Take this into consideration before configuring the container registry for the first time. -### Configure Container Registry under an existing GitLab domain +### Configure container registry under an existing GitLab domain -If the Container Registry is configured to use the existing GitLab domain, you can -expose the Container Registry on a port. This way you can reuse the existing GitLab TLS +If the container registry is configured to use the existing GitLab domain, you can +expose the container registry on a port. This way you can reuse the existing GitLab TLS certificate. If the GitLab domain is `https://gitlab.example.com` and the port to the outside world is `5050`, -to configure the Container Registry: +to configure the container registry: - Edit `gitlab.rb` if you are using a Linux package installation. - Edit `gitlab.yml` if you are using a self-compiled installation. @@ -194,14 +194,14 @@ registry_nginx['listen_port'] = 5678 ::EndTabs -Users should now be able to sign in to the Container Registry with their GitLab +Users should now be able to sign in to the container registry with their GitLab credentials using: ```shell docker login gitlab.example.com:5050 ``` -### Configure Container Registry under its own domain +### Configure container registry under its own domain When the Registry is configured to use its own domain, you need a TLS certificate for that specific domain (for example, `registry.example.com`). You might need @@ -212,7 +212,7 @@ and is distinct from `*.example.com`. As well as manually generated SSL certificates (explained here), certificates automatically generated by Let's Encrypt are also [supported in Linux package installations](https://docs.gitlab.com/omnibus/settings/ssl/index.html). -Let's assume that you want the container Registry to be accessible at +Let's assume that you want the container registry to be accessible at `https://registry.gitlab.example.com`. ::Tabs @@ -263,14 +263,14 @@ registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" ::EndTabs -Users should now be able to sign in to the Container Registry using their GitLab +Users should now be able to sign in to the container registry using their GitLab credentials: ```shell docker login registry.gitlab.example.com ``` -## Disable Container Registry site-wide +## Disable container registry site-wide When you disable the Registry by following these steps, you do not remove any existing Docker images. Docker image removal is handled by the @@ -302,11 +302,11 @@ Registry application itself. ::EndTabs -## Disable Container Registry for new projects site-wide +## Disable container registry for new projects site-wide -If the Container Registry is enabled, then it should be available on all new +If the container registry is enabled, then it should be available on all new projects. To disable this function and let the owners of a project to enable -the Container Registry by themselves, follow the steps below. +the container registry by themselves, follow the steps below. ::Tabs @@ -342,17 +342,16 @@ the Container Registry by themselves, follow the steps below. ### Increase token duration -In GitLab, tokens for the Container Registry expire every five minutes. +In GitLab, tokens for the container registry expire every five minutes. To increase the token duration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Container Registry**. 1. For the **Authorization token duration (minutes)**, update the value. 1. Select **Save changes**. -## Configure storage for the Container Registry +## Configure storage for the container registry NOTE: For storage backends that support it, you can use object versioning to preserve, retrieve, and @@ -367,8 +366,8 @@ you should configure an object lifecycle policy with your storage provider. WARNING: Do not directly modify the files or objects stored by the container registry. Anything other than the registry writing or deleting these entries can lead to instance-wide data consistency and instability issues from which recovery may not be possible. -You can configure the Container Registry to use various storage backends by -configuring a storage driver. By default the GitLab Container Registry +You can configure the container registry to use various storage backends by +configuring a storage driver. By default the GitLab container registry is configured to use the [file system driver](#use-file-system) configuration. @@ -380,19 +379,32 @@ The different supported drivers are: | `azure` | Microsoft Azure Blob Storage | | `gcs` | Google Cloud Storage | | `s3` | Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct [S3 Permission Scopes](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). | -| `swift` | OpenStack Swift Object Storage | -| `oss` | Aliyun OSS | -Although most S3 compatible services (like [MinIO](https://min.io/)) should work with the Container Registry, we only guarantee support for AWS S3. Because we cannot assert the correctness of third-party S3 implementations, we can debug issues, but we cannot patch the registry unless an issue is reproducible against an AWS S3 bucket. +Although most S3 compatible services (like [MinIO](https://min.io/)) should work with the container registry, +we only guarantee support for AWS S3. Because we cannot assert the correctness of third-party S3 implementations, +we can debug issues, but we cannot patch the registry unless an issue is reproducible against an AWS S3 bucket. + +<!--- start_remove The following content will be removed on remove_date: '2024-05-16' --> + +WARNING: +Support for the following drivers was [deprecated](https://gitlab.com/gitlab-org/container-registry/-/issues/1141) +in GitLab 16.6, and is planned for removal in 17.0. This change is a breaking change. + +| Driver | Description | +|---------|-------------| +| `swift` | OpenStack Swift Object Storage | +| `oss` | Aliyun OSS | + +<!--- end_remove --> ### Use file system If you want to store your images on the file system, you can change the storage -path for the Container Registry, follow the steps below. +path for the container registry, follow the steps below. This path is accessible to: -- The user running the Container Registry daemon. +- The user running the container registry daemon. - The user running GitLab. All GitLab, Registry, and web server users must @@ -433,7 +445,7 @@ The default location where images are stored in self-compiled installations is ### Use object storage If you want to store your images on object storage, you can change the storage -driver for the Container Registry. +driver for the container registry. [Read more about using object storage with GitLab](../object_storage.md). @@ -566,15 +578,15 @@ to copy the registry data to or between S3 buckets creates invalid metadata obje For additional details, see [Tags with an empty name](#tags-with-an-empty-name). To move data to and between S3 buckets, the AWS CLI `sync` operation is recommended. -To migrate storage without stopping the Container Registry, set the Container Registry -to read-only mode. On large instances, this may require the Container Registry +To migrate storage without stopping the container registry, set the container registry +to read-only mode. On large instances, this may require the container registry to be in read-only mode for a while. During this time, -you can pull from the Container Registry, but you cannot push. +you can pull from the container registry, but you cannot push. 1. Optional: To reduce the amount of data to be migrated, run the [garbage collection tool without downtime](#performing-garbage-collection-without-downtime). 1. This example uses the `aws` CLI. If you haven't configured the CLI before, you have to configure your credentials by running `sudo aws configure`. - Because a non-administrator user likely can't access the Container Registry folder, + Because a non-administrator user likely can't access the container registry folder, ensure you use `sudo`. To check your credential configuration, run [`ls`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/ls.html) to list all buckets. @@ -598,7 +610,7 @@ you can pull from the Container Registry, but you cannot push. [running parallel sync operations](https://repost.aws/knowledge-center/s3-improve-transfer-sync-command). 1. To perform the final data sync, - [put the Container Registry in `read-only` mode](#performing-garbage-collection-without-downtime) and + [put the container registry in `read-only` mode](#performing-garbage-collection-without-downtime) and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). 1. Sync any changes dating from after the initial data load to your S3 bucket, and delete files that exist in the destination bucket but not in the source: @@ -615,7 +627,7 @@ you can pull from the Container Registry, but you cannot push. flag deletes files that exist in the destination but not in the source. If you swap the source and destination, all data in the Registry is deleted. -1. Verify all Container Registry files have been uploaded to object storage +1. Verify all container registry files have been uploaded to object storage by looking at the file count returned by these two commands: ```shell @@ -635,11 +647,6 @@ you can pull from the Container Registry, but you cannot push. > The default configuration for the storage driver is scheduled to be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. -<!--- start_remove The following content will be removed on remove_date: '2023-10-22' --> -WARNING: -The default configuration for the storage driver is scheduled to be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. The storage driver will use `/` as the default root directory. You can add `trimlegacyrootprefix: false` to your current configuration now to avoid any disruptions. For more information, see the [Container Registry configuration](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/upstream-differences.md#azure-storage-driver) documentation. -<!--- end_remove --> - When moving from an existing file system or another object storage provider to Azure Object Storage, you must configure the registry to use the standard root directory. Configure it by setting [`trimlegacyrootprefix: true`](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/upstream-differences.md#azure-storage-driver) in the Azure storage driver section of the registry configuration. Without this configuration, the Azure storage driver uses `//` instead of `/` as the first section of the root path, rendering the migrated images inaccessible. @@ -819,17 +826,17 @@ In the examples below we set the Registry's port to `5010`. ::EndTabs -## Disable Container Registry per project +## Disable container registry per project If Registry is enabled in your GitLab instance, but you don't need it for your -project, you can [disable it from your project's settings](../../user/project/settings/index.md#configure-project-features-and-permissions). +project, you can [disable it from your project's settings](../../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). ## Use an external container registry with GitLab as an auth endpoint WARNING: Using external container registries in GitLab is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/376217) in GitLab 15.8 and the end of support is scheduled for GitLab 16.0. -If you need to use external container registries instead of the GitLab Container Registry, +If you need to use external container registries instead of the GitLab container registry, tell us about your use cases in [feedback issue 958](https://gitlab.com/gitlab-org/container-registry/-/issues/958). If you use an external container registry, some features associated with the @@ -870,8 +877,8 @@ You can use GitLab as an auth endpoint with an external container registry. ``` - `gitlab_rails['registry_enabled'] = true` is needed to enable GitLab - Container Registry features and authentication endpoint. The GitLab bundled - Container Registry service does not start, even with this enabled. + container registry features and authentication endpoint. The GitLab bundled + container registry service does not start, even with this enabled. - `gitlab_rails['registry_api_url'] = "http://<external_registry_host>:5000"` must be changed to match the host where Registry is installed. It must also specify `https` if the external registry is @@ -916,7 +923,7 @@ You can use GitLab as an auth endpoint with an external container registry. 1. Open `/home/git/gitlab/config/gitlab.yml`, and edit the configuration settings under `registry`: ```yaml - ## Container Registry + ## Container registry registry: enabled: true @@ -932,15 +939,15 @@ You can use GitLab as an auth endpoint with an external container registry. 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. -## Configure Container Registry notifications +## Configure container registry notifications -You can configure the Container Registry to send webhook notifications in +You can configure the container registry to send webhook notifications in response to events happening in the registry. -Read more about the Container Registry notifications configuration options in the +Read more about the container registry notifications configuration options in the [Docker Registry notifications documentation](https://docs.docker.com/registry/notifications/). -You can configure multiple endpoints for the Container Registry. +You can configure multiple endpoints for the container registry. ::Tabs @@ -1062,7 +1069,7 @@ end You can also [run cleanup on a schedule](../../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy). -## Container Registry garbage collection +## Container registry garbage collection NOTE: Retention policies in your object storage provider, such as Amazon S3 Lifecycle, may prevent @@ -1073,17 +1080,17 @@ The container registry can use considerable amounts of storage space, and you mi Among the listed options, deleting tags is the most effective option. However, tag deletion alone does not delete image layers, it only leaves the underlying image manifests untagged. -To more effectively free up space, the Container Registry has a garbage collector that can +To more effectively free up space, the container registry has a garbage collector that can delete unreferenced layers and (optionally) untagged manifests. To start the garbage collector, use the `registry-garbage-collect` command provided by `gitlab-ctl`. WARNING: -This command shuts down the Container Registry prior to the garbage collection and +This command shuts down the container registry prior to the garbage collection and only starts it again after garbage collection completes. If you prefer to avoid downtime, -you can manually set the Container Registry to [read-only mode and bypass `gitlab-ctl`](#performing-garbage-collection-without-downtime). +you can manually set the container registry to [read-only mode and bypass `gitlab-ctl`](#performing-garbage-collection-without-downtime). -The time required to perform garbage collection is proportional to the Container Registry data size. +The time required to perform garbage collection is proportional to the container registry data size. Prerequisites: @@ -1115,9 +1122,9 @@ no longer directly accessible via the `:latest` tag. ### Remove unreferenced layers -Image layers are the bulk of the Container Registry storage. A layer is considered +Image layers are the bulk of the container registry storage. A layer is considered unreferenced when no image manifest references it. Unreferenced layers are the -default target of the Container Registry garbage collector. +default target of the container registry garbage collector. If you did not change the default location of the configuration file, run: @@ -1125,7 +1132,7 @@ If you did not change the default location of the configuration file, run: sudo gitlab-ctl registry-garbage-collect ``` -If you changed the location of the Container Registry `config.yml`: +If you changed the location of the container registry `config.yml`: ```shell sudo gitlab-ctl registry-garbage-collect /path/to/config.yml @@ -1136,7 +1143,7 @@ to recover additional space. ### Removing untagged manifests and unreferenced layers -By default the Container Registry garbage collector ignores images that are untagged, +By default the container registry garbage collector ignores images that are untagged, and users can keep pulling untagged images by digest. Users can also re-tag images in the future, making them visible again in the GitLab UI and API. @@ -1151,11 +1158,11 @@ If you are unsure about deleting untagged images, back up your registry data bef ### Performing garbage collection without downtime -To do garbage collection while keeping the Container Registry online, put the registry +To do garbage collection while keeping the container registry online, put the registry in read-only mode and bypass the built-in `gitlab-ctl registry-garbage-collect` command. -You can pull but not push images while the Container Registry is in read-only mode. The Container -Registry must remain in read-only for the full duration of the garbage collection. +You can pull but not push images while the container registry is in read-only mode. The container +registry must remain in read-only for the full duration of the garbage collection. By default, the [registry storage path](#configure-storage-for-the-container-registry) is `/var/opt/gitlab/gitlab-rails/shared/registry`. @@ -1183,7 +1190,7 @@ To enable the read-only mode: sudo gitlab-ctl reconfigure ``` - This command sets the Container Registry into the read-only mode. + This command sets the container registry into the read-only mode. 1. Next, trigger one of the garbage collect commands: @@ -1298,7 +1305,7 @@ for GitLab to run separately from Registry: Registry side. - `gitlab_rails['internal_key']`, contents of the key that GitLab uses to sign the tokens. -## Architecture of GitLab Container Registry +## Architecture of GitLab container registry The GitLab registry is what users use to store their own Docker images. Because of that the Registry is client facing, meaning that we expose it directly @@ -1342,10 +1349,10 @@ in GitLab 15.8 and the end of support occurred in GitLab 16.0. See the [deprecat The integration is not disabled in GitLab 16.0, but support for debugging and fixing issues is no longer provided. Additionally, the integration is no longer being developed or enhanced with new features. Third-party registry functionality might be completely removed -after the new GitLab Container Registry version is available for self-managed (see epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521)). Only the GitLab Container Registry is planned to be supported. +after the new GitLab container registry version is available for self-managed (see epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521)). Only the GitLab container registry is planned to be supported. This section has guidance for administrators migrating from third-party registries -to the GitLab Container Registry. If the third-party container registry you are using is not listed here, +to the GitLab container registry. If the third-party container registry you are using is not listed here, you can describe your use cases in [the feedback issue](https://gitlab.com/gitlab-org/container-registry/-/issues/958). For all of the instructions provided below, you should try them first on a test environment. @@ -1355,11 +1362,11 @@ Make sure everything continues to work as expected before replicating it in prod The [Docker Distribution Registry](https://docs.docker.com/registry/) was donated to the CNCF and is now known as the [Distribution Registry](https://github.com/distribution/distribution). -This registry is the open source implementation that the GitLab Container Registry is based on. -The GitLab Container Registry is compatible with the basic functionality provided by the Distribution Registry, -including all the supported storage backends. To migrate to the GitLab Container Registry +This registry is the open source implementation that the GitLab container registry is based on. +The GitLab container registry is compatible with the basic functionality provided by the Distribution Registry, +including all the supported storage backends. To migrate to the GitLab container registry you can follow the instructions on this page, and use the same storage backend as the Distribution Registry. -The GitLab Container Registry should accept the same configuration that you are using for the Distribution Registry. +The GitLab container registry should accept the same configuration that you are using for the Distribution Registry. ## Use a PostgreSQL database for metadata **(FREE SELF BETA)** @@ -1413,9 +1420,9 @@ Before diving in to the following sections, here's some basic troubleshooting: for errors (for example `/var/log/gitlab/gitlab-rails/production.log`). You may be able to find clues there. -### Using self-signed certificates with Container Registry +### Using self-signed certificates with container registry -If you're using a self-signed certificate with your Container Registry, you +If you're using a self-signed certificate with your container registry, you might encounter issues during the CI jobs like the following: ```plaintext @@ -1467,7 +1474,7 @@ Check which files are in use: - `grep -A6 'auth:' /var/opt/gitlab/registry/config.yml` ```yaml - ## Container Registry Certificate + ## Container registry certificate auth: token: realm: https://gitlab.my.net/jwt/auth @@ -1480,7 +1487,7 @@ Check which files are in use: - `grep -A9 'Container Registry' /var/opt/gitlab/gitlab-rails/etc/gitlab.yml` ```yaml - ## Container Registry Key + ## Container registry key registry: enabled: true host: gitlab.company.com @@ -1600,7 +1607,7 @@ project or branch name. Special characters can include: - Double hyphen/dash To get around this, you can [change the group path](../../user/group/manage.md#change-a-groups-path), -[change the project path](../../user/project/settings/index.md#rename-a-repository) or change the +[change the project path](../../user/project/working_with_projects.md#rename-a-repository) or change the branch name. Another option is to create a [push rule](../../user/project/repository/push_rules.md) to prevent this at the instance level. @@ -1643,7 +1650,7 @@ and a simple solution would be to enable relative URLs in the Registry. ### Enable the Registry debug server -You can use the Container Registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling. +You can use the container registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling. WARNING: Sensitive information may be available from the debug endpoint. @@ -1674,9 +1681,9 @@ was: - [Deprecated in GitLab 13.7](https://about.gitlab.com/releases/2020/12/22/gitlab-13-7-released/#deprecate-pulls-that-use-v1-of-the-docker-registry-api) - [Removed in GitLab 13.9](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#deprecate-pulls-that-use-v1-of-the-docker-registry-api) -It's no longer possible to push or pull v1 images from the GitLab Container Registry. +It's no longer possible to push or pull v1 images from the GitLab container registry. -If you had v1 images in the GitLab Container Registry, but you did not upgrade them (following the +If you had v1 images in the GitLab container registry, but you did not upgrade them (following the [steps Docker recommends](https://docs.docker.com/registry/spec/deprecated-schema-v1/)) ahead of the GitLab 13.9 upgrade, these images are no longer accessible. If you try to pull them, this error appears: @@ -1684,12 +1691,12 @@ this error appears: - `Error response from daemon: manifest invalid: Schema 1 manifest not supported` For self-managed GitLab instances, you can regain access to these images by temporarily downgrading -the GitLab Container Registry to a version lower than `v3.0.0-gitlab`. Follow these steps to regain +the GitLab container registry to a version lower than `v3.0.0-gitlab`. Follow these steps to regain access to these images: -1. Downgrade the Container Registry to [`v2.13.1-gitlab`](https://gitlab.com/gitlab-org/container-registry/-/releases/v2.13.1-gitlab). +1. Downgrade the container registry to [`v2.13.1-gitlab`](https://gitlab.com/gitlab-org/container-registry/-/releases/v2.13.1-gitlab). 1. Upgrade any v1 images. -1. Revert the Container Registry downgrade. +1. Revert the container registry downgrade. There's no need to put the registry in read-only mode during the image upgrade process. Ensure that you are not relying on any new feature introduced since `v3.0.0-gitlab`. Such features are @@ -1936,7 +1943,7 @@ Once the right permissions were set, the error goes away. ### Missing `gitlab-registry.key` prevents container repository deletion -If you disable your GitLab instance's Container Registry and try to remove a project that has +If you disable your GitLab instance's container registry and try to remove a project that has container repositories, the following error occurs: ```plaintext @@ -1945,7 +1952,7 @@ Errno::ENOENT: No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-r In this case, follow these steps: -1. Temporarily enable the instance-wide setting for the Container Registry in your `gitlab.rb`: +1. Temporarily enable the instance-wide setting for the container registry in your `gitlab.rb`: ```ruby gitlab_rails['registry_enabled'] = true diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index f84703b63e7..8098ed2e95b 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Dependency Proxy administration **(FREE SELF)** diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 2eb3da4b5d7..51641bf06ea 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -1,18 +1,18 @@ --- stage: Package group: Package Registry -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Package Registry administration **(FREE SELF)** +# GitLab package registry administration **(FREE SELF)** -To use GitLab as a private repository for a variety of common package managers, use the Package Registry. +To use GitLab as a private repository for a variety of common package managers, use the package registry. You can build and publish packages, which can be consumed as dependencies in downstream projects. ## Supported formats -The Package Registry supports the following formats: +The package registry supports the following formats: | Package type | GitLab version | |-------------------------------------------------------------------|----------------| @@ -55,11 +55,11 @@ guides you through the process. When downloading packages as dependencies in downstream projects, many requests are made through the Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you -can define specific rate limits for the Packages API. For more details, see [Package Registry Rate Limits](../settings/package_registry_rate_limits.md). +can define specific rate limits for the Packages API. For more details, see [package registry rate limits](../settings/package_registry_rate_limits.md). -## Enable or disable the Package Registry +## Enable or disable the package registry -The Package Registry is enabled by default. To disable it: +The package registry is enabled by default. To disable it: ::Tabs diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 97acbf717fe..0594c4b93bd 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages administration **(FREE SELF)** @@ -93,6 +93,41 @@ Where `example.io` is the domain GitLab Pages is served from, `192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. +#### For namespace in URL path, without wildcard DNS **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- Your instance must use the Linux package installation method. + +If you need support for namespace in the URL path to remove the requirement for wildcard DNS: + +1. Enable the GitLab Pages flag for this feature by adding + `gitlab_pages["namespace_in_path"] = true` to `/etc/gitlab/gitlab.rb`. +1. In your DNS provider, add entries for `example.com` and `projects.example.com`. + In both lines, replace `example.com` with your domain name, and `192.0.0.0` with + the IPv4 version of your IP address. The entries look like this: + + ```plaintext + example.com 1800 IN A 192.0.0.0 + projects.example.com 1800 IN A 192.0.0.0 + ``` + +1. Optional. If your GitLab instance has an IPv6 address, add entries for it. + In both lines, replace `example.com` with your domain name, and `2001:db8::1` with + the IPv6 version of your IP address. The entries look like this: + + ```plaintext + example.com 1800 IN AAAA 2001:db8::1 + projects.example.com 1800 IN AAAA 2001:db8::1 + ``` + #### DNS configuration for custom domains If support for custom domains is needed, all subdomains of the Pages root domain should point to the @@ -149,6 +184,46 @@ The Pages daemon doesn't listen to the outside world. Watch the [video tutorial](https://youtu.be/dD8c7WNcc6s) for this configuration. +### Pages domain without wildcard DNS **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +This configuration is the minimum setup for GitLab Pages. It is the base for all +other configurations. In this configuration, NGINX proxies all requests to the daemon, +because the GitLab Pages daemon doesn't listen to the outside world. + +Prerequisites: + +- Your instance must use the Linux package installation method. +- You have configured DNS setup + [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). + +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages, and enable + the feature flag: + + ```ruby + # External_url here is only for reference + external_url "http://example.com" + pages_external_url 'http://example.io' + + pages_nginx['enable'] = true + + # Set this flag to enable this feature + gitlab_pages["namespace_in_path"] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + +NGINX uses the custom proxy header `X-Gitlab-Namespace-In-Path` +to send the namespace to the GitLab Pages daemon. + +The resulting URL scheme is `http://example.io/<namespace>/<project_slug>`. + ### Wildcard domains with TLS support **Requirements:** @@ -163,7 +238,7 @@ URL scheme: `https://<namespace>.example.io/<project_slug>` NGINX proxies all requests to the daemon. Pages daemon doesn't listen to the outside world. -1. Place the wildcard LTS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. +1. Place the wildcard TLS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. 1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```ruby @@ -195,6 +270,68 @@ Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitl then run `gitlab-ctl reconfigure`. For more information, read [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). +### Pages domain with TLS support, without wildcard DNS **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- Your instance must use the Linux package installation method. +- You have configured DNS setup + [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). +- You have a single TLS certificate that covers your domain (like `example.com`) + and the `projects.*` version of your domain, like `projects.example.com`. + +In this configuration, NGINX proxies all requests to the daemon. The GitLab Pages +daemon doesn't listen to the outside world: + +1. Add your TLS certificate and key as mentioned in the prerequisites into `/etc/gitlab/ssl`. +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages, and enable + the feature flag: + + ```ruby + # The external_url field is here only for reference. + external_url "https://example.com" + pages_external_url 'https://example.io' + + pages_nginx['enable'] = true + pages_nginx['redirect_http_to_https'] = true + + # Set this flag to enable this feature + gitlab_pages["namespace_in_path"] = true + ``` + +1. If your TLS certificate and key don't match the name of your domain, like + `example.io.crt` and `example.io.key`, + add the full paths for the certificate and key files to `/etc/gitlab/gitlab.rb`: + + ```ruby + pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt" + pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key" + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + + WARNING: + GitLab Pages does not update the OAuth application if changes are made to the redirect URI. + Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`, + then run `gitlab-ctl reconfigure`. For more information, see + [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). + +1. If you're using [Pages Access Control](#access-control), update the redirect URI in the GitLab Pages + [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) + to use the HTTPS protocol. + +NGINX uses the custom proxy header `X-Gitlab-Namespace-In-Path` +to send the namespace to the GitLab Pages daemon. + +The resulting URL scheme is `https://example.io/<namespace>/<project_slug>`. + ### Wildcard domains with TLS-terminating Load Balancer **Requirements:** @@ -258,6 +395,7 @@ control over how the Pages daemon runs and serves content in your environment. | `gitlab_id` | The OAuth application public ID. Leave blank to automatically fill when Pages authenticates with GitLab. | | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. | | `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | +| `auth_timeout` | GitLab application client timeout for authentication in seconds (default: `5s`). A value of `0` means no timeout. | | `auth_cookie_session_timeout` | Authentication cookie session timeout in seconds (default: `10m`). A value of `0` means the cookie is deleted after the browser session ends. | | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | | `headers` | Specify any additional http headers that should be sent to the client with each response. Multiple headers can be given as an array, header and value as one string, for example `['my-header: myvalue', 'my-other-header: my-other-value']` | @@ -268,6 +406,7 @@ control over how the Pages daemon runs and serves content in your environment. | `log_directory` | Absolute path to a log directory. | | `log_format` | The log output format: `text` or `json`. | | `log_verbose` | Verbose logging, true/false. | +| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#for-namespace-in-url-path-without-wildcard-dns). Default: `false` | | `propagate_correlation_id` | Set to true (false by default) to re-use existing Correlation ID from the incoming request header `X-Request-ID` if present. If a reverse proxy sets this header, the value is propagated in the request chain. | | `max_connections` | Limit on the number of concurrent connections to the HTTP, HTTPS or proxy listeners. | | `max_uri_length` | The maximum length of URIs accepted by GitLab Pages. Set to 0 for unlimited length. [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5729) in GitLab 14.5. @@ -292,7 +431,7 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | | **`pages_nginx[]`** | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). | -| `FF_CONFIGURABLE_ROOT_DIR` | Feature flag to [customize the default folder](../../user/project/pages/introduction.md#customize-the-default-folder) (enabled by default). | +| `FF_CONFIGURABLE_ROOT_DIR` | Feature flag to [customize the default folder](../../user/project/pages/introduction.md#customize-the-default-folder) (enabled by default). | | `FF_ENABLE_PLACEHOLDERS` | Feature flag for rewrites (enabled by default). See [Rewrites](../../user/project/pages/redirects.md#rewrites) for more information. | | `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Removed in 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | | `rate_limit_source_ip` | Rate limit per source IP in number of requests per second. Set to `0` to disable this feature. | @@ -406,9 +545,8 @@ domain as a custom domain to their project. If your user base is private or otherwise trusted, you can disable the verification requirement: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Clear the **Require users to prove ownership of custom domains** checkbox. This setting is enabled by default. @@ -424,9 +562,8 @@ sites served under a custom domain. To enable it: 1. Choose an email address on which you want to receive notifications about expiring domains. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Enter the email address for receiving notifications and accept Let's Encrypt's Terms of Service. 1. Select **Save changes**. @@ -478,9 +615,8 @@ pre-existing applications must modify the GitLab Pages OAuth application. Follow this: 1. Enable [access control](#access-control). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications**. 1. Expand **GitLab Pages**. 1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example, `read_api`). @@ -498,13 +634,15 @@ This can be helpful to restrict information published with Pages websites to the of your instance only. To do that: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Select the **Disable public access to Pages sites** checkbox. 1. Select **Save changes**. +NOTE: +You must enable [Access Control](#access-control) first for the setting to show in the Admin Area. + ### Running behind a proxy Like the rest of GitLab, Pages can be used in those environments where external @@ -683,57 +821,56 @@ Follow the steps below to configure the proxy listener of GitLab Pages. ## Set global maximum size of each GitLab Pages site **(FREE SELF)** -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the global maximum pages size for a project: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. In **Maximum size of pages**, enter a value. The default is `100`. 1. Select **Save changes**. ## Set maximum size of each GitLab Pages site in a group **(PREMIUM SELF)** -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the maximum size of each GitLab Pages site in a group, overriding the inherited setting: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Pages**. 1. Enter a value under **Maximum size** in MB. 1. Select **Save changes**. ## Set maximum size of GitLab Pages site in a project **(PREMIUM SELF)** -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the maximum size of GitLab Pages site in a project, overriding the inherited setting: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. In **Maximum size of pages**, enter the size in MB. 1. Select **Save changes**. ## Set maximum number of GitLab Pages custom domains for a project -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the maximum number of GitLab Pages custom domains for a project: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**, and expand **Pages**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. +1. Expand **Pages**. 1. Enter a value for **Maximum number of custom domains per project**. Use `0` for unlimited domains. 1. Select **Save changes**. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index fcbc04ed0c3..4e88d4aa4f3 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages administration for self-compiled installations **(FREE SELF)** @@ -479,9 +479,8 @@ The default for the maximum size of unpacked archives per project is 100 MB. To change this value: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Update the value for **Maximum size of pages (MB)**. diff --git a/doc/administration/pages/troubleshooting.md b/doc/administration/pages/troubleshooting.md index be5b8ba27ee..7a93c8a0f76 100644 --- a/doc/administration/pages/troubleshooting.md +++ b/doc/administration/pages/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting GitLab Pages administration **(FREE SELF)** @@ -170,9 +170,8 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications > GitLab Pages**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications > GitLab Pages**. 1. Edit the application. 1. Under **Scopes**, ensure that the `api` scope is selected. 1. Save your changes. @@ -184,7 +183,7 @@ this setting needs to be configured on the main GitLab server. If the wildcard DNS [prerequisite](index.md#prerequisites) can't be met, you can still use GitLab Pages in a limited fashion: -1. [Move](../../user/project/settings/index.md#transfer-a-project-to-another-namespace) +1. [Move](../../user/project/settings/migrate_projects.md#transfer-a-project-to-another-namespace) all projects you need to use Pages with into a single group namespace, for example `pages`. 1. Configure a [DNS entry](index.md#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. 1. Configure `pages_external_url http://example.io/` in your `gitlab.rb` file. @@ -214,8 +213,7 @@ You may see this error if `pages_external_url` was updated at some point of time 1. Check the [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application): - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Applications** and then **Add new application**. 1. Ensure the **Callback URL/Redirect URI** is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. diff --git a/doc/administration/polling.md b/doc/administration/polling.md index b27613663da..5edba91165f 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Polling interval multiplier **(FREE SELF)** @@ -26,9 +26,8 @@ The default value (`1`) is recommended for the majority of GitLab installations. To adjust the polling interval multiplier: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Polling interval multiplier**. 1. Set a value for the polling interval multiplier. This multiplier is applied to all resources at once. diff --git a/doc/administration/postgresql/database_load_balancing.md b/doc/administration/postgresql/database_load_balancing.md index d640dbe9341..7ef4e2cbcd2 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Load Balancing **(FREE SELF)** diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md index b9bfda80b83..5b425075b9e 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab using an external PostgreSQL service **(FREE SELF)** @@ -51,6 +51,12 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance: sudo gitlab-ctl reconfigure ``` +1. Restart PostgreSQL to enable the TCP port: + + ```shell + sudo gitlab-ctl restart + ``` + ## Troubleshooting ### Resolve `SSL SYSCALL error: EOF detected` error diff --git a/doc/administration/postgresql/external_metrics.md b/doc/administration/postgresql/external_metrics.md index fc4c5652a18..8b849bc4e71 100644 --- a/doc/administration/postgresql/external_metrics.md +++ b/doc/administration/postgresql/external_metrics.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring and logging setup for external databases diff --git a/doc/administration/postgresql/external_upgrade.md b/doc/administration/postgresql/external_upgrade.md index 3e2c3b09853..97e1c5e2cb9 100644 --- a/doc/administration/postgresql/external_upgrade.md +++ b/doc/administration/postgresql/external_upgrade.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading external PostgreSQL databases diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index 4d73ba49846..07de9bcdcf1 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring PostgreSQL for scaling **(FREE SELF)** diff --git a/doc/administration/postgresql/moving.md b/doc/administration/postgresql/moving.md index 7c18297a175..f1d6ffb29f6 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving GitLab databases to a different PostgreSQL instance **(FREE SELF)** diff --git a/doc/administration/postgresql/multiple_databases.md b/doc/administration/postgresql/multiple_databases.md index 80f2f369428..2caa4f147c4 100644 --- a/doc/administration/postgresql/multiple_databases.md +++ b/doc/administration/postgresql/multiple_databases.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple Databases **(FREE SELF)** diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 7e46933113b..6bda0522b54 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with the bundled PgBouncer service **(FREE SELF)** diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 8403177952a..f4ed9d99b45 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL replication and failover for Linux package installations **(PREMIUM SELF)** @@ -275,7 +275,7 @@ gitlab_rails['auto_migrate'] = false consul['services'] = %w(postgresql) # START user configuration -# Please set the real values as explained in Required Information section +# Set the real values as explained in Required Information section # # Replace PGBOUNCER_PASSWORD_HASH with a generated md5 value postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH' @@ -427,7 +427,7 @@ authentication mode (`patroni['tls_client_mode']`), must each have the same valu consul['watchers'] = %w(postgresql) # START user configuration - # Please set the real values as explained in Required Information section + # Set the real values as explained in Required Information section # Replace CONSUL_PASSWORD_HASH with with a generated md5 value # Replace PGBOUNCER_PASSWORD_HASH with with a generated md5 value pgbouncer['users'] = { @@ -898,6 +898,12 @@ Stopping or restarting the Patroni service on the leader node triggers an automa ### Manual failover procedure for Patroni +WARNING: +In GitLab 16.5 and earlier, PgBouncer nodes do not automatically fail over alongside +Patroni nodes. PgBouncer services +[must be restarted manually](#pgbouncer-errors-error-running-command-gitlabctlerrorsexecutionerror-and-error-database-gitlabhq_production-is-not-paused) +for a successful switchover. + While Patroni supports automatic failover, you also have the ability to perform a manual one, where you have two slightly different options: @@ -920,7 +926,7 @@ For further details on this subject, see the #### Geo secondary site considerations -When a Geo secondary site is replicating from a primary site that uses `Patroni` and `PgBouncer`, [replicating through PgBouncer is not supported](https://github.com/pgbouncer/pgbouncer/issues/382#issuecomment-517911529). The secondary *must* replicate directly from the leader node in the `Patroni` cluster. When there is an automatic or manual failover in the `Patroni` cluster, you can manually re-point your secondary site to replicate from the new leader with: +When a Geo secondary site is replicating from a primary site that uses `Patroni` and `PgBouncer`, [replicating through PgBouncer is not supported](https://github.com/pgbouncer/pgbouncer/issues/382#issuecomment-517911529). The secondary _must_ replicate directly from the leader node in the `Patroni` cluster. When there is an automatic or manual failover in the `Patroni` cluster, you can manually re-point your secondary site to replicate from the new leader with: ```shell sudo gitlab-ctl replicate-geo-database --host=<new_leader_ip> --replication-slot=<slot_name> @@ -957,7 +963,7 @@ For further details, see [Patroni documentation on this subject](https://patroni ### Switching from repmgr to Patroni WARNING: -Switching from repmgr to Patroni is straightforward, the other way around is *not*. Rolling back from Patroni to repmgr can be complicated and may involve deletion of data directory. If you need to do that, contact GitLab support. +Switching from repmgr to Patroni is straightforward, the other way around is _not_. Rolling back from Patroni to repmgr can be complicated and may involve deletion of data directory. If you need to do that, contact GitLab support. You can switch an exiting database cluster to use Patroni instead of repmgr with the following steps: @@ -1011,7 +1017,7 @@ Here are a few key facts that you must consider before upgrading PostgreSQL: GitLab deployment is down for the duration of database upgrade or, at least, as long as your leader node is upgraded. This can be **a significant downtime depending on the size of your database**. -- Upgrading PostgreSQL creates a new data directory with a new control data. From the perspective of Petroni, this is a new cluster that needs to be bootstrapped again. Therefore, as part of the upgrade procedure, the cluster state (stored in Consul) is wiped out. After the upgrade is complete, Patroni bootstraps a new cluster. **This changes your _cluster ID_**. +- Upgrading PostgreSQL creates a new data directory with a new control data. From the perspective of Patroni, this is a new cluster that needs to be bootstrapped again. Therefore, as part of the upgrade procedure, the cluster state (stored in Consul) is wiped out. After the upgrade is complete, Patroni bootstraps a new cluster. **This changes your _cluster ID_**. - The procedures for upgrading leader and replicas are not the same. That is why it is important to use the right procedure on each node. @@ -1309,6 +1315,27 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>) [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. +### PgBouncer errors `Error running command: GitlabCtl::Errors::ExecutionError` and `ERROR: database gitlabhq_production is not paused` + +Due to a [known issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/8166) that +affects versions of GitLab prior to 16.5.0, the automatic failover of PgBouncer nodes does not +happen after a [Patroni switchover](#manual-failover-procedure-for-patroni). In this +example, GitLab failed to detect a paused database, then attempted to `RESUME` a +not-paused database: + +```plaintext +INFO -- : Running: gitlab-ctl pgb-notify --pg-database gitlabhq_production --newhost database7.example.com --user pgbouncer --hostuser gitlab-consul +ERROR -- : STDERR: Error running command: GitlabCtl::Errors::ExecutionError +ERROR -- : STDERR: ERROR: ERROR: database gitlabhq_production is not paused +``` + +To ensure a [Patroni switchover](#manual-failover-procedure-for-patroni) succeeds, +you must manually restart the PgBouncer service on all PgBouncer nodes with this command: + +```shell +gitlab-ctl restart pgbouncer +``` + ### Reinitialize a 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: diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md index d6f3460e255..b609400e91d 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone PostgreSQL for Linux package installations **(FREE SELF)** diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index ec28b6bee67..207dbc7b509 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrity check Rake task **(FREE SELF)** diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index a4b14b132db..f0cbd66c719 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2024-02-06' redirect_to: '../../update/deprecations.md#geo-housekeeping-rake-tasks' --- diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index a4d52899f21..3b9b7bdfa7a 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub import Rake task (deprecated) **(FREE SELF)** @@ -25,7 +25,7 @@ before/after the brackets. Also, some shells (for example, Zsh) can interpret th You can only import repositories that are in the namespace of the owner of the GitHub personal access token being used to import. For more information, see [issue 424105](https://gitlab.com/gitlab-org/gitlab/-/issues/424105). -Prerequisite: +Prerequisites: - At least the Maintainer role on the destination group to import to. diff --git a/doc/administration/raketasks/incoming_email.md b/doc/administration/raketasks/incoming_email.md index 6b9c27ed144..abd5f0e0a4d 100644 --- a/doc/administration/raketasks/incoming_email.md +++ b/doc/administration/raketasks/incoming_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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incoming email Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index d8909440ceb..0db18ca6460 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 724dcc2046a..3a136e773d9 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintenance Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index ba2a135cb01..95db4544f43 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Praefect Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 36013803999..001d8ec6f1d 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project import and export Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/service_desk_email.md b/doc/administration/raketasks/service_desk_email.md index 21b4050a93b..9e18d2fe6c8 100644 --- a/doc/administration/raketasks/service_desk_email.md +++ b/doc/administration/raketasks/service_desk_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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Desk email Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/smtp.md b/doc/administration/raketasks/smtp.md index 3cb161345cb..46df6b7a720 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SMTP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index a1826d3e5df..d5f998e35db 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads migrate Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index f86b4406a9e..225e65fae76 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads sanitize Rake tasks **(FREE SELF)** diff --git a/doc/administration/read_only_gitlab.md b/doc/administration/read_only_gitlab.md index adc6f42271c..f70e1379958 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Place GitLab into a read-only state **(FREE SELF)** diff --git a/doc/administration/redis/index.md b/doc/administration/redis/index.md index ad5aca37830..1ba51c588fe 100644 --- a/doc/administration/redis/index.md +++ b/doc/administration/redis/index.md @@ -1,8 +1,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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 82b9a33d2c6..b33db6ce957 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -1,8 +1,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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis replication and failover with the Linux package **(PREMIUM SELF)** diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index cfe5a3157d9..48a5fa8e20f 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -1,8 +1,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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 b9d00b92f95..9b66d3a81af 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -1,8 +1,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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone Redis using the Linux package **(FREE SELF)** diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index 5f0be709d78..0dcb19c1999 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -1,8 +1,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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Redis **(FREE SELF)** @@ -78,6 +77,11 @@ repl_backlog_first_byte_offset:0 repl_backlog_histlen:0 ``` +## High CPU usage on Redis instance + +High CPU usage on Redis instance can be cause by Sidekiq `BRPOP` calls. The `BRPOP` command is expensive and increases CPU usage on Redis. +Increase the [`SIDEKIQ_SEMI_RELIABLE_FETCH_TIMEOUT` environment variable](../environment_variables.md) to improve CPU usage on Redis. + ## Troubleshooting Sentinel If you get an error like: `Redis::CannotConnectError: No sentinels available.`, diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 2203f4b3a02..defc74b7e9e 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 10,000 users **(PREMIUM SELF)** @@ -168,6 +168,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 10,000 users: @@ -234,16 +236,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. +traffic to the application servers. + +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 362da0bd7c6..1296111a974 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 1,000 users **(FREE SELF)** diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index a5d44edf877..6520f63957b 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 25,000 users **(PREMIUM SELF)** @@ -168,6 +168,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 25,000 users: @@ -236,25 +238,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. - -The next question is how you will handle SSL in your environment. -There are several different options: +traffic to the application servers. -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index fb8b9d8de45..d3f53ce3e14 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 2,000 users **(FREE SELF)** @@ -101,6 +101,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 2,000 users: @@ -124,25 +126,12 @@ To set up GitLab and its components to accommodate up to 2,000 users: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. +traffic to the application servers. -The next question is how you will handle SSL in your environment. There are -several different options: - -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 73b0291ab95..c01564a3e7a 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 3,000 users **(PREMIUM SELF)** @@ -163,6 +163,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 3,000 users: @@ -224,25 +226,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. - -The next question is how you will handle SSL in your environment. -There are several different options: +traffic to the application servers. -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm @@ -441,7 +430,8 @@ topology with a [Redis Sentinel](https://redis.io/docs/manual/sentinel/) service start the failover procedure. NOTE: -Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service. +Multi-node Redis must be deployed in an odd number of 3 nodes or more to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, +such as a cloud provider service. Redis requires authentication if used with Sentinel. See [Redis Security](https://redis.io/docs/manual/security/) documentation for more @@ -463,7 +453,7 @@ to be used with GitLab. The following IPs will be used as an example: You can optionally use a [third party external service for the Redis instance](../redis/replication_and_failover_external.md#redis-as-a-managed-service-in-a-cloud-provider) with the following guidance: - A reputable provider or solution should be used for this. [Google Memorystore](https://cloud.google.com/memorystore/docs/redis/redis-overview) and [AWS ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) are known to work. -- Redis Cluster mode is specifically not supported, but Redis Standalone with HA is. +- Redis Cluster mode is specifically not supported, but Redis Standalone with HA (Redis Sentinel) **is** supported. For more information, see [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services). diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index ca39468a76e..92421a35273 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 50,000 users **(PREMIUM SELF)** @@ -168,6 +168,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 50,000 users: @@ -243,16 +245,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. +traffic to the application servers. + +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index e908565e27e..16a92944984 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 5,000 users **(PREMIUM SELF)** @@ -163,6 +163,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 5,000 users: @@ -224,25 +226,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. - -The next question is how you handle SSL in your environment. -There are several different options: +traffic to the application servers. -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index fcbfaf46009..c4827695716 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -1,8 +1,7 @@ --- -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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architectures **(FREE SELF)** @@ -19,7 +18,7 @@ the _total_ load that comes with such a user count based on real data along with However, it should be noted that in some cases, known heavy scenarios such as [large monorepos](#large-monorepos) or notable [additional workloads](#additional-workloads) may require adjustments to be made. -For each Reference Architecture, the details of what they have been tested against can be found respectively in the "Testing Methodology" section of each page. +For details about what each Reference Architecture has been tested against, see the "Testing Methodology" section of each page. ### GitLab package (Omnibus) @@ -73,7 +72,7 @@ load of what each architecture has been tested against under the "Testing Method comparing those values with what load you are expecting against your existing GitLab environment to help select the right Reference Architecture size. -Load is given in terms of Requests per Section (RPS) for each endpoint type (API, Web, Git). This information on your existing infrastructure +Load is given in terms of Requests per Second (RPS) for each endpoint type (API, Web, Git). This information on your existing infrastructure can typically be surfaced by most reputable monitoring solutions or in some other ways such as load balancer metrics. For example, on existing GitLab environments, [Prometheus metrics](../monitoring/prometheus/gitlab_metrics.md) such as `gitlab_transaction_duration_seconds` can be used to see this data. @@ -88,7 +87,7 @@ With standalone setups, especially single node environments, there are [various ### High Availability (HA) -High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. However, to achieve this is complex and the environments required can be sizable. +High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. However, to achieve this is complex, 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 have a bigger impact against more users. All the architectures in this range have HA built in by design for this reason. @@ -206,7 +205,7 @@ Before implementing a reference architecture, refer to the following requirement These reference architectures were built and tested on Google Cloud Platform (GCP) using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a lowest common denominator baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). +CPU platform as the lowest common denominator baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). Newer, similarly-sized CPUs are supported and may have improved performance as a result. ARM CPUs are supported for Linux package environments as well as for any [Cloud Provider services](#cloud-provider-services) where applicable. @@ -216,7 +215,7 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported disk types -As a general guidance, most standard disk types are expected to work for GitLab, but be aware of the following specific call outs: +As a general guidance, most standard disk types are expected to work for GitLab, but be aware of the following specific call-outs: - [Gitaly](../gitaly/index.md#disk-requirements) requires at least 8,000 input/output operations per second (IOPS) for read operations, and 2,000 IOPS for write operations. - We don't recommend the use of any disk types that are "burstable" due to inconsistent performance. @@ -226,7 +225,7 @@ Outside the above standard, disk types are expected to work for GitLab and the c ### 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: +their services, or self-managed (ESXi) that meet both: - The specifications detailed in each reference architecture. - Any requirements in this section. @@ -431,7 +430,7 @@ While we endeavour to try and have a good range of support for GitLab environmen [Running stateful components in Kubernetes, such as Gitaly Cluster, is not supported](https://docs.gitlab.com/charts/installation/#configure-the-helm-chart-to-use-external-stateful-data). -Gitaly Cluster is only supported on conventional virtual machines. Kubernetes enforces strict memory restrictions but Git memory usage is unpredictable, which +Gitaly Cluster is only supported on conventional virtual machines. Kubernetes enforces strict memory restrictions, but Git memory usage is unpredictable, which can cause sporadic OOM termination of Gitaly pods, leading to significant disruptions and potential data loss. For this reason and others, Gitaly is not tested or supported in Kubernetes. For more information, see [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127). @@ -709,6 +708,141 @@ scaling downwards. You should take an iterative approach when scaling downwards, ### Monitoring -There are numerous options available to monitor your infrastructure, as well as [GitLab itself](../monitoring/index.md), and you should refer to your chosen monitoring solution's documentation for more information. +There are numerous options available to monitor your infrastructure, as well as [GitLab itself](../monitoring/index.md), and you should refer to your selected monitoring solution's documentation for more information. Of note, the GitLab application is bundled with [Prometheus as well as various Prometheus compatible exporters](../monitoring/prometheus/index.md) that could be hooked into your solution. + +## Update history + +Below is a history of notable updates for the Reference Architectures (2021-01-01 onward, ascending order), which we aim to keep updated at least once per quarter. + +You can find a full history of changes [on the GitLab project](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&state=merged&label_name%5B%5D=Reference%20Architecture&label_name%5B%5D=documentation). + +**2023:** + +- [2023-12-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133457): Updated notes on Load Balancers to be more reflective that any reputable offering is expected to work. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133457): Expanded details on what each Reference Architecture is designed for, the testing methodology used as well as added details on how to scale environments. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Added expanded notes on disk types, object storage and monitoring. +- [2023-10-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Adjusted Sidekiq configuration example to use Linux Package role. +- [2023-10-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133835): Adjusted the Sidekiq recommendations to include a separate node for 2k and tweaks to instance type and counts for 3k and 5k. +- [2023-10-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132270): Added more expanded notes throughout to warn about the use of Large Monorepos and their impacts for increased awareness. +- [2023-10-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133258): Updated name of Task Runner pod to its new name of Toolbox. +- [2023-10-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132961): Expanded guidance on using an external service for Redis further, in particular for separated Cache and Persistent services with 10k and up. +- [2023-09-21](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132289): Expanded details on the challenges of running Gitaly in Kubernetes. +- [2023-09-20](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132275): Removed references to Grafana after deprecation and removal. +- [2023-08-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130470): Expanded section on Geo under the Decision Tree. +- [2023-08-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128529): Switch config example to use the Sidekiq role for Linux package. +- [2023-08-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128374): Fixed an AWS Machine type typo for the 50k architecture. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133457): Expand details on what each Reference Architecture is designed for, the testing methodology used as well as added details on how to scale environments. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Add expanded notes on disk types, object storage and monitoring. +- [2023-10-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Adjust Sidekiq configuration example to use Linux Package role. +- [2023-10-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133835): Adjust the Sidekiq recommendations to include a separate node for 2k and tweaks to instance type and counts for 3k and 5k. +- [2023-10-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132270): Add more expanded notes throughout to warn about the use of Large Monorepos and their impacts for increased awareness. +- [2023-10-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133258): Update name of Task Runner pod to its new name of Toolbox. +- [2023-10-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132961): Expand guidance on using an external service for Redis further, in particular for separated Cache and Persistent services with 10k and up. +- [2023-09-21](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132289): Expand details on the challenges of running Gitaly in Kubernetes. +- [2023-09-20](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132275): Remove references to Grafana after deprecation and removal. +- [2023-08-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130470): Expand section on Geo under the Decision Tree. +- [2023-08-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128529): Switch configuration example to use the Sidekiq role for Linux package. +- [2023-08-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128374): Fix an AWS Machine type typo for the 50k architecture. +- [2023-06-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125017): Update PostgreSQL configuration examples to remove a now unneeded setting to instead use the Linux package default. +- [2023-06-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125017): Add explicit example on main page that reflects Google Memorystore is recommended. +- [2023-06-11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122063): Fix IP examples for the 3k and 5k architectures. +- [2023-05-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121545): Expand notes on usage of external Cloud Provider Services and the recommendation of separated Redis servers for 10k environments and up. +- [2023-05-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119224): Update documentation to reflect correct requirement of Redis 6 instead of 5. +- [2023-04-28](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114877): Add a note that the Azure Active Directory authentication method is not supported for use with Azure PostgreSQL Flexible service. +- [2023-03-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114877): Add more details about known unsupported designs. +- [2023-03-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114872): Update Redis configuration examples for multi-node to have correct config to ensure all components can connect. +- [2023-03-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110784): Update Gitaly configuration examples to the new format. +- [2023-03-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114495): Update cost estimates to no longer include NFS VMs. +- [2023-02-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110379): Update Praefect configuration examples to the new format. +- [2023-02-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109798): Add examples of what automations may be considered additional workloads. +- [2023-02-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111018): Add a new 'Before you Start' section that gives more context about what's involved with running production software self-managed. Also added more details for Standalone setups and Cloud Provider services in the Decision Tree section. +- [2023-02-01](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110641): Switch to use more common "complex" terminology instead of less known "involved". +- [2023-01-31](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110328): Expand and centralize the requirements' section on the main page. +- [2023-01-26](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110183): Add notes on migrating Git Data from NFS, that object data is still supported on NFS and handling SSH keys correctly across multiple Rails nodes. + +**2022:** + +- [2022-12-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105451): Remove guidance for using NFS for Git data as support for this is now ended with `15.6` onwards. +- [2022-12-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106826): Add note to clarify difference between Amazon RDS Multi-AZ DB _cluster_ and _instance_, with the latter being supported. Also increase PostgreSQL max connections setting to new default of `500`. +- [2022-12-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106695): Update Sidekiq max concurrency configuration to match new default of `20`. +- [2022-11-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104236): Correct guidance for Praefect and Gitaly in reduced 3k architecture section that an odd number quorum is required. +- [2022-11-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103623): Add guidance on how to handle GitLab Secrets in Cloud Native Hybrids and further links to the GitLab Charts documentation. +- [2022-11-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103767): Fix a typo with Sidekiq configuration for the 10k architecture. +- [2022-11-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102746): Add guidance on large monorepos and additional workloads impact on performance. Also expanded Load Balancer guidance around SSL and a recommendation for least connection based routing methods. +- [2022-10-18](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100826): Adjust Object Storage guidance to make it clearer it's recommended over NFS. +- [2022-10-11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100305): Update guidance for Azure to recommend up to 2k only due to performance issues. +- [2022-09-27](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98204): Add Decision Tree section to help users better decide what architecture to use. +- [2022-09-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98263): Add explicit step to enable Incremental Logging when only Object Storage is being used. +- [2022-09-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98184): Expand guidance on recommended cloud providers and services. +- [2022-09-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97245): Expand Object Storage guidance and updated that NFS support for Git data ends with `15.6`. +- [2022-08-24](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96150): Add clearer note that Gitaly Cluster is not supported in Kubernetes. +- [2022-08-24](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96021): Add section on supported CPUs and types. +- [2022-08-18](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95713): Update architecture tables to be clearer for Object Storage support. +- [2022-08-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95185): Increase Cloud Native Hybrid pool specs for 2k architecture to ensure enough resources present for pods. Also increased Sidekiq worker count. +- [2022-08-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93493): Add note to use newer Gitaly check command from GitLab 15 and later. +- [2022-07-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93141): Move troubleshooting section to a more general location. +- [2022-07-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92144): Add guidance that Amazon Aurora is no longer compatible and not supported from GitLab 14.4.0 and later. +- [2022-07-07](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91943): Add call out not to remove the `default` section from Gitaly storages config as it's required. +- [2022-06-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86812): Move Incremental Logging guidance to separate section. +- [2022-04-29](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85856): Expand testing results' section with new regular pipelines. +- [2022-04-26](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85833): Update Praefect configuration to reflect setting name changes. +- [2022-04-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85231): Add missing setting to enable Object Storage correctly. +- [2022-04-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85107): Expand Cloud Native Hybrid guidance with AWS machine types. +- [2022-04-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84389): Add cost estimates for AWS and Azure. +- [2022-04-06](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84483): Update configuration examples for most components to be correctly included for Prometheus monitoring auto discovery. +- [2022-03-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81538): Expand validation and testing result's section with more clearly language and more detail. +- [2022-03-21](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83019): Add note that additional specs may be needed for Gitaly in some scenarios. +- [2022-03-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82087): Add guidance for preventing the GitLab KAS service running on nodes where not required. +- [2022-03-01](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81814): Fix a typo for Praefect TLS port in configuration examples. +- [2022-02-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81247): Add guidance to enable the Gitaly Pack-objects cache. +- [2022-02-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80892): Add a general section on recommended Cloud Providers and services. +- [2022-02-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80521): Link to blog post about GPT testing added. +- [2022-01-26](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78705): Merge testing process and cost estimates into one section with expanded details. +- [2022-01-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77968): Expand guidance on recommended Kubernetes platforms. + +**2021:** + +- [2021-12-31](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77437): Fix typo for 25k Redis AWS machine size. +- [2021-12-28](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77243): Add Cloud Provider breakdowns to testing process & results section. +- [2021-12-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77039): Add more detail to testing process and results section. +- [2021-12-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77002): Add note on Database Load Balancing requirements when using a modified 3k architecture. +- [2021-12-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76236): Add diagram for 1k architecture (single node). +- [2021-12-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76748): Add sections on estimated costs (GCP), testing process and results and further Cloud Provider service details. +- [2021-12-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76226): Expand external database service guidance for components and what Cloud Provider services are recommended. +- [2021-11-24](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74612): Add recommendations for Database Load Balancing. +- [2021-11-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73634): Add more detail about testing targets used for the architectures. +- [2021-10-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72052): Add guidance around optionally enabling Incremental Logging via Redis. +- [2021-10-07](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71784): Update Sidekiq config to include required `external_url` setting. +- [2021-10-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71576): Expand guidance around Gitaly Cluster and Gitaly Sharded. +- [2021-09-29](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70625): Add note on what Cloud Native Hybrid architecture to use with small user counts. +- [2021-09-27](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70602): Change guidance to now co-locate Redis Sentinel beside Redis on the same node. +- [2021-08-18](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67778): Add 2k Cloud Native Hybrid architecture. +- [2021-08-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67463): Add links to performance test results for each architecture. +- [2021-07-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67231): Fix the replication settings in PostgreSQL configuration examples to have correct values. +- [2021-07-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66185): Add 3k Cloud Native Hybrid architecture. +- [2021-07-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66278): Update architecture diagrams to correctly reflect no direct connection between Rails and Sidekiq. +- [2021-07-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65373): Update Patroni configuration to include Rest API authentication settings. +- [2021-07-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65992): Add 5k Cloud Native Hybrid architecture. +- [2021-07-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65154): Add 25k Cloud Native Hybrid architecture. +- [2021-06-29](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64711): Add 50k Cloud Native Hybrid architecture. +- [2021-06-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64612): Make additions to main page for Cloud Native Hybrid and reduce 3k architecture. +- [2021-06-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63580): Update PostgreSQL steps and configuration to use the latest roles and prep for any Geo replication. +- [2021-06-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63857): Update configuration examples for Monitoring node to follow latest. +- [2021-06-11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62316): Expand notes on external services with more detail. +- [2021-06-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63504): Add additional guidance and expand on how to correctly manage GitLab secrets and database migrations. +- [2021-06-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63443): Update Praefect configuration examples to follow the new storages format. +- [2021-06-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61923): Removed references for the Unicorn webserver, which has been replaced by Puma. +- [2021-04-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59471): Update Sidekiq configuration examples to show how to correctly configure multiple workers on each node. +- [2021-04-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59283): Add initial guidance on how to modify the 3k Reference Architecture for lower user counts. +- [2021-04-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59259): Add further clarification on using external services (PostgreSQL, Redis). +- [2021-04-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59139): Add additional guidance on using Load Balancers and their routing methods. +- [2021-04-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58885): Add additional guidance on how to correctly configure only one node to do database migrations for Praefect. +- [2021-04-06](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57476): Expand 10k Cloud Native Hybrid documentation with more details and clear naming. +- [2021-03-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54454): Expand Gitaly Cluster documentation to all other applicable Reference Architecture sizes. +- [2021-02-19](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54244): Add additional Object Storage guidance of using separated buckets for different data types as per recommendations. +- [2021-02-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50852): Add documentation for setting up Object Storage with Rails and Sidekiq. +- [2021-02-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51928): Add documentation for setting up Gitaly Cluster for the 10k Reference Architecture. +- [2021-02-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52249): Add the first iteration of the 10k Cloud Native Hybrid reference architecture. +- [2021-01-07](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50573): Add documentation for using Patroni as PostgreSQL replication manager. diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index b632108b103..d6c1f74fda8 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reply by email **(FREE SELF)** diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index ef6fd82a460..99cfbd59c49 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Postfix for incoming email **(FREE SELF)** diff --git a/doc/administration/reporting/git_abuse_rate_limit.md b/doc/administration/reporting/git_abuse_rate_limit.md index 7e2c340f20d..19818a818ac 100644 --- a/doc/administration/reporting/git_abuse_rate_limit.md +++ b/doc/administration/reporting/git_abuse_rate_limit.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git abuse rate limit (administration) **(ULTIMATE SELF)** @@ -21,8 +21,7 @@ GitLab team members can view more information in this confidential epic: ## Configure Git abuse rate limiting -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand **Git abuse rate limit**. 1. Update the Git abuse rate limit settings: @@ -41,8 +40,7 @@ If automatic banning is enabled, an email notification is sent when a user is ab ## Unban a user -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Banned** tab and search for the account you want to unban. 1. From the **User administration** dropdown list select **Unban user**. diff --git a/doc/administration/reporting/ip_addr_restrictions.md b/doc/administration/reporting/ip_addr_restrictions.md index 2e152b0b176..434052344d8 100644 --- a/doc/administration/reporting/ip_addr_restrictions.md +++ b/doc/administration/reporting/ip_addr_restrictions.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # IP address restrictions **(FREE SELF)** @@ -19,8 +19,7 @@ unique IP addresses. Therefore, the IP addresses per user limit should take into ## Configure IP address restrictions -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Update the IP address restrictions settings: diff --git a/doc/administration/reporting/spamcheck.md b/doc/administration/reporting/spamcheck.md index c92336a39b9..4ba36e33abb 100644 --- a/doc/administration/reporting/spamcheck.md +++ b/doc/administration/reporting/spamcheck.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Spamcheck anti-spam service **(FREE SELF)** @@ -40,8 +40,7 @@ Spamcheck is only available for package-based installations: ## Configure GitLab to use Spamcheck -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Update the Spam Check settings: diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 241f88793ff..85a74199022 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository checks **(FREE SELF)** @@ -20,9 +20,8 @@ committed to a repository. GitLab administrators can: To check a project's repository using GitLab UI: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Projects**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Projects**. 1. Select the project to check. 1. In the **Repository check** section, select **Trigger repository check**. @@ -33,10 +32,9 @@ project page in the Admin Area. If the checks fail, see [what to do](#what-to-do Instead of checking repositories manually, GitLab can be configured to run the checks periodically: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). -1. Expand the **Repository maintenance** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **Repository maintenance**. 1. Enable **Enable repository checks**. When enabled, GitLab periodically runs a repository check on all project repositories and wiki @@ -87,10 +85,9 @@ If a repository check fails, locate the error in the [`repocheck.log` file](logs If periodic repository checks cause false alarms, you can clear all repository check states: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). -1. Expand the **Repository maintenance** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **Repository maintenance**. 1. Select **Clear all repository checks**. ## Troubleshooting diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index a3e0158fd24..efa719d103b 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage **(FREE SELF)** @@ -66,9 +66,8 @@ Administrators can look up a project's hashed path from its name or ID using: To look up a project's hash path in the Admin Area: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Projects** and select the project. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Projects** and select the project. 1. Locate the **Relative path** field. The value is similar to: ```plaintext @@ -180,7 +179,7 @@ Files stored in an S3-compatible endpoint can have the same advantages as #### Avatars Each file is stored in a directory that matches the `id` assigned to it in the database. The -filename is always `avatar.png` for user avatars. When an avatar is replaced, the `Upload` model is +file name is always `avatar.png` for user avatars. When an avatar is replaced, the `Upload` model is destroyed and a new one takes place with a different `id`. #### CI/CD artifacts @@ -205,10 +204,9 @@ LFS objects are also [S3-compatible](lfs/index.md#storing-lfs-objects-in-remote- After you configure multiple repository storages, you can choose where new repositories are stored: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository** and expand the **Repository storage** - section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **Repository storage**. 1. Enter values in the **Storage nodes for new repositories** fields. 1. Select **Save changes**. diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index d0e4beccb3a..6cd9af0731a 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to restart GitLab **(FREE SELF)** diff --git a/doc/administration/review_abuse_reports.md b/doc/administration/review_abuse_reports.md index 84bb7ab219f..86953f6d984 100644 --- a/doc/administration/review_abuse_reports.md +++ b/doc/administration/review_abuse_reports.md @@ -1,8 +1,7 @@ --- stage: Govern group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review abuse reports **(FREE SELF)** @@ -16,8 +15,7 @@ reports in the Admin Area. To receive notifications of new abuse reports by email: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address and select **Save changes**. @@ -36,8 +34,7 @@ To find out more about reporting abuse, see To access abuse reports: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Abuse Reports**. There are four ways to resolve an abuse report, with a button for each method: diff --git a/doc/administration/review_spam_logs.md b/doc/administration/review_spam_logs.md index e3b96cdae95..67f6080b3bc 100644 --- a/doc/administration/review_spam_logs.md +++ b/doc/administration/review_spam_logs.md @@ -1,8 +1,7 @@ --- stage: Govern group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review spam logs **(FREE SELF)** @@ -19,8 +18,7 @@ View and resolve spam logs to moderate user activity in your instance. To view spam logs: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Spam Logs**. 1. Optional. To resolve a spam log, select a log and then select **Remove user**, **Block user**, **Remove log**, or **Trust user**. diff --git a/doc/administration/secure_files.md b/doc/administration/secure_files.md index 6c61c390655..d3dfe4fdf4c 100644 --- a/doc/administration/secure_files.md +++ b/doc/administration/secure_files.md @@ -1,7 +1,7 @@ --- stage: Mobile group: Mobile DevOps -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure Files administration **(FREE SELF)** @@ -30,7 +30,7 @@ Secure Files to reduce disk space, or to remove access to the feature. To disable Secure Files, follow the steps below according to your installation. -Prerequisite: +Prerequisites: - You must be an administrator. diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 4d8377b4117..562c8547d90 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git server hooks **(FREE SELF)** @@ -18,8 +18,13 @@ on the GitLab server. You can use them to run Git-related tasks such as: Git server hooks use `pre-receive`, `post-receive`, and `update` [Git server-side hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_server_side_hooks). -GitLab administrators configure server hooks on the file system of the GitLab server. If you don't have file system access, -alternatives to server hooks include: +GitLab administrators configure server hooks using the `gitaly` command, which also: + +- Is used to launch a Gitaly server. +- Provides several subcommands. +- Connects to the Gitaly gRPC API. + +If you don't have access to the `gitaly` command, alternatives to server hooks include: - [Webhooks](../user/project/integrations/webhooks.md). - [GitLab CI/CD](../ci/index.md). @@ -49,7 +54,7 @@ To set server hooks for a repository: example, if the script is in Ruby the shebang is probably `#!/usr/bin/env ruby`. - To create a single server hook, create a file with a name that matches the hook type. For example, for a - `pre-receive` server hook, the filename should be `pre-receive` with no extension. + `pre-receive` server hook, the file name should be `pre-receive` with no extension. - To create many server hooks, create a directory for the hooks that matches the hook type. For example, for a `pre-receive` server hook, the directory name should be `pre-receive.d`. Put the files for the hook in that directory. @@ -71,8 +76,7 @@ If you implemented the server hook code correctly, it should execute when the Gi To create server hooks for a repository: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Go to **Overview > Projects** and select the project you want to add a server hook to. 1. On the page that appears, locate the value of **Relative path**. This path is where server hooks must be located. @@ -85,7 +89,7 @@ To create server hooks for a repository: 1. On the file system, create a new directory in the correct location called `custom_hooks`. 1. In the new `custom_hooks` directory: - To create a single server hook, create a file with a name that matches the hook type. For example, for a - `pre-receive` server hook, the filename should be `pre-receive` with no extension. + `pre-receive` server hook, the file name should be `pre-receive` with no extension. - To create many server hooks, create a directory for the hooks that matches the hook type. For example, for a `pre-receive` server hook, the directory name should be `pre-receive.d`. Put the files for the hook in that directory. 1. **Make the server hook files executable** and ensure that they are owned by the Git user. @@ -156,7 +160,7 @@ To create a global server hook for all repositories: 1. Make the hook file executable, ensure that it's owned by the Git user, and ensure it does not match the backup file pattern (`*~`). -If the server hook code is properly implemented, it should execute when the Git hook is next triggered. Hooks are executed in alphabetical order by filename in the hook type +If the server hook code is properly implemented, it should execute when the Git hook is next triggered. Hooks are executed in alphabetical order by file name in the hook type subdirectories. ## Remove server hooks for a repository diff --git a/doc/administration/settings/account_and_limit_settings.md b/doc/administration/settings/account_and_limit_settings.md index b33ceb2c4e5..d8e2ca38627 100644 --- a/doc/administration/settings/account_and_limit_settings.md +++ b/doc/administration/settings/account_and_limit_settings.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Account and limit settings **(FREE SELF)** @@ -16,8 +15,7 @@ the [project limits for existing users](#projects-limit-for-a-user). To configure the maximum number of projects in personal namespaces for new users: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Increase or decrease that **Default projects limit** value. @@ -30,8 +28,7 @@ in their users personal namespace. However, projects can still be created in a g You can edit a specific user, and change the maximum number of projects this user can create in their personal namespace: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview** > **Users**. 1. From the list of users, select a user. 1. Select **Edit**. @@ -44,8 +41,7 @@ can create in their personal namespace: The maximum file size for attachments in GitLab comments and replies is 100 MB. To change the maximum attachment size: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MiB)**. @@ -60,8 +56,7 @@ For GitLab.com repository size limits, read [accounts and limit settings](../../ You can change the maximum push size for your instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum push size (MiB)**. @@ -92,8 +87,7 @@ The default prefix is `glpat-` but administrators can change it. To change the default global prefix: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Personal Access Token prefix** field. @@ -139,8 +133,7 @@ These settings can be found in: 1. Fill in the **Repository size limit (MiB)** field in the **Naming, visibility** section. 1. Select **Save changes**. - GitLab global settings: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MiB)** field. @@ -162,8 +155,7 @@ For details on manually purging files, see [reducing the repository size using G You can change how long users can remain signed in without activity. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. The set duration is in **Session duration (minutes)**. @@ -177,8 +169,7 @@ For details, see [cookies used for sign-in](../../user/profile/index.md#cookies- Users can select the **Remember me** checkbox on sign-in, and their session will remain active for an indefinite period of time when accessed from that specific browser. You can turn off this setting if you need sessions to expire for security or compliance purposes. Turning off this setting will ensure users' sessions expire after the number of minutes of inactivity set when you [customize your session duration](#customize-the-default-session-duration). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select or clear the **Remember me** checkbox to turn this setting on or off. @@ -195,8 +186,7 @@ GitLab administrators can choose to customize the session duration (in minutes) To set a limit on how long these sessions are valid: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. @@ -223,8 +213,7 @@ there are no restrictions. To set a lifetime on how long SSH keys are valid: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for SSH keys (days)** field. @@ -260,8 +249,7 @@ there are no restrictions. To set a lifetime on how long access tokens are valid: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for access tokens (days)** field. @@ -283,8 +271,7 @@ To maintain integrity of user details in [Audit Events](../../administration/aud To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select the **Prevent users from changing their profile name** checkbox. @@ -294,6 +281,20 @@ When this ability is disabled, GitLab administrators can still use the [Admin Area](../../administration/admin_area.md#administering-users) or the [API](../../api/users.md#user-modification) to update usernames. +## Prevent users from creating organizations **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423302) in GitLab 16.7 [with a flag](../feature_flags.md) named `ui_for_organizations`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../feature_flags.md) named `ui_for_organizations`. On GitLab.com, this feature is not available. This feature is not ready for production use. + +By default, users can create organizations. GitLab administrators can prevent users from creating organizations. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Account and limit**. +1. Clear the **Allow users to create organizations** checkbox. + ## Prevent new users from creating top-level groups > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. @@ -305,8 +306,7 @@ By default, new users can create top-level groups. GitLab administrators can pre - The [application setting API](../../api/settings.md#change-application-settings). - In GitLab 15.4 and earlier, a [configuration file](../../administration/user_settings.md#use-configuration-files-to-prevent-new-users-from-creating-top-level-groups). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Clear the **Allow new users to create top-level groups** checkbox. @@ -317,8 +317,7 @@ By default, new users can create top-level groups. GitLab administrators can pre By default, newly created users have a public profile. GitLab administrators can set new users to have a private profile by default: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select the **Make new users' profiles private by default** checkbox. @@ -330,8 +329,7 @@ By default, newly created users have a public profile. GitLab administrators can By default, users can delete their own accounts. GitLab administrators can prevent users from deleting their own accounts: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Clear the **Allows users to delete their own accounts** checkbox. diff --git a/doc/administration/settings/continuous_integration.md b/doc/administration/settings/continuous_integration.md index 0e2a512302d..8164c63b9b9 100644 --- a/doc/administration/settings/continuous_integration.md +++ b/doc/administration/settings/continuous_integration.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Continuous Integration and Deployment Admin Area settings **(FREE SELF)** @@ -15,8 +14,7 @@ job artifacts. To enable (or disable) [Auto DevOps](../../topics/autodevops/index.md) for all projects: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. 1. Optionally, set up the [Auto DevOps base domain](../../topics/autodevops/requirements.md#auto-devops-base-domain) @@ -33,8 +31,7 @@ If you want to disable it for a specific project, you can do so in You can set all new projects to have the instance's shared runners available by default. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Select the **Enable shared runners for new projects** checkbox. @@ -53,8 +50,7 @@ you can assign that runner to other projects. To enable a project runner for more than one project: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. 1. In the upper-right corner, select **Edit** (**{pencil}**). @@ -67,8 +63,7 @@ To enable a project runner for more than one project: To display details about the instance's shared runners in all projects' runner settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Enter text, including Markdown if you want, in the **Shared runner details** field. For example: @@ -97,8 +92,7 @@ The value is in MB, and the default is 100 MB per job. An administrator can chan - Instance level: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > CI/CD > Continuous Integration and Deployment**. 1. Change the value of **Maximum artifacts size (MB)**. 1. Select **Save changes** for the changes to take effect. @@ -112,7 +106,7 @@ The value is in MB, and the default is 100 MB per job. An administrator can chan - Project level (this overrides the instance and group settings): 1. Go to the project's **Settings > CI/CD > General Pipelines**. - 1. Change the value of **maximum artifacts size** (in MB). + 1. Change the value of **Maximum artifacts size** (in MB). 1. Select **Save changes** for the changes to take effect. ## Default artifacts expiration @@ -122,8 +116,7 @@ can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../ci/yaml/index.md#artifactsexpire_in) and the default value is `30 days`. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Select **Save changes** for the changes to take effect. @@ -154,8 +147,7 @@ If disabled at the instance level, you cannot enable this per-project. To disable the setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. @@ -178,8 +170,7 @@ blueprint for more details. To set the duration for which the jobs are considered as old and expired: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. @@ -196,8 +187,7 @@ For the value set for GitLab.com, see [Scheduled job archiving](../../user/gitla To set all new [CI/CD variables](../../ci/variables/index.md) as [protected](../../ci/variables/index.md#protect-a-cicd-variable) by default: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Select **Protect CI/CD variables by default**. @@ -208,8 +198,7 @@ To set all new [CI/CD variables](../../ci/variables/index.md) as The maximum number of [includes](../../ci/yaml/includes.md) per pipeline can be set at the instance level. The default is `150`. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Change the value of **Maximum includes**. 1. Select **Save changes** for the changes to take effect. @@ -221,8 +210,7 @@ The default is `150`. The default CI/CD configuration file and path for new projects can be set in the Admin Area of your GitLab instance (`.gitlab-ci.yml` if not set): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Input the new file and path in the **Default CI/CD configuration file** field. 1. Select **Save changes** for the changes to take effect. @@ -237,8 +225,7 @@ It is also possible to specify a [custom CI/CD configuration file for a specific You can configure some [CI/CD limits](../../administration/instance_limits.md#cicd-limits) from the Admin Area: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. In the **CI/CD limits** section, you can set the following limits: @@ -260,8 +247,7 @@ walkthrough on how to add one. To enable or disable the banner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Select or clear the **Enable pipeline suggestion banner** checkbox. 1. Select **Save changes**. @@ -276,8 +262,7 @@ malicious user-generated content, as described in Self-managed administrators can disable the external redirect warning page, so you can view job artifact pages directly: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Deselect **Enable the external redirect page for job artifacts**. @@ -313,14 +298,13 @@ in the pipeline editor. To select a CI/CD template for the required pipeline configuration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select a CI/CD template from the dropdown list. 1. Select **Save changes**. -## Package Registry configuration +## Package registry configuration ### Maven Forwarding **(PREMIUM SELF)** @@ -328,8 +312,7 @@ GitLab administrators can disable the forwarding of Maven requests to [Maven Cen To disable forwarding Maven requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward Maven package requests to the Maven Registry if the packages are not found in the GitLab Package Registry**. @@ -341,8 +324,7 @@ GitLab administrators can disable the forwarding of npm requests to [npmjs.com]( To disable it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. @@ -354,8 +336,7 @@ GitLab administrators can disable the forwarding of PyPI requests to [pypi.org]( To disable it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. @@ -367,8 +348,7 @@ GitLab administrators can adjust the maximum allowed file size for each package To set the maximum file size: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. @@ -388,8 +368,7 @@ By default, all members of a project and group are able to register runners. To restrict all users in an instance from registering runners: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Runner registration** section, clear the **Members of the project can register runners** and @@ -411,8 +390,7 @@ GitLab administrators can adjust group permissions to restrict runner registrati To restrict runner registration by members in a specific group: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Groups** and find your group. 1. Select **Edit**. 1. Clear the **New group runners can be registered** checkbox if you want to disable runner registration by all members in the group. If the setting is read-only, you must enable runner registration for the [instance](#restrict-runner-registration-by-all-users-in-an-instance). @@ -426,8 +404,7 @@ By default, GitLab instances periodically fetch official runner version data fro To disable your instance fetching this data: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Runner version management** section, clear the **Fetch GitLab Runner release version data from GitLab.com** checkbox. @@ -435,11 +412,16 @@ To disable your instance fetching this data: ## Troubleshooting -### 413 Request Entity Too Large +### `413 Request Entity Too Large` error -When build jobs fail with the following error, -increase the [maximum artifacts size](#maximum-artifacts-size). +If the artifacts are too large, the job might fail with the following error: ```plaintext Uploading artifacts as "archive" to coordinator... too large archive <job-id> responseStatus=413 Request Entity Too Large status=413" at end of a build job on pipeline when trying to store artifacts to <object-storage>. ``` + +You might need to: + +- Increase the [maximum artifacts size](#maximum-artifacts-size). +- If you are using NGINX as a proxy server, increase the file upload size limit which is limited to 1 MB by default. + Set a higher value for `client-max-body-size` in the NGINX configuration file. diff --git a/doc/administration/settings/deprecated_api_rate_limits.md b/doc/administration/settings/deprecated_api_rate_limits.md index 21385a6779d..2ef4d49ff0a 100644 --- a/doc/administration/settings/deprecated_api_rate_limits.md +++ b/doc/administration/settings/deprecated_api_rate_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deprecated API rate limits **(FREE SELF)** @@ -28,14 +27,13 @@ the general user and IP rate limits for requests to deprecated endpoints. You ca and IP rate limits already in place, and increase or decrease the rate limits for deprecated API endpoints. No other new features are provided by this override. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To override the general user and IP rate limits for requests to deprecated API endpoints: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Deprecated API Rate Limits**. 1. Select the checkboxes for the types of rate limits you want to enable: diff --git a/doc/administration/settings/email.md b/doc/administration/settings/email.md index bcf4bab6fc5..cc80b082139 100644 --- a/doc/administration/settings/email.md +++ b/doc/administration/settings/email.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Email **(FREE SELF)** @@ -21,8 +20,7 @@ address in the body of the email instead. To include the author's email address in the email body: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Select the **Include author name in email notification email body** checkbox. @@ -34,8 +32,7 @@ GitLab can send email in multipart format (HTML and plain text) or plain text on To enable multipart email: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Select **Enable multipart email**. @@ -50,8 +47,7 @@ This configuration option sets the email hostname for [private commit emails](.. To change the hostname used in private commit emails: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. @@ -69,8 +65,7 @@ can be used for legal, auditing, or compliance reasons, for example. To add additional text to emails: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter your text in the **Additional text** field. @@ -82,8 +77,7 @@ GitLab sends email notifications to users when their account has been deactivate To disable these notifications: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Clear the **Enable user deactivation emails** checkbox. @@ -106,8 +100,7 @@ setting. To add additional text to deactivation emails: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter your text in the **Additional text for deactivation email** field. diff --git a/doc/administration/settings/external_authorization.md b/doc/administration/settings/external_authorization.md index 3ddebeb983c..95ce7963bb7 100644 --- a/doc/administration/settings/external_authorization.md +++ b/doc/administration/settings/external_authorization.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External authorization control **(FREE SELF)** @@ -45,8 +45,7 @@ Alternatively, learn where to install custom certificates by using The external authorization service can be enabled by an administrator: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **External authorization**. 1. Complete the fields. @@ -66,8 +65,7 @@ Prerequisites: To allow authorization with deploy tokens and keys: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **External authorization**, and: - Leave the service URL field empty. diff --git a/doc/administration/settings/files_api_rate_limits.md b/doc/administration/settings/files_api_rate_limits.md index 025f8c86993..4764341b932 100644 --- a/doc/administration/settings/files_api_rate_limits.md +++ b/doc/administration/settings/files_api_rate_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Repository files API **(FREE SELF)** @@ -24,14 +23,13 @@ the general user and IP rate limits for requests to the and IP rate limits already in place, and increase or decrease the rate limits for the Files API. No other new features are provided by this override. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To override the general user and IP rate limits for requests to the Repository files API: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Files API Rate Limits**. 1. Select the checkboxes for the types of rate limits you want to enable: diff --git a/doc/administration/settings/floc.md b/doc/administration/settings/floc.md index f461472bfe7..499b1d9c82f 100644 --- a/doc/administration/settings/floc.md +++ b/doc/administration/settings/floc.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Federated Learning of Cohorts (FLoC) **(FREE SELF)** @@ -22,8 +22,7 @@ Permissions-Policy: interest-cohort=() To enable it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Federated Learning of Cohorts (FLoC)**. 1. Select the **Participate in FLoC** checkbox. diff --git a/doc/administration/settings/git_lfs_rate_limits.md b/doc/administration/settings/git_lfs_rate_limits.md index acd3945750f..4e096e52f41 100644 --- a/doc/administration/settings/git_lfs_rate_limits.md +++ b/doc/administration/settings/git_lfs_rate_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Git LFS **(FREE SELF)** @@ -21,8 +20,7 @@ rate limits. Git LFS rate limits are disabled by default. If enabled and configured, these limits supersede the [general user and IP rate limits](../settings/user_and_ip_rate_limits.md): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Git LFS Rate Limits**. 1. Select **Enable authenticated Git LFS request rate limit**. diff --git a/doc/administration/settings/gitaly_timeouts.md b/doc/administration/settings/gitaly_timeouts.md index 1cab1e9fd01..b35ee32a3e9 100644 --- a/doc/administration/settings/gitaly_timeouts.md +++ b/doc/administration/settings/gitaly_timeouts.md @@ -1,29 +1,80 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly timeouts **(FREE SELF)** -[Gitaly](../gitaly/index.md) timeouts are configurable. The timeouts can be -configured to make sure that long-running Gitaly calls don't needlessly take up resources. +[Gitaly](../gitaly/index.md) provides two types of configurable timeouts: -To access Gitaly timeout settings: +- Call timeouts, configured by using the GitLab UI. +- Negotiation timeouts, configured by using Gitaly configuration files. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +## Configure the call timeouts + +Configure the following call timeouts to make sure that long-running Gitaly calls don't needlessly take up resources. To +configure the call timeouts: + +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand the **Gitaly timeouts** section. +1. Set each timeout as required. -## Available timeouts +### Available call timeouts -The following timeouts are available. +Different call timeouts are available for different Gitaly operations. | Timeout | Default | Description | |:--------|:-----------|:------------| -| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../operations/puma.md#change-the-worker-timeout) that can be configured for [Puma](../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | -| Fast | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | -| Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast. | +| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made in a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../operations/puma.md#change-the-worker-timeout) that can be configured for [Puma](../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | +| Fast | 10 seconds | Timeout for fast Gitaly operations used in requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | +| Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly in requests) but preferably not used multiple times in a request. For example, loading blobs. Timeout that should be set between Default and Fast. | + +## Configure the negotiation timeouts + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5574) in GitLab 16.5. + +You might need to increase the negotiation timeout: + +- For particularly large repositories. +- When performing these commands in parallel. + +You can configure negotiation timeouts for: + +- `git-upload-pack(1)`, which is invoked by a Gitaly node when you execute `git fetch`. +- `git-upload-archive(1)`, which is invoked by a Gitaly node when you execute `git archive --remote`. + +To configure these timeouts: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +Edit `/etc/gitlab/gitlab.rb`: + +```ruby +gitaly['configuration'] = { + timeout: { + upload_pack_negotiation: '10m', # 10 minutes + upload_archive_negotiation: '20m', # 20 minutes + } +} +``` + +:::TabTitle Self-compiled (source) + +Edit `/home/git/gitaly/config.toml`: + +```toml +[timeout] +upload_pack_negotiation = "10m" +upload_archive_negotiation = "20m" +``` + +::EndTabs + +For the values, use the format of [`ParseDuration`](https://pkg.go.dev/time#ParseDuration) in Go. -You can also [configure negotiation timeouts](../gitaly/configure_gitaly.md#configure-negotiation-timeouts). +These timeouts affect only the [negotiation phase](https://git-scm.com/docs/pack-protocol/2.2.3#_packfile_negotiation) of +remote Git operations, not the entire transfer. diff --git a/doc/administration/settings/help_page.md b/doc/administration/settings/help_page.md index 23ca7d55cde..1077bbec316 100644 --- a/doc/administration/settings/help_page.md +++ b/doc/administration/settings/help_page.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize the Help and sign-in page messages **(FREE SELF)** @@ -16,8 +15,7 @@ the GitLab sign-in page. You can add a help message, which is shown at the top of the GitLab `/help` page (for example, <https://gitlab.com/help>): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. @@ -34,8 +32,7 @@ is restricted, `/help` is visible only to authenticated users. You can add a help message, which is shown on the GitLab sign-in page. The message appears on the sign-in page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the sign-in page**, enter the information you want to @@ -48,8 +45,7 @@ You can now see the message on the sign-in page. GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. Select the **Hide marketing-related entries from the Help page** checkbox. @@ -62,8 +58,7 @@ You can specify a custom URL to which users are directed when they: - Select **Support** from the Help dropdown list. - Select **See our website for help** on the Help page. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Support page URL** field, enter the URL. @@ -77,8 +72,7 @@ You can specify a custom URL to which users are directed when they: You can redirect all `/help` links to a destination that meets the [necessary requirements](#destination-requirements). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Documentation pages URL** field, enter the URL. diff --git a/doc/administration/settings/import_and_export_settings.md b/doc/administration/settings/import_and_export_settings.md index 8d191ea661c..ddb31e49483 100644 --- a/doc/administration/settings/import_and_export_settings.md +++ b/doc/administration/settings/import_and_export_settings.md @@ -1,8 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Import and export settings **(FREE SELF)** @@ -15,8 +14,7 @@ Before you can import projects from other systems, you must enable the [import source](../../user/gitlab_com/index.md#default-import-sources) for that system. 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Import and export settings** section. 1. Select each of **Import sources** to allow. @@ -28,8 +26,7 @@ To enable the export of [projects and their data](../../user/project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Import and export settings** section. 1. Scroll to **Project export**. @@ -51,8 +48,7 @@ Migration of groups and projects by direct transfer is disabled by default. To enable migration of groups and projects by direct transfer: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Import and export settings** section. 1. Scroll to **Allow migrating GitLab groups and projects by direct transfer**. @@ -69,8 +65,7 @@ The same setting To modify the maximum file size for exports in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**, then expand **Import and export settings**. 1. Increase or decrease by changing the value in **Maximum export size (MiB)**. @@ -80,8 +75,7 @@ To modify the maximum file size for exports in GitLab: To modify the maximum file size for imports in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Increase or decrease by changing the value in **Maximum import size (MiB)**. @@ -103,8 +97,7 @@ By default, the maximum remote file size for imports from external object storag To modify this setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Increase or decrease by changing the value in **Maximum import remote file size (MiB)**. Set to `0` to set no file size limit. @@ -117,8 +110,7 @@ By default, the maximum download file size for imports by direct transfer is 5 G To modify this setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Increase or decrease by changing the value in **Direct transfer maximum download file size (MiB)**. Set to `0` to set no download file size limit. @@ -141,8 +133,7 @@ Decompressed archive size validation failed. To modify this setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Set another value for **Maximum decompressed file size for archives from imports (MiB)**. @@ -155,8 +146,7 @@ When you [import a project](../../user/project/settings/import_export.md), you c To modify the maximum decompressed file size for imports in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Set another value for **Timeout for decompressing archived files (seconds)**. diff --git a/doc/administration/settings/import_export_rate_limits.md b/doc/administration/settings/import_export_rate_limits.md index dad72ffdf44..b261efd751b 100644 --- a/doc/administration/settings/import_export_rate_limits.md +++ b/doc/administration/settings/import_export_rate_limits.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits for imports and exports of project and groups **(FREE SELF)** @@ -12,8 +12,7 @@ You can configure the rate limits for imports and exports of projects and groups To change a rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Import and export rate limits**. 1. Change the value of any rate limit. The rate limits are per minute per user, not per IP address. diff --git a/doc/administration/settings/incident_management_rate_limits.md b/doc/administration/settings/incident_management_rate_limits.md index 5a8b1b96c6d..57005682f15 100644 --- a/doc/administration/settings/incident_management_rate_limits.md +++ b/doc/administration/settings/incident_management_rate_limits.md @@ -1,8 +1,7 @@ --- -type: reference -stage: Monitor +stage: Service Management group: Respond -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incident management rate limits **(ULTIMATE SELF)** @@ -30,8 +29,7 @@ Requests that exceed the limit are logged into `auth.log`. To set inbound incident management alert limits: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Incident Management Limits**. 1. Select the **Enable Incident Management inbound alert limit** checkbox. diff --git a/doc/administration/settings/index.md b/doc/administration/settings/index.md index 1c601df7814..531073887c5 100644 --- a/doc/administration/settings/index.md +++ b/doc/administration/settings/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Update your Admin Area settings **(FREE SELF)** @@ -17,5 +16,4 @@ Use **Settings** to control settings across the instance. To access the **Admin Area**: 1. Sign in to your GitLab instance as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. diff --git a/doc/administration/settings/instance_template_repository.md b/doc/administration/settings/instance_template_repository.md index 510c88e7738..3d95172ae24 100644 --- a/doc/administration/settings/instance_template_repository.md +++ b/doc/administration/settings/instance_template_repository.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Instance template repository **(PREMIUM SELF)** @@ -20,8 +19,7 @@ while the project remains secure. To select a project to serve as the custom template repository: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown list, select the project to use as the template repository. diff --git a/doc/administration/settings/jira_cloud_app.md b/doc/administration/settings/jira_cloud_app.md index 8ff2a9acdb8..c87c7c62a3a 100644 --- a/doc/administration/settings/jira_cloud_app.md +++ b/doc/administration/settings/jira_cloud_app.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Jira Cloud app administration **(FREE SELF)** @@ -18,6 +18,10 @@ To set up the GitLab for Jira Cloud app on your self-managed instance, do one of - [Connect the GitLab for Jira Cloud app](#connect-the-gitlab-for-jira-cloud-app) (GitLab 15.7 and later). - [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). +After you set up the app, you can use the [project toolchain](https://support.atlassian.com/jira-software-cloud/docs/what-is-the-project-toolchain-in-jira) +developed and maintained by Atlassian to [link GitLab repositories to Jira projects](https://support.atlassian.com/jira-software-cloud/docs/link-repositories-to-a-project/#Link-repositories-using-the-toolchain-feature). +The project toolchain does not affect how development information is synced between GitLab and Jira Cloud. + For Jira Data Center or Jira Server, use the [Jira DVCS connector](../../integration/jira/dvcs/index.md) developed and maintained by Atlassian. ## Set up OAuth authentication @@ -29,9 +33,8 @@ You must set up OAuth authentication to: To create an OAuth application on your self-managed instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications**. 1. Select **New application**. 1. In **Redirect URI**: - If you're installing the app from the official marketplace listing, enter `https://gitlab.com/-/jira_connect/oauth_callbacks`. @@ -109,9 +112,8 @@ With this method: To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab 15.7 and later: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. In **Jira Connect Proxy URL**, enter `https://gitlab.com`. 1. Select **Save changes**. @@ -231,9 +233,8 @@ You might want to use a proxy if you're managing multiple GitLab instances but o To configure your GitLab instance to serve as a proxy: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Select **Enable public key storage**. 1. Select **Save changes**. @@ -248,6 +249,16 @@ Other GitLab instances that use the proxy must configure the following settings The GitLab for Jira Cloud app connects GitLab and Jira. Data must be shared between the two applications, and access must be granted in both directions. +### Using GitLab.com as a proxy + +When you use [GitLab.com as a proxy](#configure-your-gitlab-instance-to-serve-as-a-proxy), +the Jira access token is shared with GitLab.com. + +The Jira access token is stored on GitLab.com because the token must be used to verify +incoming requests from Jira before the requests are sent to your self-managed instance. +The token is encrypted and is not used to access data in Jira. +Any data from your self-managed instance is sent directly to Jira. + ### Access to GitLab through OAuth GitLab does not share an access token with Jira. However, users must authenticate through OAuth to configure the app. @@ -263,161 +274,3 @@ However, the GitLab for Jira Cloud app only uses this access to: - Link groups. Access through OAuth is only needed for the time a user configures the GitLab for Jira Cloud app. For more information, see [Access token expiration](../../integration/oauth_provider.md#access-token-expiration). - -## Troubleshooting - -When administering the GitLab for Jira Cloud app for self-managed instances, you might encounter the following issues. - -For GitLab.com, see [GitLab for Jira Cloud app](../../integration/jira/connect-app.md#troubleshooting). - -### Browser displays a sign-in message when already signed in - -You might get the following message prompting you to sign in to GitLab.com -when you're already signed in: - -```plaintext -You need to sign in or sign up before continuing. -``` - -The GitLab for Jira Cloud app uses an iframe to add groups on the -settings page. Some browsers block cross-site cookies, which can lead to this issue. - -To resolve this issue, set up [OAuth authentication](#set-up-oauth-authentication). - -### Manual installation fails - -You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with [manual installation](#install-the-gitlab-for-jira-cloud-app-manually): - -```plaintext -The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace -``` - -To resolve this issue, disable the **Jira Connect Proxy URL** setting. - -- In GitLab 15.7: - - 1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). - 1. Execute `ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)`. - -- In GitLab 15.8 and later: - - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Settings > General**. - 1. Expand **GitLab for Jira App**. - 1. Clear the **Jira Connect Proxy URL** text box. - 1. Select **Save changes**. - -### Data sync fails with `Invalid JWT` error - -If the GitLab for Jira Cloud app continuously fails to sync data, it may be due to an outdated secret token. Atlassian can send new secret tokens that must be processed and stored by GitLab. -If GitLab fails to store the token or misses the new token request, an `Invalid JWT` error occurs. - -To resolve this issue on GitLab self-managed, follow one of the solutions below, depending on your app installation method. - -- If you installed the app from the official marketplace listing: - - 1. Open the GitLab for Jira Cloud app on Jira. - 1. Select **Change GitLab version**. - 1. Select **GitLab.com (SaaS)**. - 1. Select **Change GitLab version** again. - 1. Select **GitLab (self-managed)**. - 1. Enter your **GitLab instance URL**. - 1. Select **Save**. - -- If you [installed the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually): - - - In GitLab 14.9 and later: - - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your group. - - In all GitLab versions: - - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the [Jira development panel](../../integration/jira/development_panel.md). - -### `Failed to update the GitLab instance` - -When you set up the GitLab for Jira Cloud app, you might get a `Failed to update the GitLab instance` error after you enter your self-managed instance URL. - -To resolve this issue, ensure all prerequisites for your installation method have been met: - -- [Prerequisites for connecting the GitLab for Jira Cloud app](#prerequisites) -- [Prerequisites for installing the GitLab for Jira Cloud app manually](#prerequisites-1) - -If you have configured a Jira Connect Proxy URL and the problem persists after checking the prerequisites, review [Debugging Jira Connect Proxy issues](#debugging-jira-connect-proxy-issues). - -If you're using GitLab 15.8 and earlier and have previously enabled both the `jira_connect_oauth_self_managed` -and the `jira_connect_oauth` feature flags, you must disable the `jira_connect_oauth_self_managed` flag -due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388943). To check for these flags: - -1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). -1. Execute the following code: - - ```ruby - # Check if both feature flags are enabled. - # If the flags are enabled, these commands return `true`. - Feature.enabled?(:jira_connect_oauth) - Feature.enabled?(:jira_connect_oauth_self_managed) - - # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. - Feature.disable(:jira_connect_oauth_self_managed) - ``` - -#### Debugging Jira Connect Proxy issues - -If you are using a self-managed GitLab instance and you have configured `https://gitlab.com` for the Jira Connect Proxy URL when -[setting up the OAuth authentication](#set-up-oauth-authentication), you can inspect the network traffic in your browser's development -tools while reproducing the `Failed to update the GitLab instance` error to see a more precise error. - -You should see a `GET` request to `https://gitlab.com/-/jira_connect/installations`. - -This request should return a `200` status code, but it can return a `422` status code if there was a problem. The response body can be checked for the error. - -If you cannot resolve the problem and you are a GitLab customer, contact [GitLab Support](https://about.gitlab.com/support/) for assistance. Provide -GitLab Support with: - -1. Your GitLab self-managed instance URL. -1. Your GitLab.com username. -1. If possible, the `X-Request-Id` response header for the failed `GET` request to `https://gitlab.com/-/jira_connect/installations`. -1. Optional. [A HAR file that captured the problem](https://support.zendesk.com/hc/en-us/articles/4408828867098-Generating-a-HAR-file-for-troubleshooting). - -The GitLab Support team can then look up why this is failing in the GitLab.com server logs. - -##### Process for GitLab Support - -NOTE: -These steps can only be completed by GitLab Support. - -In Kibana, the logs should be filtered for `json.meta.caller_id: JiraConnect::InstallationsController#update` and `NOT json.status: 200`. -If you have been provided the `X-Request-Id` value, you can use that against `json.correlation_id` to narrow down the results. - -Each `GET` request to the Jira Connect Proxy URL `https://gitlab.com/-/jira_connect/installations` generates two log entries. - -For the first log: - -- `json.status` is `422`. -- `json.params.value` should match the GitLab self-managed URL `[[FILTERED], {"instance_url"=>"https://gitlab.example.com"}]`. - -For the second log: - -- `json.message` is `Proxy lifecycle event received error response` or similar. -- `json.jira_status_code` and `json.jira_body` might contain details on why GitLab.com wasn't able to connect back to the self-managed instance. - -### `Failed to link group` - -After you connect the GitLab for Jira Cloud app for self-managed instances, you might get one of these errors: - -```plaintext -Failed to load Jira Connect Application ID. Please try again. -``` - -```plaintext -Failed to link group. Please try again. -``` - -When you check the browser console, you might see the following message: - -```plaintext -Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403. -``` - -`403` status code is returned if the user information cannot be fetched from Jira because of insufficient permissions. - -To resolve this issue, ensure that the Jira user that installs and configures the GitLab for Jira Cloud app meets certain [requirements](#jira-user-requirements). diff --git a/doc/administration/settings/jira_cloud_app_troubleshooting.md b/doc/administration/settings/jira_cloud_app_troubleshooting.md new file mode 100644 index 00000000000..1b6f88d43ae --- /dev/null +++ b/doc/administration/settings/jira_cloud_app_troubleshooting.md @@ -0,0 +1,164 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting GitLab for Jira Cloud app administration **(FREE SELF)** + +When administering the GitLab for Jira Cloud app for self-managed instances, you might encounter the following issues. + +For GitLab.com, see [GitLab for Jira Cloud app](../../integration/jira/connect-app.md#troubleshooting). + +## Browser displays a sign-in message when already signed in + +You might get the following message prompting you to sign in to GitLab.com +when you're already signed in: + +```plaintext +You need to sign in or sign up before continuing. +``` + +The GitLab for Jira Cloud app uses an iframe to add groups on the +settings page. Some browsers block cross-site cookies, which can lead to this issue. + +To resolve this issue, set up [OAuth authentication](jira_cloud_app.md#set-up-oauth-authentication). + +## Manual installation fails + +You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with [manual installation](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually): + +```plaintext +The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace +``` + +To resolve this issue, disable the **Jira Connect Proxy URL** setting. + +- In GitLab 15.7: + + 1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). + 1. Execute `ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)`. + +- In GitLab 15.8 and later: + + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **GitLab for Jira App**. + 1. Clear the **Jira Connect Proxy URL** text box. + 1. Select **Save changes**. + +## Data sync fails with `Invalid JWT` error + +If the GitLab for Jira Cloud app continuously fails to sync data, it may be due to an outdated secret token. Atlassian can send new secret tokens that must be processed and stored by GitLab. +If GitLab fails to store the token or misses the new token request, an `Invalid JWT` error occurs. + +To resolve this issue on GitLab self-managed, follow one of the solutions below, depending on your app installation method. + +- If you installed the app from the official marketplace listing: + + 1. Open the GitLab for Jira Cloud app on Jira. + 1. Select **Change GitLab version**. + 1. Select **GitLab.com (SaaS)**. + 1. Select **Change GitLab version** again. + 1. Select **GitLab (self-managed)**. + 1. Enter your **GitLab instance URL**. + 1. Select **Save**. + +- If you [installed the GitLab for Jira Cloud app manually](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually): + + - In GitLab 14.9 and later: + - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your group. + - In all GitLab versions: + - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the [Jira development panel](../../integration/jira/development_panel.md). + +## `Failed to update the GitLab instance` + +When you set up the GitLab for Jira Cloud app, you might get a `Failed to update the GitLab instance` error after you enter your self-managed instance URL. + +To resolve this issue, ensure all prerequisites for your installation method have been met: + +- [Prerequisites for connecting the GitLab for Jira Cloud app](jira_cloud_app.md#prerequisites) +- [Prerequisites for installing the GitLab for Jira Cloud app manually](jira_cloud_app.md#prerequisites-1) + +If you have configured a Jira Connect Proxy URL and the problem persists after checking the prerequisites, review [Debugging Jira Connect Proxy issues](#debugging-jira-connect-proxy-issues). + +If you're using GitLab 15.8 and earlier and have previously enabled both the `jira_connect_oauth_self_managed` +and the `jira_connect_oauth` feature flags, you must disable the `jira_connect_oauth_self_managed` flag +due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388943). To check for these flags: + +1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Execute the following code: + + ```ruby + # Check if both feature flags are enabled. + # If the flags are enabled, these commands return `true`. + Feature.enabled?(:jira_connect_oauth) + Feature.enabled?(:jira_connect_oauth_self_managed) + + # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. + Feature.disable(:jira_connect_oauth_self_managed) + ``` + +### Debugging Jira Connect Proxy issues + +If you are using a self-managed GitLab instance and you have configured `https://gitlab.com` for the Jira Connect Proxy URL when +[setting up the OAuth authentication](jira_cloud_app.md#set-up-oauth-authentication), you can inspect the network traffic in your browser's development +tools while reproducing the `Failed to update the GitLab instance` error to see a more precise error. + +You should see a `GET` request to `https://gitlab.com/-/jira_connect/installations`. + +This request should return a `200` status code, but it can return a `422` status code if there was a problem. The response body can be checked for the error. + +If you cannot resolve the problem and you are a GitLab customer, contact [GitLab Support](https://about.gitlab.com/support/) for assistance. Provide +GitLab Support with: + +1. Your GitLab self-managed instance URL. +1. Your GitLab.com username. +1. If possible, the `X-Request-Id` response header for the failed `GET` request to `https://gitlab.com/-/jira_connect/installations`. +1. Optional. [A HAR file that captured the problem](https://support.zendesk.com/hc/en-us/articles/4408828867098-Generating-a-HAR-file-for-troubleshooting). + +The GitLab Support team can then look up why this is failing in the GitLab.com server logs. + +#### Process for GitLab Support + +NOTE: +These steps can only be completed by GitLab Support. + +In Kibana, the logs should be filtered for `json.meta.caller_id: JiraConnect::InstallationsController#update` and `NOT json.status: 200`. +If you have been provided the `X-Request-Id` value, you can use that against `json.correlation_id` to narrow down the results. + +Each `GET` request to the Jira Connect Proxy URL `https://gitlab.com/-/jira_connect/installations` generates two log entries. + +For the first log: + +- `json.status` is `422`. +- `json.params.value` should match the GitLab self-managed URL `[[FILTERED], {"instance_url"=>"https://gitlab.example.com"}]`. + +For the second log: + +- `json.message` is `Proxy lifecycle event received error response` or similar. +- `json.jira_status_code` and `json.jira_body` might contain details on why GitLab.com wasn't able to connect back to the self-managed instance. +- If `json.jira_status_code` is `401` and `json.jira_body` is empty, this might indicate that the [**Jira Connect Proxy URL**](jira_cloud_app.md#set-up-your-instance) is not set to + `https://gitlab.com`. + +## `Failed to link group` + +After you connect the GitLab for Jira Cloud app for self-managed instances, you might get one of these errors: + +```plaintext +Failed to load Jira Connect Application ID. Please try again. +``` + +```plaintext +Failed to link group. Please try again. +``` + +When you check the browser console, you might see the following message: + +```plaintext +Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403. +``` + +`403` status code is returned if the user information cannot be fetched from Jira because of insufficient permissions. + +To resolve this issue, ensure that the Jira user that installs and configures the GitLab for Jira Cloud app meets certain [requirements](jira_cloud_app.md#jira-user-requirements). diff --git a/doc/administration/settings/localization.md b/doc/administration/settings/localization.md index a86e9c75a4e..71ceaa3c9bf 100644 --- a/doc/administration/settings/localization.md +++ b/doc/administration/settings/localization.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Localization **(FREE SELF)** @@ -15,8 +14,7 @@ deployment. You can change the [Default first day of the week](../../user/profile/preferences.md) for the entire GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired first day of the week. @@ -25,7 +23,6 @@ for the entire GitLab instance: You can change the [Default language](../../user/profile/preferences.md) for the entire GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired default language. diff --git a/doc/administration/settings/package_registry_rate_limits.md b/doc/administration/settings/package_registry_rate_limits.md index 2ddb6bfcd17..db3170a625b 100644 --- a/doc/administration/settings/package_registry_rate_limits.md +++ b/doc/administration/settings/package_registry_rate_limits.md @@ -1,13 +1,12 @@ --- stage: Package group: Package Registry -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Package Registry Rate Limits **(FREE SELF)** +# Package registry rate limits **(FREE SELF)** -With the [GitLab Package Registry](../../user/packages/package_registry/index.md), +With the [GitLab package registry](../../user/packages/package_registry/index.md), you can use GitLab as a private or public registry for a variety of common package managers. You can publish and share packages, which others can consume as a dependency in downstream projects through the [Packages API](../../api/packages.md). @@ -30,8 +29,7 @@ no difference in functionality compared to the general user and IP rate limits. To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Package registry rate limits**. 1. Select **Enable unauthenticated request rate limit**. @@ -45,8 +43,7 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network** 1. Expand **Package registry rate limits**. 1. Select **Enable authenticated API request rate limit**. diff --git a/doc/administration/settings/project_integration_management.md b/doc/administration/settings/project_integration_management.md index 32756e65eaf..7fea1bccaf6 100644 --- a/doc/administration/settings/project_integration_management.md +++ b/doc/administration/settings/project_integration_management.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project integration administration **(FREE SELF)** @@ -23,14 +23,13 @@ is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Manage instance-level default settings for a project integration -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To manage instance-level default settings for a project integration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. 1. Complete the fields. @@ -65,14 +64,13 @@ is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ### Remove an instance-level default setting -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To remove an instance-level default setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. 1. Select **Reset** and confirm. @@ -83,14 +81,13 @@ Resetting an instance-level default setting removes the integration from all pro > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218252) in GitLab 14.2. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To view projects in your instance that [use custom settings](../../user/project/integrations/index.md#use-custom-settings-for-a-project-or-group-integration): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. 1. Select the **Projects using custom settings** tab. diff --git a/doc/administration/settings/protected_paths.md b/doc/administration/settings/protected_paths.md index 3244c25e906..9eae34c8c64 100644 --- a/doc/administration/settings/protected_paths.md +++ b/doc/administration/settings/protected_paths.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected paths **(FREE SELF)** @@ -34,8 +33,7 @@ See also: Throttling of protected paths is enabled by default and can be disabled or customized. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Protected paths**. diff --git a/doc/administration/settings/push_event_activities_limit.md b/doc/administration/settings/push_event_activities_limit.md index 36aa1eec306..edf64100eb7 100644 --- a/doc/administration/settings/push_event_activities_limit.md +++ b/doc/administration/settings/push_event_activities_limit.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Push event activities limit and bulk push events **(FREE SELF)** @@ -26,8 +25,7 @@ the activity feed. To modify this setting: - In the Admin Area: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Performance optimization**. - Through the [Application settings API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) diff --git a/doc/administration/settings/rate_limit_on_issues_creation.md b/doc/administration/settings/rate_limit_on_issues_creation.md index 14d484d91b1..36e242b4ac4 100644 --- a/doc/administration/settings/rate_limit_on_issues_creation.md +++ b/doc/administration/settings/rate_limit_on_issues_creation.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on issue and epic creation **(FREE SELF)** @@ -18,8 +17,7 @@ action blocks requests that exceed a rate of 300 per minute. Access to the endpo To limit the number of requests made to the issue and epic creation endpoints: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Issues Rate Limits**. 1. Under **Max requests per minute**, enter the new value. diff --git a/doc/administration/settings/rate_limit_on_notes_creation.md b/doc/administration/settings/rate_limit_on_notes_creation.md index 3bd6eee8303..59ec47afaa9 100644 --- a/doc/administration/settings/rate_limit_on_notes_creation.md +++ b/doc/administration/settings/rate_limit_on_notes_creation.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on note creation **(FREE SELF)** @@ -13,8 +12,7 @@ You can configure the per-user rate limit for requests to the note creation endp To change the note creation rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Notes rate limit**. 1. In the **Maximum requests per minute** box, enter the new value. diff --git a/doc/administration/settings/rate_limit_on_pipelines_creation.md b/doc/administration/settings/rate_limit_on_pipelines_creation.md index d083acb190e..e99d6e65993 100644 --- a/doc/administration/settings/rate_limit_on_pipelines_creation.md +++ b/doc/administration/settings/rate_limit_on_pipelines_creation.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on pipeline creation **(FREE SELF)** @@ -26,8 +25,7 @@ Requests that exceed the limit are logged in the `application_json.log` file. To limit the number of pipeline requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Pipelines Rate Limits**. 1. Under **Max requests per minute**, enter a value greater than `0`. diff --git a/doc/administration/settings/rate_limit_on_projects_api.md b/doc/administration/settings/rate_limit_on_projects_api.md index 33304e4f088..f2797b37171 100644 --- a/doc/administration/settings/rate_limit_on_projects_api.md +++ b/doc/administration/settings/rate_limit_on_projects_api.md @@ -1,8 +1,7 @@ --- -type: reference stage: Data Stores group: Tenant Scale -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limit on Projects API **(FREE SELF)** @@ -16,8 +15,7 @@ You can configure the rate limit per IP address for unauthenticated requests to To change the rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Projects API rate limit**. 1. In the **Maximum requests per 10 minutes per IP address** text box, enter the new value. diff --git a/doc/administration/settings/rate_limit_on_users_api.md b/doc/administration/settings/rate_limit_on_users_api.md index 533bfe0b000..fcac30c9105 100644 --- a/doc/administration/settings/rate_limit_on_users_api.md +++ b/doc/administration/settings/rate_limit_on_users_api.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Users API **(FREE SELF)** @@ -13,8 +12,7 @@ You can configure the per user rate limit for requests to [Users API](../../api/ To change the rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Users API rate limit**. 1. In the **Maximum requests per 10 minutes** text box, enter the new value. diff --git a/doc/administration/settings/rate_limits.md b/doc/administration/settings/rate_limits.md index 2263455fa09..89e64344e0c 100644 --- a/doc/administration/settings/rate_limits.md +++ b/doc/administration/settings/rate_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits @@ -15,7 +14,7 @@ You can change network settings to limit the rate of connections with your insta - [Incident management](incident_management_rate_limits.md) - [Issue creation](rate_limit_on_issues_creation.md) - [Note creation](rate_limit_on_notes_creation.md) -- [Package Registry](package_registry_rate_limits.md) +- [Package registry](package_registry_rate_limits.md) - [Pipeline creation](rate_limit_on_pipelines_creation.md) - [Projects API](rate_limit_on_projects_api.md) - [Raw endpoints](rate_limits_on_raw_endpoints.md) diff --git a/doc/administration/settings/rate_limits_on_git_ssh_operations.md b/doc/administration/settings/rate_limits_on_git_ssh_operations.md index 4e60fd55b19..dea939c7fe9 100644 --- a/doc/administration/settings/rate_limits_on_git_ssh_operations.md +++ b/doc/administration/settings/rate_limits_on_git_ssh_operations.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Git SSH operations **(FREE SELF)** @@ -26,8 +25,7 @@ Because the same commands are shared by `git-upload-pack`, `git pull`, and `git `Git operations using SSH` is enabled by default. Defaults to 600 per user per minute. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Git SSH operations rate limit**. 1. Enter a value for **Maximum number of Git operations per minute**. diff --git a/doc/administration/settings/rate_limits_on_raw_endpoints.md b/doc/administration/settings/rate_limits_on_raw_endpoints.md index 237b57f4436..9ff5637028d 100644 --- a/doc/administration/settings/rate_limits_on_raw_endpoints.md +++ b/doc/administration/settings/rate_limits_on_raw_endpoints.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on raw endpoints **(FREE SELF)** @@ -11,8 +10,7 @@ type: reference This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Performance optimization**. diff --git a/doc/administration/settings/scim_setup.md b/doc/administration/settings/scim_setup.md index 45020fdfb59..52061150fa7 100644 --- a/doc/administration/settings/scim_setup.md +++ b/doc/administration/settings/scim_setup.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure SCIM for self-managed GitLab instances **(PREMIUM SELF)** @@ -27,8 +26,7 @@ Prerequisites: To configure GitLab SCIM: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **SCIM Token** section and select **Generate a SCIM token**. 1. For configuration of your identity provider, save the: diff --git a/doc/administration/settings/security_and_compliance.md b/doc/administration/settings/security_and_compliance.md index 78923b19b04..d0d9ed3256b 100644 --- a/doc/administration/settings/security_and_compliance.md +++ b/doc/administration/settings/security_and_compliance.md @@ -1,8 +1,7 @@ --- stage: Secure group: Composition Analysis -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security and Compliance Admin Area settings **(ULTIMATE SELF)** @@ -13,8 +12,7 @@ The settings for package metadata synchronization are located in the [Admin Area To choose the packages you want to synchronize with the GitLab Package Metadata Database for [License Compliance](../../user/compliance/license_scanning_of_cyclonedx_files/index.md) and [Continuous Vulnerability Scanning](../../user/application_security/continuous_vulnerability_scanning/index.md): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Security and Compliance**. 1. Expand **License Compliance**. 1. Select or clear checkboxes for the package registries that you want to sync. diff --git a/doc/administration/settings/security_contact_information.md b/doc/administration/settings/security_contact_information.md new file mode 100644 index 00000000000..e4d2cf62bdc --- /dev/null +++ b/doc/administration/settings/security_contact_information.md @@ -0,0 +1,42 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# Provide public security contact information **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433210) in GitLab 16.7. + +Organizations can facilitate the responsible disclosure of security issues by +providing public contact information. GitLab supports using a +[`security.txt`](https://securitytxt.org/) file for this purpose. + +Administrators can add a `security.txt` file using the GitLab UI or the +[REST API](../../api/settings.md#change-application-settings). +Any content added is made available at +`https://gitlab.example.com/.well-known/security.txt`. Authentication is not +required to view this file. + +To configure a `security.txt` file: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand the **Add security contact information** section. +1. In **Content for security.txt**, enter security contact information in the + format documented at <https://securitytxt.org/>. +1. Select **Save changes**. + +For information about how to respond if you receive a report, see +[Responding to security incidents](../../security/responding_to_security_incidents.md). + +## Example `security.txt` file + +The format of this information is documented at <https://securitytxt.org/>. +An example `security.txt` file is: + +```plaintext +Contact: mailto:security@example.com +Expires: 2024-12-31T23:59Z +``` diff --git a/doc/administration/settings/sidekiq_job_limits.md b/doc/administration/settings/sidekiq_job_limits.md index 6c5ff29e96b..bf89678d4d2 100644 --- a/doc/administration/settings/sidekiq_job_limits.md +++ b/doc/administration/settings/sidekiq_job_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq job size limits **(FREE SELF)** @@ -17,8 +16,7 @@ Redis. To avoid excessive memory for Redis, we: To access Sidekiq job size limits: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sidekiq job size limits**. 1. Adjust the compression threshold or size limit. The compression can diff --git a/doc/administration/settings/sign_in_restrictions.md b/doc/administration/settings/sign_in_restrictions.md index 942b706b9a3..60994bc6e43 100644 --- a/doc/administration/settings/sign_in_restrictions.md +++ b/doc/administration/settings/sign_in_restrictions.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign-in restrictions **(FREE SELF)** @@ -12,8 +12,7 @@ You can use **Sign-in restrictions** to customize authentication restrictions fo To access sign-in restriction settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Sign-in restrictions** section. @@ -76,11 +75,11 @@ Open the [Rails console](../operations/rails_console.md) and run the following: To enable Admin Mode through the UI: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-in restrictions**. -1. In the **Admin Mode** section, select the **Require additional authentication for administrative tasks** checkbox. +1. Select **Enable Admin Mode**. +1. Select **Save changes**. ### Turn on Admin Mode for your session @@ -181,8 +180,7 @@ For example, if you include the following information in the noted text box: To access this text box: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Sign-in restrictions** section. ``` diff --git a/doc/administration/settings/sign_up_restrictions.md b/doc/administration/settings/sign_up_restrictions.md index da40a2bab05..3ebb80c34ab 100644 --- a/doc/administration/settings/sign_up_restrictions.md +++ b/doc/administration/settings/sign_up_restrictions.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign-up restrictions **(FREE SELF)** @@ -22,8 +21,7 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. @@ -40,8 +38,7 @@ enabled by default for new GitLab instances. It is only applicable if sign ups a To require administrator approval for new sign ups: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. @@ -66,8 +63,7 @@ their email address before they are allowed to sign in. To enforce confirmation of the email address used for new sign ups: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Under **Email confirmation settings**, select **Hard**. @@ -101,14 +97,13 @@ The user cap might apply only retrospectively after the cap has already been exc To ensure the cap is enabled immediately, set the cap to a value below the current number of billable users (for example, `1`). -Prerequisite: +Prerequisites: - You must be an administrator. To set a user cap: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. @@ -121,14 +116,13 @@ administrator approval is not restricted. After you remove the user cap, users pending approval are automatically approved. -Prerequisite: +Prerequisites: - You must be an administrator. To remove the user cap: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. @@ -153,8 +147,7 @@ You can add additional complexity requirements. Changes to password complexity r Existing passwords are unaffected. To change password complexity requirements: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Under **Minimum password length (number of characters)**, select additional password complexity requirements. You can require numbers, uppercase letters, lowercase letters, @@ -183,8 +176,7 @@ reduce the risk of malicious users creating spam accounts with disposable email To create an email domain allowlist or denylist: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list diff --git a/doc/administration/settings/slack_app.md b/doc/administration/settings/slack_app.md index de11da281e4..5e54294b720 100644 --- a/doc/administration/settings/slack_app.md +++ b/doc/administration/settings/slack_app.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Slack app administration **(FREE SELF)** @@ -18,7 +18,7 @@ The app is a private one-time copy installed in your Slack workspace only and no ## Create a GitLab for Slack app -Prerequisite: +Prerequisites: - You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). @@ -26,8 +26,7 @@ To create a GitLab for Slack app: - **In GitLab**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Slack app**. 1. Select **Create Slack app**. @@ -46,9 +45,8 @@ You're then redirected to Slack for the next steps. After you've [created a GitLab for Slack app](#create-a-gitlab-for-slack-app), you can configure the settings in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **GitLab for Slack app**. 1. Select the **Enable GitLab for Slack app** checkbox. 1. Enter the details of your GitLab for Slack app: @@ -70,7 +68,7 @@ To use Slash commands for a project, configure the [GitLab for Slack app](../../ ## Update the GitLab for Slack app -Prerequisite: +Prerequisites: - You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). @@ -80,8 +78,7 @@ To update your copy of the GitLab for Slack app: - **In GitLab**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Slack app**. 1. Select **Download latest manifest file** to download `slack_manifest.json`. @@ -107,7 +104,7 @@ To enable the GitLab for Slack app functionality, your network must allow inboun When administering the GitLab for Slack app for self-managed instances, you might encounter the following issues. -For GitLab.com, see [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md#troubleshooting). +For GitLab.com, see [GitLab for Slack app](../../user/project/integrations/gitlab_slack_app_troubleshooting.md). ### Slash commands return an error in Slack diff --git a/doc/administration/settings/terms.md b/doc/administration/settings/terms.md index 12678b6416a..dc12784ad82 100644 --- a/doc/administration/settings/terms.md +++ b/doc/administration/settings/terms.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terms of Service and Privacy Policy **(FREE SELF)** @@ -17,8 +16,7 @@ for example `https://gitlab.example.com/-/users/terms`. To enforce acceptance of a Terms of Service and Privacy Policy: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. diff --git a/doc/administration/settings/terraform_limits.md b/doc/administration/settings/terraform_limits.md index 7f744b0a4e5..9650b2fdda1 100644 --- a/doc/administration/settings/terraform_limits.md +++ b/doc/administration/settings/terraform_limits.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform limits **(FREE SELF)** @@ -15,8 +14,7 @@ state file version, and is checked whenever a new version is created. To add a storage limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Terraform limits**. 1. Enter a size limit in bytes. Set to `0` to allow files of unlimited size. diff --git a/doc/administration/settings/third_party_offers.md b/doc/administration/settings/third_party_offers.md index b91f13a6a30..861859e3639 100644 --- a/doc/administration/settings/third_party_offers.md +++ b/doc/administration/settings/third_party_offers.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Tenant Scale -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customer experience improvement and third-party offers **(FREE SELF)** @@ -18,8 +17,7 @@ questions when creating a group. To toggle the display of customer experience improvement content and third-party offers: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Customer experience improvement and third-party offers**. 1. Select **Do not display content for customer experience improvement and offers from third parties**. diff --git a/doc/administration/settings/usage_statistics.md b/doc/administration/settings/usage_statistics.md index b9080f49f5d..20479a7dd8a 100644 --- a/doc/administration/settings/usage_statistics.md +++ b/doc/administration/settings/usage_statistics.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage statistics **(FREE SELF)** @@ -71,12 +71,16 @@ In the following table, you can see: | [Users and permissions report](../../administration/admin_area.md#user-permission-export) | GitLab 16.6 and later | | [Advanced search](../../user/search/advanced_search.md) | GitLab 16.6 and later | | [DevOps Adoption](../../user/group/devops_adoption/index.md) | GitLab 16.6 and later | +| [Сross-project pipelines with artifacts dependencies](../../ci/yaml/index.md#needsproject) | GitLab 16.7 and later | +| [Feature flag related issues](../../operations/feature_flags.md#feature-flag-related-issues) | GitLab 16.7 and later | +| [Merged results pipelines](../../ci/pipelines/merged_results_pipelines.md) | GitLab 16.7 and later | +| [CI/CD for external repositories](../../ci/ci_cd_for_external_repos/index.md) | GitLab 16.7 and later | +| [CI/CD for GitHub](../../ci/ci_cd_for_external_repos/github_integration.md) | GitLab 16.7 and later | ### Enable registration features 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. If not enabled, select the **Enable Service Ping** checkbox. @@ -107,8 +111,7 @@ If you disable version check, this information isn't collected. ### Enable or disable version check -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Select or clear the **Enable version check** checkbox. @@ -144,8 +147,7 @@ If your GitLab instance is behind a proxy, set the appropriate To enable or disable Service Ping: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Select or clear the **Enable Service Ping** checkbox. @@ -207,8 +209,7 @@ the Admin Area. You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling > Usage statistics**. 1. Select **Preview payload**. @@ -225,8 +226,7 @@ or if the Service Ping [cron job](../../development/internal_analytics/service_p To upload the payload manually: 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling > Usage statistics**. 1. Select **Download payload**. 1. Save the JSON file. diff --git a/doc/administration/settings/user_and_ip_rate_limits.md b/doc/administration/settings/user_and_ip_rate_limits.md index 22b16d01394..1f6cb1af814 100644 --- a/doc/administration/settings/user_and_ip_rate_limits.md +++ b/doc/administration/settings/user_and_ip_rate_limits.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User and IP rate limits **(FREE SELF)** @@ -31,8 +30,7 @@ counted as web traffic. To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable unauthenticated API request rate limit**. @@ -46,8 +44,7 @@ To enable the unauthenticated request rate limit: To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable unauthenticated web request rate limit**. @@ -61,8 +58,7 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable authenticated API request rate limit**. @@ -76,8 +72,7 @@ To enable the authenticated API request rate limit: To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable authenticated web request rate limit**. @@ -96,8 +91,7 @@ plain-text body, which by default is `Retry later`. To use a custom response: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. In the **Plain-text response to send to clients that hit a rate limit** text box, @@ -111,8 +105,7 @@ To reduce timeouts, the `project/:id/jobs` endpoint has a default [rate limit](. To modify the maximum number of requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Update the **Maximum authenticated requests to `project/:id/jobs` per minute** value. diff --git a/doc/administration/settings/visibility_and_access_controls.md b/doc/administration/settings/visibility_and_access_controls.md index 11652d8ee9a..671d0a70bd9 100644 --- a/doc/administration/settings/visibility_and_access_controls.md +++ b/doc/administration/settings/visibility_and_access_controls.md @@ -1,8 +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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Control access and visibility **(FREE SELF)** @@ -13,8 +12,7 @@ specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -25,8 +23,7 @@ Instance-level protections for project creation define which roles can on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. For **Default project creation protection**, select the desired roles: @@ -42,8 +39,7 @@ on the instance. To alter which roles have permission to create projects: By default both administrators and anyone with the **Owner** role can delete a project. To restrict project deletion to only administrators: 1. Sign in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: @@ -80,8 +76,7 @@ then it gets automatically changed to `1` while also disabling deletion protecti To configure delayed project deletion: 1. Sign in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: @@ -113,7 +108,7 @@ In GitLab 15.11 and later with the `always_perform_delayed_deletion` feature fla Alternatively, projects that are marked for removal can be deleted immediately. To do so: -1. [Restore the project](../../user/project/settings/index.md#restore-a-project). +1. [Restore the project](../../user/project/settings/migrate_projects.md#restore-a-project). 1. Delete the project as described in the [Administering Projects page](../admin_area.md#administering-projects). @@ -122,8 +117,7 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../user/public_access.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default project visibility: @@ -141,8 +135,7 @@ For more details on project visibility, see To set the default visibility levels for new [snippets](../../user/snippets.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default snippet visibility. @@ -156,8 +149,7 @@ For more details on snippet visibility, read To set the default visibility levels for new groups: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default group visibility: @@ -173,6 +165,7 @@ For more details on group visibility, see > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124649) in GitLab 16.3 to prevent restricting default project and group visibility, [with a flag](../feature_flags.md) named `prevent_visibility_restriction`. Disabled by default. > - `prevent_visibility_restriction` [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131203) by default in GitLab 16.4. +> - The flag `prevent_visibility_restriction` was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/433280) in GitLab 16.7. When restricting visibility levels, consider how these restrictions interact with permissions for subgroups and projects that inherit their visibility from @@ -181,8 +174,7 @@ the item you're changing. To restrict visibility levels for groups, projects, snippets, and selected pages: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. @@ -211,8 +203,7 @@ The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired Git access protocols: @@ -298,8 +289,7 @@ include the `10.0.0.0/24` range. To add a IP address range to the group-level allowlist: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In **Globally-allowed IP ranges**, provide a list of IP address ranges. This list: diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md index 89de4cd6cf3..bde60d17f0c 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run multiple Sidekiq processes **(FREE SELF)** @@ -48,9 +48,8 @@ to all available queues: To view the Sidekiq processes in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Background Jobs**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Background Jobs**. ## Concurrency diff --git a/doc/administration/sidekiq/index.md b/doc/administration/sidekiq/index.md index 0a7974c9622..6a6412a9944 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure an external Sidekiq instance **(FREE SELF)** @@ -200,9 +200,9 @@ To set up multiple Sidekiq nodes: sudo gitlab-ctl reconfigure ``` -## Configure the Container Registry when using an external Sidekiq +## Configure the container registry when using an external Sidekiq -If you're using the Container Registry and it's running on a different +If you're using the container registry and it's running on a different node than Sidekiq, follow the steps below. 1. Edit `/etc/gitlab/gitlab.rb`, and configure the registry URL: @@ -217,7 +217,7 @@ node than Sidekiq, follow the steps below. sudo gitlab-ctl reconfigure ``` -1. In the instance where Container Registry is hosted, copy the `registry.key` +1. In the instance where container registry is hosted, copy the `registry.key` file to the Sidekiq node. ## Configure the Sidekiq metrics server diff --git a/doc/administration/sidekiq/processing_specific_job_classes.md b/doc/administration/sidekiq/processing_specific_job_classes.md index 74cbb6ca89b..26f3445f62c 100644 --- a/doc/administration/sidekiq/processing_specific_job_classes.md +++ b/doc/administration/sidekiq/processing_specific_job_classes.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Processing specific job classes diff --git a/doc/administration/sidekiq/sidekiq_health_check.md b/doc/administration/sidekiq/sidekiq_health_check.md index 74b478c1913..9da4a59dc42 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq Health Check **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_job_migration.md b/doc/administration/sidekiq/sidekiq_job_migration.md index 10a1faea850..ef79ed8eded 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq job migration Rake tasks **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_memory_killer.md b/doc/administration/sidekiq/sidekiq_memory_killer.md index cd69a47d283..6dcc97f2f7a 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: Cloud Connector -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reducing memory use diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md index 2990110150f..591d1e5f64d 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Sidekiq **(FREE SELF)** @@ -641,6 +641,11 @@ indicate that additional Sidekiq processes would be beneficial. Consider [adding additional Sidekiq processes](extra_sidekiq_processes.md) to compensate for removing the `sidekiq-cluster` service. +## CPU saturation in Redis caused by Sidekiq BRPOP calls + +Sidekiq `BROP` calls can cause CPU usage to increase on Redis. +Increase the [`SIDEKIQ_SEMI_RELIABLE_FETCH_TIMEOUT` environment variable](../environment_variables.md) to improve CPU usage on Redis. + ## Related topics - [Elasticsearch workers overload Sidekiq](../../integration/advanced_search/elasticsearch_troubleshooting.md#elasticsearch-workers-overload-sidekiq). diff --git a/doc/administration/silent_mode/index.md b/doc/administration/silent_mode/index.md index 4f68a765585..f72b715ac5e 100644 --- a/doc/administration/silent_mode/index.md +++ b/doc/administration/silent_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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Silent Mode **(FREE SELF)** @@ -25,8 +25,7 @@ There are multiple ways to enable Silent Mode: - **Web UI** - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. On the left sidebar, select **Settings > General**. 1. Expand **Silent Mode**, and toggle **Enable Silent Mode**. 1. Changes are saved immediately. @@ -55,8 +54,7 @@ There are multiple ways to disable Silent Mode: - **Web UI** - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Silent Mode**, and toggle **Enable Silent Mode**. 1. Changes are saved immediately. @@ -93,7 +91,7 @@ Outbound communications from the following features are silenced by Silent Mode. | [Executable integrations](../../user/project/integrations/index.md) | The integrations are not executed. | | [Service Desk](../../user/project/service_desk/index.md) | Incoming emails still raise issues, but the users who sent the emails to Service Desk are not notified of issue creation or comments on their issues. | | Outbound emails | | -| Outbound HTTP requests | Many HTTP requests are blocked where features are not blocked or skipped explicitly. These may produce errors. If a particular error is problematic for testing during Silent Mode, please consult [GitLab Support](https://about.gitlab.com/support/). | +| Outbound HTTP requests | Many HTTP requests are blocked where features are not blocked or skipped explicitly. These may produce errors. If a particular error is problematic for testing during Silent Mode, consult [GitLab Support](https://about.gitlab.com/support/). | ### Outbound communications that are not silenced diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index 06bf4978a6b..5e303fc79a8 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Signing outgoing email with S/MIME **(FREE SELF)** diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index b59432b0b9e..6b53c2b1d10 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto 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/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Snippets **(FREE SELF)** diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index 203f59b60f7..258af6b045b 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -1,8 +1,7 @@ --- stage: Create group: IDE -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 +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # External storage for static objects **(FREE SELF)** @@ -16,10 +15,9 @@ storage such as a content delivery network (CDN). To configure external storage for static objects: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository**. -1. Expand the **External storage for repository static objects** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **External storage for repository static objects**. 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage), use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. 1. Select **Save changes**. diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md index daee7b61670..57a23a25a08 100644 --- a/doc/administration/system_hooks.md +++ b/doc/administration/system_hooks.md @@ -1,8 +1,7 @@ --- stage: Manage group: Import and Integrate -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # System hooks **(FREE SELF)** @@ -53,9 +52,8 @@ For push and tag events, the same structure and deprecations are followed as [pr To create a system hook: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **System Hooks**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **System Hooks**. 1. Select **Add new webhook**. 1. Provide the **URL** and **Secret Token**. 1. Select the checkbox next to each optional **Trigger** you want to enable. diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index bf0774478ee..0a993542847 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform state administration **(FREE SELF)** @@ -36,7 +36,7 @@ When Terraform state administration is disabled: To disable Terraform administration, follow the steps below according to your installation. -Prerequisite: +Prerequisites: - You must be an administrator. diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md index e0f70cecb43..c5f4fed4ef8 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changing your time zone **(FREE SELF)** diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index 32b07d8c4af..b9e77e72c65 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Diagnostics tools **(FREE SELF)** diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 01c75c32366..57b2df000b1 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Rails Console Cheat Sheet **(FREE SELF)** @@ -56,11 +56,11 @@ This content has been moved to [Activate GitLab EE with a license file or key](. ### Registry Disk Space Usage by Project -Find this content in the [Container Registry troubleshooting documentation](../packages/container_registry.md#registry-disk-space-usage-by-project). +Find this content in the [container registry troubleshooting documentation](../packages/container_registry.md#registry-disk-space-usage-by-project). ### Run the Cleanup policy now -Find this content in the [Container Registry troubleshooting documentation](../packages/container_registry.md#run-the-cleanup-policy-now). +Find this content in the [container registry troubleshooting documentation](../packages/container_registry.md#run-the-cleanup-policy-now). ## Sidekiq diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md index 8be6abc180d..a59429f1aee 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting a GitLab installation **(FREE SELF)** @@ -14,7 +14,7 @@ for in this list, you should search the documentation. ## Troubleshooting guides -- [SSL](ssl.md) +- [SSL](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html) - [Geo](../geo/replication/troubleshooting.md) - [SAML](../../user/group/saml_sso/troubleshooting.md) - [Kubernetes cheat sheet](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html) @@ -47,7 +47,7 @@ who are aware of the risks. - [Troubleshooting Kubernetes](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html) - [Troubleshooting PostgreSQL](postgresql.md) - [Guide to test environments](test_environments.md) (for Support Engineers) -- [Troubleshooting SSL](ssl.md) +- [Troubleshooting SSL](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html) - Related links: - [Repairing and recovering broken Git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html) - [Testing with OpenSSL](https://www.feistyduck.com/library/openssl-cookbook/online/testing-with-openssl/index.html) diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index ae0ef44f0b1..6255cae3a30 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linux cheat sheet **(FREE SELF)** diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index e7965d451b6..315a68fb126 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL **(FREE SELF)** diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md deleted file mode 100644 index bf8e6b45fde..00000000000 --- a/doc/administration/troubleshooting/ssl.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html' -remove_date: '2023-10-27' ---- - -This document was moved to [another location](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html). - -<!-- This redirect file can be deleted after <2023-01-25>. --> -<!-- 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/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index 63ccbce9480..1d148a654b8 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Apps for a testing environment **(FREE SELF)** diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 6259304d68e..31d0781ee79 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads administration **(FREE SELF)** diff --git a/doc/administration/user_cohorts.md b/doc/administration/user_cohorts.md index c849d3115d2..fb9adc67dc0 100644 --- a/doc/administration/user_cohorts.md +++ b/doc/administration/user_cohorts.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cohorts **(FREE SELF)** @@ -34,7 +34,6 @@ How do we measure the activity of users? GitLab considers a user active if: To view user cohorts: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Cohorts** tab. diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index cb796ccb993..ec6dab525ac 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Modify global user settings **(FREE SELF)** diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index 6d186ef0af5..8af9387f821 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/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this What's new page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # What's new **(FREE ALL)** @@ -31,9 +31,8 @@ To access the **What's new** feature: You can configure **What's new** to display features based on the tier, or you can hide it. To configure it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **What's new**, and choose one of the following options: | Option | Description | diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index fd7c1825e8d..abbb968e35d 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Knowledge -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Wiki settings **(FREE SELF)** |
