feat: add quotas (#4779)

adds possibilities to cap authenticated requests and execution seconds of actions on a defined intervall

docs/docs/apis/proto/system.md

@@ -88,7 +88,7 @@ This might take some time
 > **rpc** RemoveInstance([RemoveInstanceRequest](#removeinstancerequest))
 [RemoveInstanceResponse](#removeinstanceresponse)
 
-Removes a instances
+Removes an instance
 This might take some time
 
 
@@ -228,6 +228,30 @@ failed event. You can find out if it worked on the `failure_count`
     DELETE: /failedevents/{database}/{view_name}/{failed_sequence}
 
 
+### AddQuota
+
+> **rpc** AddQuota([AddQuotaRequest](#addquotarequest))
+[AddQuotaResponse](#addquotaresponse)
+
+Creates a new quota
+
+
+
+    POST: /instances/{instance_id}/quotas
+
+
+### RemoveQuota
+
+> **rpc** RemoveQuota([RemoveQuotaRequest](#removequotarequest))
+[RemoveQuotaResponse](#removequotaresponse)
+
+Removes a quota
+
+
+
+    DELETE: /instances/{instance_id}/quotas/{unit}
+
+
 
 
 
@@ -326,6 +350,34 @@ failed event. You can find out if it worked on the `failure_count`
 
 
 
+### AddQuotaRequest
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| instance_id |  string | - | string.min_len: 1<br /> string.max_len: 200<br />  |
+| unit |  zitadel.quota.v1.Unit | the unit a quota should be imposed on | enum.defined_only: true<br /> enum.not_in: [0]<br />  |
+| from |  google.protobuf.Timestamp | the starting time from which the current quota period is calculated from. This is relevant for querying the current usage. | timestamp.required: true<br />  |
+| reset_interval |  google.protobuf.Duration | the quota periods duration | duration.required: true<br />  |
+| amount |  uint64 | the quota amount of units | uint64.gt: 0<br />  |
+| limit |  bool | whether ZITADEL should block further usage when the configured amount is used |  |
+| notifications | repeated zitadel.quota.v1.Notification | the handlers, ZITADEL executes when certain quota percentages are reached |  |
+
+
+
+
+### AddQuotaResponse
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| details |  zitadel.v1.ObjectDetails | - |  |
+
+
+
+
 ### ChangeSubscriptionRequest
 
 
@@ -558,19 +610,6 @@ This is an empty response
 
 
 
-### GetUsageResponse
-
-
-
-| Field | Type | Description | Validation |
-| ----- | ---- | ----------- | ----------- |
-| details |  zitadel.v1.ObjectDetails | - |  |
-| executed_requests |  uint64 | - |  |
-| executed_action_mins |  uint64 | - |  |
-
-
-
-
 ### HealthzRequest
 This is an empty request
 
@@ -760,6 +799,29 @@ This is an empty response
 
 
 
+### RemoveQuotaRequest
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| instance_id |  string | - | string.min_len: 1<br /> string.max_len: 200<br />  |
+| unit |  zitadel.quota.v1.Unit | - |  |
+
+
+
+
+### RemoveQuotaResponse
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| details |  zitadel.v1.ObjectDetails | - |  |
+
+
+
+
 ### SetPrimaryDomainRequest
 
 

docs/docs/self-hosting/manage/production.md

@@ -140,3 +140,7 @@ DefaultInstance:
 - Probably, you also want to [apply your custom branding](/guides/manage/customize/branding), [hook into certain events](/guides/manage/customize/behavior), [customize texts](/guides/manage/customize/texts) or [add metadata to your users](/guides/manage/customize/user-metadata).
 - If you want to automatically create ZITADEL resources, you can use the [ZITADEL Terraform Provider](/guides/manage/terraform/basics).
 
+## Quotas
+
+If you host ZITADEL as a service,
+you might want to [limit usage and/or execute tasks on certain usage units and levels](/self-hosting/manage/quotas).

docs/docs/self-hosting/manage/quotas.md

@@ -0,0 +1,60 @@
+---
+title: Usage Quotas
+---
+
+Quotas is an enterprise feature that is relevant if you want to host ZITADEL as a service.
+It enables you to limit usage and/or register webhooks that trigger on configurable usage levels for certain units.
+For example, you might want to report usage to an external billing tool and notify users when 80 percent of a quota is exhausted.
+Quotas are currently supported [for the instance level only](/concepts/structure/instance).
+Please refer to the [system API docs](/apis/proto/system#addquota) for detailed explanations about how to use the quotas feature.
+
+ZITADEL supports limiting authenticated requests and action run seconds
+
+## Authenticated Requests
+
+For using the quotas feature for authenticated requests you have to enable the database logstore for access logs in your ZITADEL configurations LogStore section:
+
+```yaml
+LogStore:
+  Access:
+    Database:
+      # If enabled, all access logs are stored in the database table logstore.access
+      Enabled: false
+      # Logs that are older than the keep duration are cleaned up continuously
+      Keep: 2160h # 90 days
+      # CleanupInterval defines the time between cleanup iterations
+      CleanupInterval: 4h
+      # Debouncing enables to asynchronously emit log entries, so the normal execution performance is not impaired
+      # Log entries are held in-memory until one of the conditions MinFrequency or MaxBulkSize meets.
+      Debounce:
+        MinFrequency: 2m
+        MaxBulkSize: 100
+```
+
+If a quota is configured to limit requests and the quotas amount is exhausted, all further requests are blocked except requests to the System API.
+Also, a cookie is set, to make it easier to block further traffic before it reaches your ZITADEL runtime.
+
+## Action Run Seconds
+
+For using the quotas feature for action run seconds you have to enable the database logstore for execution logs in your ZITADEL configurations LogStore section:
+
+```yaml
+LogStore:
+  Execution:
+    Database:
+      # If enabled, all action execution logs are stored in the database table logstore.execution
+      Enabled: false
+      # Logs that are older than the keep duration are cleaned up continuously
+      Keep: 2160h # 90 days
+      # CleanupInterval defines the time between cleanup iterations
+      CleanupInterval: 4h
+      # Debouncing enables to asynchronously emit log entries, so the normal execution performance is not impaired
+      # Log entries are held in-memory until one of the conditions MinFrequency or MaxBulkSize meets.
+      Debounce:
+        MinFrequency: 0s
+        MaxBulkSize: 0
+```
+
+If a quota is configured to limit action run seconds and the quotas amount is exhausted, all further actions will fail immediately with a context timeout exceeded error.
+The action that runs into the limit also fails with the context timeout exceeded error.
+

docs/sidebars.js

@@ -265,7 +265,7 @@ module.exports = {
         "self-hosting/deploy/compose",
         "self-hosting/deploy/knative",
         "self-hosting/deploy/kubernetes",
-        "self-hosting/deploy/loadbalancing-example/loadbalancing-example",
+        "self-hosting/deploy/loadbalancing-example/loadbalancing-example"
       ],
     },
     {
@@ -282,6 +282,7 @@ module.exports = {
         "self-hosting/manage/tls_modes",
         "self-hosting/manage/database/database",
         "self-hosting/manage/updating_scaling",
+        "self-hosting/manage/quotas"
       ],
     },
   ],
@@ -334,7 +335,10 @@ module.exports = {
       type: "category",
       label: "Features",
       collapsed: false,
-      items: ["concepts/features/actions", "concepts/features/selfservice"],
+      items: [
+        "concepts/features/actions",
+        "concepts/features/selfservice"
+      ],
     },
   ],
   manuals: [