Merge branch 'russell/document-new-storage-quota-totals' into 'master'

Document new storage quota totals

See merge request gitlab-org/gitlab!47467

doc/ci/pipelines/pipeline_artifacts.md

@@ -13,6 +13,6 @@ Pipeline artifacts are used by the [test coverage visualization feature](../../u
 
 ## Storage
 
-Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/group/index.md#storage-usage-quota). The **Artifacts** on the usage quote page is the sum of all job artifacts and pipeline artifacts.
+Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/usage_quotas.md#storage-usage-quota). The **Artifacts** on the Usage Quotas page is the sum of all job artifacts and pipeline artifacts.
 
 Pipeline artifacts are erased after one week.

doc/subscriptions/gitlab_com/index.md

@@ -303,10 +303,42 @@ Be aware that:
   be deducted from your Additional Minutes quota immediately after your purchase of additional
   minutes.
 
+## Storage subscription
+
+Projects have a free storage quota of 10 GB. To exceed this quota you must first [purchase one or
+more storage subscription units](#purchase-more-storage). Each unit provides 10 GB of additional
+storage per namespace. A storage subscription is renewed annually. For more details, see
+[Usage Quotas](../../user/usage_quotas.md).
+
+When the amount of purchased storage reaches zero, all projects over the free storage quota are
+locked. Projects can only be unlocked by purchasing more storage subscription units.
+
+### Purchase more storage
+
+To purchase more storage for either a personal or group namespace:
+
+1. Sign in to GitLab.com.
+1. From either your personal homepage or the group's page, go to **Settings > Usage Quotas**.
+1. For each locked project, total by how much its **Usage** exceeds the free quota and purchased
+   storage. You must purchase the storage increment that exceeds this total.
+1. Click **Purchase more storage** and you are taken to the Customers Portal.
+1. Click **Add new subscription**.
+1. Scroll to **Purchase add-on subscriptions** and select **Buy storage subscription**.
+1. In the **Subscription details** section select the name of the user or group from the dropdown.
+1. Enter the desired quantity of storage packs.
+1. In the **Billing information** section select the payment method from the dropdown.
+1. Select the **Privacy Policy** and **Terms of Service** checkbox.
+1. Select **Buy subscription**.
+1. Sign out of the Customers Portal.
+1. Switch back to the GitLab.com tab and refresh the page.
+
+The **Purchased storage available** total is incremented by the amount purchased. All locked
+projects are unlocked and their excess usage is deducted from the additional storage.
+
 ## Customers Portal
 
-GitLab provides the [Customers Portal](../index.md#customers-portal) where you can
-manage your subscriptions and your account details.
+The GitLab [Customers Portal](../index.md#customers-portal) enables you to manage your subscriptions
+and account details.
 
 ## Contact Support
 

doc/user/group/index.md

@@ -747,20 +747,6 @@ To enable prevent project forking:
 - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group.
 - **Integrations**: Configure [integrations](../admin_area/settings/project_integration_management.md) for your group.
 
-#### Storage usage quota **(STARTER)**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0.
-
-A group owner can check the aggregated storage usage for all the projects in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list.
-
-![Group storage usage quota](img/group_storage_usage_quota.png)
-
-The total usage of the storage is updated if any relevant event that
-will affect its value is triggered (e.g., a commit push).
-For performance reasons, we may delay the update up to 1 hour and 30 minutes.
-
-If your namespace shows `N/A` as the total storage usage, you can trigger a recalculation by pushing a commit to any project in that namespace.
-
 #### Group push rules **(STARTER)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8.

doc/user/usage_quotas.md

+---
+type: howto
+stage: Fulfillment
+group: Fulfillment
+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/#designated-technical-writers
+---
+
+# Storage usage quota
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0.
+> - Moved to GitLab Free.
+
+A project's repository has a free storage quota of 10 GB. When a project's repository reaches
+the quota it is locked. You cannot push changes to a locked project. To monitor the size of each
+repository in a namespace, including a breakdown for each project, you can
+[view storage usage](#view-storage-usage). To allow a project's repository to exceed the free quota
+you must purchase additional storage. For more details, see [Excess storage usage](#excess-storage-usage).
+
+## View storage usage
+
+To help manage storage, a namespace's owner can view:
+
+- Total storage used in the namespace
+- Total storage used per project
+- Breakdown of storage use per project, by storage type.
+
+To view storage usage, from the namespace's page go to **Settings > Usage Quotas** and select the
+**Storage** tab. The Usage Quotas statistics are updated every 90 minutes.
+
+If your namespace shows `N/A` as the total storage usage, push a commit to any project in that
+namespace to trigger a recalculation.
+
+A stacked bar graph shows the proportional storage used for the namespace, including a total per
+storage item. Click on each project's title to see a breakdown per storage item.
+
+## Storage usage statistics **(BRONZE ONLY)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247831) in GitLab 13.7.
+> - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default.
+> - It's enabled on GitLab.com.
+> - It's recommended for production use.
+
+CAUTION: **Warning:**
+This feature might not be available to you. Check the **version history** note above for details.
+
+The following storage usage statistics are available to an owner:
+
+- Total namespace storage used: Total amount of storage used across projects in this namespace.
+- Total excess storage used: Total amount of storage used that exceeds their allocated storage.
+- Purchased storage available: Total storage that has been purchased but is not yet used.
+
+## Excess storage usage
+
+Excess storage usage is the amount that a project's repository exceeds the free storage quota. If no
+purchased storage is available the project is locked. You cannot push changes to a locked project.
+To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage)
+for the namespace. When the purchase is completed, locked projects are automatically unlocked. The
+amount of purchased storage available must always be greater than zero.
+
+The **Storage** tab of the **Usage Quotas** page warns you of the following:
+
+- Purchased storage available is running low.
+- Projects that are at risk of being locked if purchased storage available is zero.
+- Projects that are locked because purchased storage available is zero. Locked projects are
+  marked with an information icon (**{information-o}**) beside their name.
+
+### Excess storage example
+
+The following example describes an excess storage scenario for namespace _Example Company_:
+
+| Repository | Storage used | Excess storage | Quota  | Status            |
+|------------|--------------|----------------|--------|-------------------|
+| Red        | 10 GB        | 0 GB           | 10 GB  | Locked **{lock}** |
+| Blue       | 8 GB         | 0 GB           | 10 GB  | Not locked        |
+| Green      | 10 GB        | 0 GB           | 10 GB  | Locked **{lock}** |
+| Yellow     | 2 GB         | 0 GB           | 10 GB  | Not locked        |
+| **Totals** | **30 GB**    | **0 GB**       | -      | -                 |
+
+The Red and Green projects are locked because their repositories have reached the quota. In this
+example, no additional storage has yet been purchased.
+
+To unlock the Red and Green projects, 50 GB additional storage is purchased.
+
+Assuming the Green and Red projects' repositories grow past the 10 GB quota, the purchased storage
+available decreases. All projects remain unlocked because 40 GB purchased storage is available:
+50 GB (purchased storage) - 10 GB (total excess storage used).
+
+| Repository | Storage used | Excess storage | Quota   | Status            |
+|------------|--------------|----------------|---------|-------------------|
+| Red        | 15 GB        | 5 GB           | 10 GB   | Not locked        |
+| Blue       | 14 GB        | 4 GB           | 10 GB   | Not locked        |
+| Green      | 11 GB        | 1 GB           | 10 GB   | Not locked        |
+| Yellow     | 5 GB         | 0 GB           | 10 GB   | Not locked        |
+| **Totals** | **45 GB**    | **10 GB**      | -       | -                 |

ee/app/views/groups/usage_quotas/index.html.haml

@@ -21,4 +21,4 @@
     = render "namespaces/pipelines_quota/list",
       locals: { namespace: @group, projects: @projects }
   .tab-pane#storage-quota-tab
-    #js-storage-counter-app{ data: { namespace_path: @group.full_path, help_page_path: help_page_path('user/group/index.md', anchor: 'storage-usage-quota'), purchase_storage_url: url_to_purchase_storage, is_temporary_storage_increase_visible: temporary_storage_increase_visible?(@group).to_s } }
+    #js-storage-counter-app{ data: { namespace_path: @group.full_path, help_page_path: help_page_path('user/usage_quotas.md', anchor: 'storage-usage-quota'), purchase_storage_url: url_to_purchase_storage, is_temporary_storage_increase_visible: temporary_storage_increase_visible?(@group).to_s } }

ee/app/views/profiles/usage_quotas/index.html.haml

@@ -22,4 +22,4 @@
     = render "namespaces/pipelines_quota/list",
       locals: { namespace: @namespace, projects: @projects }
   .tab-pane#storage-quota-tab
-    #js-storage-counter-app{ data: { namespace_path: @namespace.full_path, help_page_path: help_page_path('user/group/index.md', anchor: 'storage-usage-quota'), purchase_storage_url: url_to_purchase_storage, is_temporary_storage_increase_visible: temporary_storage_increase_visible?(@namespace).to_s } }
+    #js-storage-counter-app{ data: { namespace_path: @namespace.full_path, help_page_path: help_page_path('user/usage_quotas.md', anchor: 'storage-usage-quota'), purchase_storage_url: url_to_purchase_storage, is_temporary_storage_increase_visible: temporary_storage_increase_visible?(@namespace).to_s } }