diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-01-19 18:14:05 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-01-19 18:14:05 +0300 |
commit | b22f3af733282394aa18261c073adbec117a1d47 (patch) | |
tree | b1fff6ae393a9f4c0a95d2529f374bb538d90b50 /doc | |
parent | e67f3f55d2b887e13181a37e34275a82fce28b9a (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/graphql/reference/index.md | 20 | ||||
-rw-r--r-- | doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png | bin | 0 -> 94088 bytes | |||
-rw-r--r-- | doc/architecture/blueprints/runner_scaling/index.md | 239 | ||||
-rw-r--r-- | doc/development/index.md | 3 | ||||
-rw-r--r-- | doc/development/merge_request_performance_guidelines.md | 4 | ||||
-rw-r--r-- | doc/development/profiling.md | 14 | ||||
-rw-r--r-- | doc/development/service_ping/metrics_instrumentation.md | 6 | ||||
-rw-r--r-- | doc/development/testing_guide/best_practices.md | 5 | ||||
-rw-r--r-- | doc/update/deprecations.md | 16 | ||||
-rw-r--r-- | doc/user/analytics/repository_analytics.md | 5 | ||||
-rw-r--r-- | doc/user/group/img/group_code_coverage_analytics_v13_9.png | bin | 29915 -> 0 bytes | |||
-rw-r--r-- | doc/user/group/repositories_analytics/index.md | 6 |
12 files changed, 288 insertions, 30 deletions
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 738732f111a..3148fd1a6df 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -4336,6 +4336,25 @@ Input type: `TerraformStateUnlockInput` | <a id="mutationterraformstateunlockclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationterraformstateunlockerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.timelineEventDestroy` + +Input type: `TimelineEventDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationtimelineeventdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationtimelineeventdestroyid"></a>`id` | [`IncidentManagementTimelineEventID!`](#incidentmanagementtimelineeventid) | Timeline event ID to remove. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationtimelineeventdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationtimelineeventdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationtimelineeventdestroytimelineevent"></a>`timelineEvent` | [`TimelineEventType`](#timelineeventtype) | Timeline event. | + ### `Mutation.todoCreate` Input type: `TodoCreateInput` @@ -11837,6 +11856,7 @@ Maven metadata. | <a id="mergerequestautomergestrategy"></a>`autoMergeStrategy` | [`String`](#string) | Selected auto merge strategy. | | <a id="mergerequestavailableautomergestrategies"></a>`availableAutoMergeStrategies` | [`[String!]`](#string) | Array of available auto merge strategies. | | <a id="mergerequestcommitcount"></a>`commitCount` | [`Int`](#int) | Number of commits in the merge request. | +| <a id="mergerequestcommits"></a>`commits` | [`CommitConnection`](#commitconnection) | Merge request commits. (see [Connections](#connections)) | | <a id="mergerequestcommitswithoutmergecommits"></a>`commitsWithoutMergeCommits` | [`CommitConnection`](#commitconnection) | Merge request commits excluding merge commits. (see [Connections](#connections)) | | <a id="mergerequestconflicts"></a>`conflicts` | [`Boolean!`](#boolean) | Indicates if the merge request has conflicts. | | <a id="mergerequestcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the merge request was created. | diff --git a/doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png b/doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png Binary files differnew file mode 100644 index 00000000000..c3ba615784f --- /dev/null +++ b/doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png diff --git a/doc/architecture/blueprints/runner_scaling/index.md b/doc/architecture/blueprints/runner_scaling/index.md new file mode 100644 index 00000000000..8e47b5fda8c --- /dev/null +++ b/doc/architecture/blueprints/runner_scaling/index.md @@ -0,0 +1,239 @@ +--- +stage: none +group: unassigned +comments: false +description: 'Next Runner Auto-scaling Architecture' +--- + +# Next Runner Auto-scaling Architecture + +## Summary + +GitLab Runner is a core component of GitLab CI/CD. It makes it possible to run +CI/CD jobs in a reliable and concurrent environment. It has been initially +introduced by Kamil Trzciński in early 2015 to replace a Ruby version of the +same service. GitLab Runner written in Go turned out to be easier to use by the +wider community, it was more efficient and reliable than the previous, +Ruby-based, version. + +In February 2016 Kamil Trzciński [implemented an auto-scaling feature](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/53) +to leverage cloud infrastructure to run many CI/CD jobs in parallel. This +feature has become a foundation supporting CI/CD adoption on GitLab.com over +the years, where we now run around 4 million builds per day at peak. + +During the initial implementation a decision was made to use Docker Machine: + +> Is easy to use. Is well documented. Is well supported and constantly +> extended. It supports almost any cloud provider or virtualization +> infrastructure. We need minimal amount of changes to support Docker Machine: +> machine enumeration and inspection. We don't need to implement any "cloud +> specific" features. + +This design choice was crucial for the GitLab Runner success. Since that time +the auto-scaling feature has been used by many users and customers and enabled +rapid growth of CI/CD adoption on GitLab.com. + +We can not, however, continue using Docker Machine. Work on that project [was +paused in July 2018](https://github.com/docker/machine/issues/4537) and there +was no development made since that time (except for some highly important +security fixes). In 2018, after Docker Machine entered the “maintenance mode”, +we decided to create [our own fork](https://gitlab.com/gitlab-org/ci-cd/docker-machine) +to be able to keep using this and ship fixes and updates needed for our use case. +[On September 26th, 2021 the project got archived](https://github.com/docker/docker.github.io/commit/2dc8b49dcbe85686cc7230e17aff8e9944cb47a5) +and the documentation for it has been removed from the official page. This +means that the original reason to use Docker Machine is no longer valid too. + +To keep supporting our customers and the wider community we need to design a +new mechanism for GitLab Runner autoscaling. It not only needs to support +auto-scaling, but it also needs to do that in the way to enable us to build on +top of it to improve efficiency, reliability and availability. + +We call this new mechanism the “next GitLab Runner Scaling architecture”. + +_Disclaimer The following contain information related to upcoming products, +features, and functionality._ + +_It is important to note that the information presented is for informational +purposes only. Please do not rely on this information for purchasing or +planning purposes._ + +_As with all projects, the items mentioned in this document and linked pages are +subject to change or delay. The development, release and timing of any +products, features, or functionality remain at the sole discretion of GitLab +Inc._ + +## Proposal + +Currently, GitLab Runner auto-scaling can be configured in a few ways. Some +customers are successfully using an auto-scaled environment in Kubernetes. We +know that a custom and unofficial GitLab Runner version has been built to make +auto-scaling on Kubernetes more reliable. We recognize the importance of having +a really good Kubernetes solution for running multiple jobs in parallel, but +refinements in this area are out of scope for this architectural initiative. + +We want to focus on resolving problems with Docker Machine and replacing this +mechanism with a reliable and flexible mechanism. We might be unable to build a +drop-in replacement for Docker Machine, as there are presumably many reasons +why it has been deprecated. It is very difficult to maintain compatibility with +so many cloud providers, and it seems that Docker Machine has been deprecated +in favor of Docker Desktop, which is not a viable replacement for us. [This +issue](https://github.com/docker/roadmap/issues/245) contains a discussion +about how people are using Docker Machine right now, and it seems that GitLab +CI is one of the most frequent reasons for people to keep using Docker Machine. + +There is also an opportunity in being able to optionally run multiple jobs in a +single, larger virtual machine. We can’t do that today, but we know that this +can potentially significantly improve efficiency. We might want to build a new +architecture that makes it easier and allows us to test how efficient it is +with PoCs. Running multiple jobs on a single machine can also make it possible +to reuse what we call a “sticky context” - a space for build artifacts / user +data that can be shared between job runs. + +### 💡 Design a simple abstraction that users will be able to build on top of + +Because there is no viable replacement and we might be unable to support all +cloud providers that Docker Machine used to support, the key design requirement +is to make it really simple and easy for the wider community to write a custom +GitLab auto-scaling plugin, whatever cloud provider they might be using. We +want to design a simple abstraction that users will be able to build on top, as +will we to support existing workflows on GitLab.com. + +The designed mechanism should abstract what Docker Machine executor has been doing: +providing a way to create an external Docker environment, waiting to execute +jobs by provisioning this environment and returning credentials required to +perform these operations. + +The new plugin system should be available for all major platforms: Linux, +Windows, MacOS. + +### 💡 Migrate existing Docker Machine solution to a plugin + +Once we design and implement the new abstraction, we should be able to migrate +existing Docker Machine mechanisms to a plugin. This will make it possible for +users and customers to immediately start using the new architecture, but still +keep their existing workflows and configuration for Docker Machine. This will +give everyone time to migrate to the new architecture before we drop support +for the legacy auto-scaling entirely. + +### 💡 Build plugins for AWS, Google Cloud Platform and Azure + +Although we might be unable to add support for all the cloud providers that +Docker Machine used to support, it seems to be important to provide +GitLab-maintained plugins for the major cloud providers like AWS, Google Cloud +Platform and Azure. + +We should build them, presumably in separate repositories, in a way that they +are easy to contribute to, fork, modify for certain needs the wider community +team members might have. It should be also easy to install a new plugin without +the need of rebuilding GitLab Runner whenever it happens. + +### 💡 Write a solid documentation about how to build your own plugin + +It is important to show users how to build an auto-scaling plugin, so that they +can implement support for their own cloud infrastructure. + +Building new plugins should be simple, and with the support of great +documentation it should not require advanced skills, like understanding how +gRPC works. We want to design the plugin system in a way that the entry barrier +for contributing new plugins is very low. + +### 💡 Build a PoC to run multiple builds on a single machine + +We want to better understand what kind of efficiency can running multiple jobs +on a single machine bring. It is difficult to predict that, so ideally we +should build a PoC that will help us to better understand what we can expect +from this. + +To run this experiement we most likely we will need to build an experimental +plugin, that not only allows us to schedule running multiple builds on a single +machine, but also has a set of comprehensive metrics built into it, to make it +easier to understand how it performs. + +## Details + +How the abstraction for the custom provider will look exactly is something that +we will need to prototype, PoC and decide in a data-informed way. There are a +few proposals that we should describe in detail, develop requirements for, PoC +and score. We will choose the solution that seems to support our goals the +most. + +In order to describe the proposals we first need to better explain what part of +the GitLab Runner needs to be abstracted away. To make this easier to grasp +these concepts, let's take a look at the current auto-scaling architecture and +sequence diagram. + +![GitLab Runner Autoscaling Overview](gitlab-autoscaling-overview.png) + +On the diagrams above we see that currently a GitLab Runner Manager runs on a +machine that has access to a cloud provider’s API. It is using Docker Machine +to provision new Virtual Machines with Docker Engine installed and it +configures the Docker daemon there to allow external authenticated requests. It +stores credentials to such ephemeral Docker environments on disk. Once a +machine has been provisioned and made available for GitLab Runner Manager to +run builds, it is using one of the existing executors to run a user-provided +script. In auto-scaling, this is typically done using Docker executor. + +### Custom provider + +In order to reduce the scope of work, we only want to introduce the new +abstraction layer in one place. + +A few years ago we introduced the [Custom Executor](https://docs.gitlab.com/runner/executors/custom.html) +feature in GitLab Runner. It allows users to design custom build execution +methods. The custom executor driver can be implemented in any way - from a +simple shell script to a dedicated binary - that is then used by a Runner +through os/exec system calls. + +Thanks to the custom executor abstraction there is no more need to implement +new executors internally in Runner. Users who have specific needs can implement +their own drivers and don’t need to wait for us to make their work part of the +“official” GitLab Runner. As each driver is a separate project, it also makes +it easier to create communities around them, where interested people can +collaborate together on improvements and bug fixes. + +We want to design the new Custom Provider to replicate the success of the +Custom Executor. It will make it easier for users to build their own ways to +provide a context and an environment in which a build will be executed by one +of the Custom Executors. + +There are multiple solutions to implementing a custom provider abstraction. We +can use raw Go plugins, Hashcorp’s Go Plugin, HTTP interface or gRPC based +facade service. There are many solutions, and we want to choose the most +optimal one. In order to do that, we will describe the solutions in a separate +document, define requirements and score the solution accordingly. This will +allow us to choose a solution that will work best for us and the wider +community. + +## Status + +Status: RFC. + +## Who + +Proposal: + +<!-- vale gitlab.Spelling = NO --> + +| Role | Who +|------------------------------|------------------------------------------| +| Authors | Grzegorz Bizon, Tomasz Maczukin | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | Elliot Rushton, Cheryl Li | +| Product Manager | Darren Eastman, Jackie Porter | +| Domain Expert / Runner | Arran Walker | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Leadership | Elliot Rushton | +| Product | Darren Eastman | +| Engineering | Tomasz Maczukin | + +Domain experts: + +| Area | Who +|------------------------------|------------------------| +| Domain Expert / Runner | Arran Walker | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/development/index.md b/doc/development/index.md index a31bc2d5a6f..197c7f48398 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -264,8 +264,7 @@ the [reviewer values](https://about.gitlab.com/handbook/engineering/workflow/rev - [Caching guidelines](caching.md) for using caching in Rails under a GitLab environment. - [Merge request performance guidelines](merge_request_performance_guidelines.md) for ensuring merge requests do not negatively impact GitLab performance -- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or - tracking down N+1 queries using Bullet. +- [Profiling](profiling.md) a URL or tracking down N+1 queries using Bullet. - [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries masked by query caching, memory profiling and why should we avoid cached queries. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 69e9f7d16e3..106db862122 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -13,9 +13,7 @@ _every_ merge request **should** adhere to the guidelines outlined in this document. There are no exceptions to this rule unless specifically discussed with and agreed upon by backend maintainers and performance specialists. -To measure the impact of a merge request you can use -[Sherlock](profiling.md#sherlock). It's also highly recommended that you read -the following guides: +It's also highly recommended that you read the following guides: - [Performance Guidelines](performance.md) - [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md) diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 656b30402a6..789e0640933 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -108,20 +108,6 @@ Find more information about different sampling modes in the [Stackprof docs](htt This is enabled for all users that can access the performance bar. -## Sherlock - -Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_ -available when running GitLab in development mode _and_ when setting the -environment variable `ENABLE_SHERLOCK` to a non empty value. For example: - -```shell -ENABLE_SHERLOCK=1 bundle exec rails s -``` - -Sherlock is also [available though the GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/sherlock.md). - -Recorded transactions can be found by navigating to `/sherlock/transactions`. - ## Bullet Bullet is a Gem that can be used to track down N+1 query problems. Bullet section is diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md index 6fdbd1eea31..c98b0df92aa 100644 --- a/doc/development/service_ping/metrics_instrumentation.md +++ b/doc/development/service_ping/metrics_instrumentation.md @@ -33,6 +33,12 @@ We have built a domain-specific language (DSL) to define the metrics instrumenta ## Database metrics +- `operation`: Operations for the given `relation`, one of `count`, `distinct_count`. +- `relation`: `ActiveRecord::Relation` for the objects we want to perform the `operation`. +- `start`: Specifies the start value of the batch counting, by default is `relation.minimum(:id)`. +- `finish`: Specifies the end value of the batch counting, by default is `relation.maximum(:id)`. +- `cache_start_and_finish_as`: Specifies the cache key for `start` and `finish` values and sets up caching them. Use this call when `start` and `finish` are expensive queries that should be reused between different metric calculations. + [Example of a merge request that adds a database metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60022). ```ruby diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 0f768a51b66..fe0c4c13ba2 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -642,6 +642,11 @@ should either: It takes around one second to load tests that are using `fast_spec_helper` instead of 30+ seconds in case of a regular `spec_helper`. +WARNING: +To verify that code and its specs are well-isolated from Rails, run the spec +individually via `bin/rspec`. Don't use `bin/spring rspec` as it loads +`spec_helper` automatically. + ### `subject` and `let` variables The GitLab RSpec suite has made extensive use of `let`(along with its strict, non-lazy diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 371018896ed..7388f4baf83 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -487,7 +487,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### Coverage guided fuzzing schemas below 14.0.0 @@ -505,7 +505,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### DAST schemas below 14.0.0 @@ -523,7 +523,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will cause [warning to be displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### Dependency scanning schemas below 14.0.0 @@ -541,7 +541,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will cause [warning to be displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### Enforced validation of security report schemas @@ -559,7 +559,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### Godep support in License Compliance @@ -635,7 +635,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### Secret detection schemas below 14.0.0 @@ -653,7 +653,7 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ### Sidekiq metrics and health checks configuration @@ -701,7 +701,7 @@ Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distr The `merged_by` field in the [merge request API](https://docs.gitlab.com/ee/api/merge_requests.html#list-merge-requests) is being deprecated and will be removed in GitLab 15.0. This field is being replaced with the `merge_user` field (already present in GraphQL) which more correctly identifies who merged a merge request when performing actions (merge when pipeline succeeds, add to merge train) other than a simple merge. -**Planned removal milestone: 15.0 ()** +**Planned removal milestone: 15.0 (2022-05-22)** ## 14.8 diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 42b3e96c340..5fd4a567b58 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Repository analytics **(FREE)** +# Repository analytics for projects **(FREE)** Use repository analytics to view information about a project's Git repository: @@ -35,4 +35,5 @@ To review repository analytics for a project: ## How repository analytics chart data is updated -Data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. +Data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. +Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_9.png b/doc/user/group/img/group_code_coverage_analytics_v13_9.png Binary files differdeleted file mode 100644 index 8cd71396381..00000000000 --- a/doc/user/group/img/group_code_coverage_analytics_v13_9.png +++ /dev/null diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 763b8eb1ae3..2487ab188e8 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -9,7 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. -![Group repositories analytics](../img/group_code_coverage_analytics_v13_9.png) +Repositories analytics for groups provides information about test coverage for all projects in a group. An +[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/273527) to also extend support for all projects in +subgroups. + +It is similar to [repository analytics for projects](../../analytics/repository_analytics.md). ## Current group code coverage |