Merge branch '335075_documentation_for_files_api_rate_limiting' into 'master'

Add documentation to Files API Rate Limits

See merge request gitlab-org/gitlab!68645

doc/administration/instance_limits.md

@@ -88,6 +88,20 @@ requests per user. For more information, read
 
 - **Default rate limit**: Disabled by default.
 
+### Files API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available,
+ask an administrator to [enable the `files_api_throttling` flag](../administration/feature_flags.md). On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.
+The feature is not ready for production use.
+
+This setting limits the request rate on the Packages API per user or IP address. For more information, read
+[Files API rate limits](../user/admin_area/settings/files_api_rate_limits.md).
+
+- **Default rate limit**: Disabled by default.
+
 ### Import/Export
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2.

doc/api/repository_files.md

@@ -7,9 +7,11 @@ type: reference, api
 
 # Repository files API **(FREE)**
 
-**CRUD for repository files**
+You can fetch, create, update, and delete files in your repository with this API.
+You can also [configure rate limits](../user/admin_area/settings/files_api_rate_limits.md)
+for this API.
 
-**Create, read, update, and delete repository files using this API**
+## Available scopes for personal access tokens
 
 The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted
 in the following table.
@@ -19,8 +21,6 @@ in the following table.
 | `read_repository` | Allows read-access to the repository files. |
 | `api` | Allows read-write access to the repository files. |
 
-> `read_repository` scope was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23534) in GitLab 11.6.
-
 ## Get file from repository
 
 Allows you to receive information about file in repository like name, size,

doc/security/rate_limits.md

@@ -35,6 +35,7 @@ These are rate limits you can set in the Admin Area of your instance:
 - [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md)
 - [Package registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md)
 - [Git LFS rate limits](../user/admin_area/settings/git_lfs_rate_limits.md)
+- [Files API rate limits](../user/admin_area/settings/files_api_rate_limits.md)
 
 ## Non-configurable limits
 

doc/user/admin_area/settings/files_api_rate_limits.md

+---
+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
+---
+
+# Files API rate limits **(FREE SELF)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it
+available, ask an administrator to [enable the `files_api_throttling` flag](../../../administration/feature_flags.md).
+On GitLab.com, this feature is available but can be configured by GitLab.com
+administrators only. The feature is not ready for production use.
+
+The [Repository files API](../../../api/repository_files.md) enables you to
+fetch, create, update, and delete files in your repository. To improve the security
+and durability of your web application, you can enforce
+[rate limits](../../../security/rate_limits.md) on this API. Any rate limits you
+create for the Files API override the [general user and IP rate limits](user_and_ip_rate_limits.md).
+
+## Define Files API rate limits
+
+Rate limits for the Files API are disabled by default. When enabled, they supersede
+the general user and IP rate limits for requests to the
+[Repository files API](../../../api/repository_files.md). You can keep any general user
+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.
+
+Prerequisites:
+
+- You must have the Administrator role for your instance.
+- The `files_api_throttling` feature flag must be enabled.
+
+To override the general user and IP rate limits for requests to the Repository files API:
+
+1. On the top bar, select **Menu > Admin**.
+1. On the left sidebar, select **Settings > Network**.
+1. Expand **Files API Rate Limits**.
+1. Select the check boxes for the types of rate limits you want to enable:
+   - **Unauthenticated API request rate limit**
+   - **Authenticated API request rate limit**
+1. _If you enabled unauthenticated API request rate limits:_
+   1. Select the **Max unauthenticated API requests per period per IP**.
+   1. Select the **Unauthenticated API rate limit period in seconds**.
+1. _If you enabled authenticated API request rate limits:_
+   1. Select the **Max authenticated API requests per period per user**.
+   1. Select the **Authenticated API rate limit period in seconds**.
+
+## Resources
+
+- [Rate limits](../../../security/rate_limits.md)
+- [Repository files API](../../../api/repository_files.md)
+- [User and IP rate limits](user_and_ip_rate_limits.md)

doc/user/admin_area/settings/index.md

@@ -98,6 +98,7 @@ To access the default page for Admin Area settings:
 | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. |
 | [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. |
 | [Git LFS Rate Limits](git_lfs_rate_limits.md) | Configure specific limits for Git LFS requests that supersede the user and IP rate limits. |
+| [Files API Rate Limits](files_api_rate_limits.md) | Configure specific limits for Files API requests that supersede the user and IP rate limits. |
 | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. |
 | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. |
 | [Incident Management](../../../operations/incident_management/index.md) Limits | Limit the number of inbound alerts that can be sent to a project. |

doc/user/admin_area/settings/user_and_ip_rate_limits.md

@@ -189,6 +189,8 @@ The possible names are:
 - `throttle_unauthenticated_packages_api`
 - `throttle_authenticated_packages_api`
 - `throttle_authenticated_git_lfs`
+- `throttle_unauthenticated_files_api`
+- `throttle_authenticated_files_api`
 
 For example, to try out throttles for all authenticated requests to
 non-protected paths can be done by setting