diff options
Diffstat (limited to 'doc/development/internal_api/internal_api_allowed.md')
-rw-r--r-- | doc/development/internal_api/internal_api_allowed.md | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/doc/development/internal_api/internal_api_allowed.md b/doc/development/internal_api/internal_api_allowed.md new file mode 100644 index 00000000000..83dbb54babd --- /dev/null +++ b/doc/development/internal_api/internal_api_allowed.md @@ -0,0 +1,109 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, api +--- + +# Internal allowed API + +The `internal/allowed` endpoint assesses whether a user has permission to perform +certain operations on the Git repository. It performs multiple checks, such as: + +- Ensuring the branch or tag name is acceptable. +- Whether or not the user has the authority to perform that action. + +## Endpoint definition + +The internal API endpoints are defined under +[`lib/api/internal`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/internal), +and the `/allowed` path is in +[`lib/api/internal/base.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb). + +## Use the endpoint + +`internal/allowed` is called when you: + +- Push to the repository. +- Perform actions on the repository through the GitLab user interface, such as + applying suggestions or using the GitLab IDE. + +Gitaly typically calls this endpoint. It is only called internally (by other parts +of the application) rather than by external users of the API. + +## Push checks + +A key part of the `internal/allowed` flow is the call to +`EE::Gitlab::Checks::PushRuleCheck`, which can perform the following checks: + +- `EE::Gitlab::Checks::PushRules::CommitCheck` +- `EE::Gitlab::Checks::PushRules::TagCheck` +- `EE::Gitlab::Checks::PushRules::BranchCheck` +- `EE::Gitlab::Checks::PushRules::FileSizeCheck` + +## Recursion + +Some of the Gitaly RPCs called by `internal/allowed` then, themselves, make calls +back to `internal/allowed`. These calls are now correlated with the original request. +Gitaly relies on the Rails application for authorization, and maintains no permissions model itself. + +These calls show up in the logs differently to the initial requests. {example} + +Because this endpoint can be called recursively, slow performance on this endpoint can result in an exponential performance impact. This documentation is in fact adapted from [the investigation into its performance](https://gitlab.com/gitlab-org/gitlab/-/issues/222247). + +## Known performance issues + +### Refs + +The number of [`refs`](https://git-scm.com/book/en/v2/Git-Internals-Git-References) +on the Git repository have a notable effect on the performance of `git` commands +called upon it. Gitaly RPCs are similarly affected. Certain `git` commands scan +through all refs, causing a notable impact on the speed of those commands. + +On the `internal/allowed` endpoint, the recursive nature of RPC calls mean the +ref counts have an exponential effect on performance. + +#### Environment refs + +[Stale environment refs](https://gitlab.com/gitlab-org/gitlab/-/issues/296625) +are a common example of excessive refs causing performance issues. Stale environment +refs can number into the tens of thousands on busy repositories, as they aren't +cleared up automatically. + +#### Dangling refs + +Dangling refs are created to prevent accidental deletion of objects from object pools. +Large numbers of these refs can exist, which may have potential performance implications. +For existing discussion around this issue, read +[`gitaly#1900`](https://gitlab.com/gitlab-org/gitaly/-/issues/1900). This issue +appears to have less effect than stale environment refs. + +### Pool repositories + +When a fork is created on GitLab, a central pool repository is created and the forks +are linked to it. This pool repository prevents duplication of data by storing +data common to other forks. However, the pool repository is not cleaned up in the +same manner as the standard repositories, and is more prone to the refs issue. + +## Feature flags + +### Parallel push checks + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `parallel_push_checks`. +On GitLab.com, by default this feature is not available. To make it available +per project, ask GitLab.com administrator to +[enable the feature flag](../../administration/feature_flags.md) named `parallel_push_checks`. +You should not use this feature for production environments. + +This experimental feature flag enables the endpoint to run multiple RPCs simultaneously, +reducing the overall time taken by roughly half. This time savings is achieved through +threading, and has potential side effects at large scale. On GitLab.com, this feature flag +is enabled only for `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` projects. +Without it, those projects routinely time out requests to the endpoint. When this +feature was deployed to all of GitLab.com, some pushes failed, presumably due to +exhausting resources like database connection pools. + +We recommend you enable this feature flag only if you are experiencing timeouts, and +only enable it for that specific project. |