mirror of
https://github.com/zitadel/zitadel.git
synced 2025-04-19 08:21:33 +00:00
ed0bc39ea4
* docs: fix init description typos * feat: block instances using limits * translate * unit tests * fix translations * redirect /ui/login * fix http interceptor * cleanup * fix http interceptor * fix: delete cookies on gateway 200 * add integration tests * add command test * docs * fix integration tests * add bulk api and integration test * optimize bulk set limits * unit test bulk limits * fix broken link * fix assets middleware * fix broken link * validate instance id format * Update internal/eventstore/search_query.go Co-authored-by: Livio Spring <livio.a@gmail.com> * remove support for owner bulk limit commands * project limits to instances * migrate instances projection * Revert "migrate instances projection" This reverts commit 214218732a56e6df823beac1972adfcf8beeded5. * join limits, remove owner * remove todo * use optional bool * normally validate instance ids * use 302 * cleanup * cleanup * Update internal/api/grpc/system/limits_converter.go Co-authored-by: Livio Spring <livio.a@gmail.com> * remove owner * remove owner from reset --------- Co-authored-by: Livio Spring <livio.a@gmail.com>
139 lines
7.5 KiB
Markdown
139 lines
7.5 KiB
Markdown
---
|
|
title: Usage Control
|
|
sidebar_label: Usage Control
|
|
---
|
|
|
|
If you have a self-hosted ZITADEL environment, you can limit the usage of your [instances](/concepts/structure/instance).
|
|
For example, if you provide your customers [their own virtual instances](/concepts/structure/instance#multiple-virtual-instances) with access on their own domains, you can design a pricing model based on the usage of their instances.
|
|
The usage control features are currently limited to the instance level only.
|
|
|
|
## Block Instances
|
|
|
|
You can block an instance using the [system API](/category/apis/resources/system/limits).
|
|
|
|
Most requests to a blocked instance are rejected with the HTTP status *429 Too Many Requests* or the gRPC status *8 Resource Exhausted*.
|
|
However, requests to the [system API](/apis/introduction#system) are still allowed.
|
|
Requests to paths with the prefix */ui/login* return a redirect with HTTP status *302 Found* to */ui/console*, where the user is guided to *InstanceManagementURL*.
|
|
Blocked HTTP requests additionally set a cookie to make it easy to block traffic before it reaches your ZITADEL runtime, for example with a WAF rule.
|
|
|
|
You can block new instances by default using the *DefaultInstance.Limits.Block* runtime configuration.
|
|
The following snippets shows the default YAML:
|
|
|
|
```yaml
|
|
DefaultInstance:
|
|
Limits:
|
|
# If Block is true, all requests except to /ui/console or the system API are blocked and /ui/login is redirected to /ui/console.
|
|
# /ui/console shows a message that the instance is blocked with a link to Console.InstanceManagementURL
|
|
Block: # ZITADEL_DEFAULTINSTANCE_LIMITS_BLOCK
|
|
```
|
|
|
|
## Limit Audit Trails
|
|
|
|
You can restrict the maximum age of events returned by the following APIs:
|
|
|
|
- [Events Search](/apis/resources/admin/admin-service-list-events), See also the [Event API guide](guides/integrate/event-api)
|
|
- [My User History](/apis/resources/auth/auth-service-list-my-user-changes)
|
|
- [A Users History](/apis/resources/mgmt/management-service-list-user-changes)
|
|
- [An Applications History](/apis/resources/mgmt/management-service-list-app-changes)
|
|
- [An Organizations History](/apis/resources/mgmt/management-service-list-org-changes)
|
|
- [A Projects History](/apis/resources/mgmt/management-service-list-project-changes)
|
|
- [A Project Grants History](/apis/resources/mgmt/management-service-list-project-grant-changes)
|
|
|
|
You can set a global default limit as well as a default limit [for new virtual instances](/concepts/structure/instance#multiple-virtual-instances) in the ZITADEL configuration.
|
|
The following snippets shows the defaults:
|
|
|
|
```yaml
|
|
# AuditLogRetention limits the number of events that can be queried via the events API by their age.
|
|
# A value of "0s" means that all events are available.
|
|
# If an audit log retention is set using an instance limit, it will overwrite the system default.
|
|
AuditLogRetention: 0s # ZITADEL_AUDITLOGRETENTION
|
|
DefaultInstance:
|
|
Limits:
|
|
# AuditLogRetention limits the number of events that can be queried via the events API by their age.
|
|
# A value of "0s" means that all events are available.
|
|
# If this value is set, it overwrites the system default unless it is not reset via the admin API.
|
|
AuditLogRetention: # ZITADEL_DEFAULTINSTANCE_LIMITS_AUDITLOGRETENTION
|
|
```
|
|
|
|
You can also set a limit for [a specific virtual instance](/concepts/structure/instance#multiple-virtual-instances) using the [system API](/category/apis/resources/system/limits).
|
|
|
|
## Quotas
|
|
|
|
Quotas 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.
|
|
|
|
ZITADEL supports limiting authenticated requests and action run seconds with quotas.
|
|
|
|
For using the quotas feature you have to activate it in your ZITADEL configurations *Quotas* section.
|
|
The following snippets shows the defaults:
|
|
|
|
```yaml
|
|
Quotas:
|
|
Access:
|
|
# If enabled, authenticated requests are counted and potentially limited depending on the configured quota of the instance
|
|
Enabled: false # ZITADEL_QUOTAS_ACCESS_ENABLED
|
|
Debounce:
|
|
MinFrequency: 0s # ZITADEL_QUOTAS_ACCESS_DEBOUNCE_MINFREQUENCY
|
|
MaxBulkSize: 0 # ZITADEL_QUOTAS_ACCESS_DEBOUNCE_MAXBULKSIZE
|
|
ExhaustedCookieKey: "zitadel.quota.exhausted" # ZITADEL_QUOTAS_ACCESS_EXHAUSTEDCOOKIEKEY
|
|
ExhaustedCookieMaxAge: "300s" # ZITADEL_QUOTAS_ACCESS_EXHAUSTEDCOOKIEMAXAGE
|
|
Execution:
|
|
# If enabled, all action executions are counted and potentially limited depending on the configured quota of the instance
|
|
Enabled: false # ZITADEL_QUOTAS_EXECUTION_DATABASE_ENABLED
|
|
Debounce:
|
|
MinFrequency: 0s # ZITADEL_QUOTAS_EXECUTION_DEBOUNCE_MINFREQUENCY
|
|
MaxBulkSize: 0 # ZITADEL_QUOTAS_EXECUTION_DEBOUNCE_MAXBULKSIZE
|
|
```
|
|
|
|
Once you have activated the quotas feature, you can configure quotas [for your virtual instances](/concepts/structure/instance#multiple-virtual-instances) using the [system API](/category/apis/resources/system/quotas) or the *DefaultInstances.Quotas* section.
|
|
The following snippets shows the defaults:
|
|
|
|
```yaml
|
|
DefaultInstance:
|
|
Quotas:
|
|
# Items take a slice of quota configurations, whereas, for each unit type and instance, one or zero quotas may exist.
|
|
# The following unit types are supported
|
|
|
|
# "requests.all.authenticated"
|
|
# The sum of all requests to the ZITADEL API with an authorization header,
|
|
# excluding the following exceptions
|
|
# - Calls to the System API
|
|
# - Calls that cause internal server errors
|
|
# - Failed authorizations
|
|
# - Requests after the quota already exceeded
|
|
|
|
# "actions.all.runs.seconds"
|
|
# The sum of all actions run durations in seconds
|
|
Items:
|
|
# - Unit: "requests.all.authenticated"
|
|
# # From defines the starting time from which the current quota period is calculated.
|
|
# # This is relevant for querying the current usage.
|
|
# From: "2023-01-01T00:00:00Z"
|
|
# # ResetInterval defines the quota periods duration
|
|
# ResetInterval: 720h # 30 days
|
|
# # Amount defines the number of units for this quota
|
|
# Amount: 25000
|
|
# # Limit defines whether ZITADEL should block further usage when the configured amount is used
|
|
# Limit: false
|
|
# # Notifications are emitted by ZITADEL when certain quota percentages are reached
|
|
# Notifications:
|
|
# # Percent defines the relative amount of used units, after which a notification should be emitted.
|
|
# - Percent: 100
|
|
# # Repeat defines, whether a notification should be emitted each time when a multitude of the configured Percent is used.
|
|
# Repeat: true
|
|
# # CallURL is called when a relative amount of the quota is used.
|
|
# CallURL: "https://httpbin.org/post"
|
|
```
|
|
|
|
### Exhausted Authenticated Requests
|
|
|
|
If a quota is configured to limit requests and the quotas amount is exhausted, all further authenticated requests are blocked except requests to the [system API](/apis/introduction#system).
|
|
Also, a cookie is set, to make it easier to block further traffic before it reaches your ZITADEL runtime, for example with a WAF rule.
|
|
The console is still served, but it only shows a dialog that says that the instance is blocked with a link to *InstanceManagementURL*.
|
|
|
|
### Exhausted Action Run Seconds
|
|
|
|
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.
|
|
|