Azure Key Vault 限制指南Azure Key Vault throttling guidance

限制进程可在启动后,用于限定对 Azure 服务发出的并发调用数,以防止过度使用资源。Throttling is a process you initiate that limits the number of concurrent calls to the Azure service to prevent overuse of resources. Azure Key Vault (AKV) 能够处理大量请求。Azure Key Vault (AKV) is designed to handle a high volume of requests. 在请求数过多的情况下,限制客户端请求可帮助 AKV 服务保持最佳性能和可靠性。If an overwhelming number of requests occurs, throttling your client's requests helps maintain optimal performance and reliability of the AKV service.

限制值因情况而异。Throttling limits vary based on the scenario. 例如,如果正在执行大量写入,则发生限制的可能性会比仅执行读取高。For example, if you are performing a large volume of writes, the possibility for throttling is higher than if you are only performing reads.

Key Vault 如何处理其限制?How does Key Vault handle its limits?

Key Vault 中的服务限制可防止资源滥用,确保所有 Key Vault 客户端的服务质量。Service limits in Key Vault prevent misuse of resources and ensure quality of service for all of Key Vault's clients. 当超过服务阈值时,Key Vault 会在一段时间内限制客户端发出其他任何请求,返回 HTTP 状态代码 429(请求过多),而请求会失败。When a service threshold is exceeded, Key Vault limits any further requests from that client for a period of time, returns HTTP status code 429 (Too many requests), and the request fails. Key Vault 会跟踪向限制值返回 429 计数的失败请求。Failed requests that return a 429 count towards the throttle limits tracked by Key Vault.

Key Vault 最初设计用于在部署时存储和检索机密。Key Vault was originally designed to be used to store and retrieve your secrets at deployment time. 世界已经演变,Key Vault 现在是在运行时用于存储和检索机密,而应用和服务往往希望将 Key Vault 当作数据库使用。The world has evolved, and Key Vault is being used at run-time to store and retrieve secrets, and often apps and services want to use Key Vault like a database. 当前的限制不支持高吞吐率。Current limits do not support high throughput rates.

Key Vault 最初是根据 Azure Key Vault 服务限制中指定的限制创建的。Key Vault was originally created with the limits specified in Azure Key Vault service limits. 下面是最大化 Key Vault 吞吐率的一些建议指导原则/最佳做法:To maximize your Key Vault through put rates, here are some recommended guidelines/best practices for maximizing your throughput:

  1. 确保已实施限制。Ensure you have throttling in place. 客户端必须遵循 429 指数退避策略,并确保按照下面的指导执行重试。Client must honor exponential back-off policies for 429's and ensure you are doing retries as per the guidance below.
  2. 将 Key Vault 流量划分到多个保管库和不同区域。Divide your Key Vault traffic amongst multiple vaults and different regions. 为每个安全性/可用性域使用单独的保管库。Use a separate vault for each security/availability domain. 如果你有 5 个应用,每个应用已划分到 2 个区域,则我们建议配置 10 个保管库,其中每个保管库包含应用和区域特有的机密。If you have five apps, each in two regions, then we recommend 10 vaults each containing the secrets unique to app and region. 所有事务类型的订阅范围限制是单个 Key Vault 限制的 5 倍。A subscription-wide limit for all transaction types is five times the individual key vault limit. 例如,每个订阅的“软件 - 其他”事务限制为每个订阅 10 秒内 10,000 个事务。For example, Software-other transactions per subscription are limited to 10,000 transactions in 10 seconds per subscription. 考虑在服务或应用中缓存机密,以便同时减少 Key Vault 的直接 RPS,并/或处理基于突发的流量。Consider caching the secret within your service or app to also reduce the RPS directly to key vault and/or handle burst based traffic. 还可以将流量划分到不同的区域,以最大程度地减少延迟并使用不同的订阅/保管库。You can also divide your traffic amongst different regions to minimize latency and use a different subscription/vault. 不要将超过订阅限制的流量发送到单个 Azure 区域中的 Key Vault 服务。Do not send more than the subscription limit to the Key Vault service in a single Azure region.
  3. 在内存中缓存从 Azure Key Vault 检索的机密,并尽可能地从内存中重新使用机密。Cache the secrets you retrieve from Azure Key Vault in memory, and reuse from memory whenever possible. 仅当缓存的副本停止工作(例如,因为它已在源中轮换)时,才从 Azure Key Vault 重新读取。Re-read from Azure Key Vault only when the cached copy stops working (e.g. because it got rotated at the source).
  4. Key Vault 是为你自己的服务机密设计的。Key Vault is designed for your own services secrets. 如果存储客户的机密(尤其是对于高吞吐量密钥存储方案),请考虑将密钥放在支持加密的数据库中或存储帐户中,并只将主密钥存储在 Azure Key Vault 中。If you are storing your customers' secrets (especially for high-throughput key storage scenarios), consider putting the keys in a database or storage account with encryption, and storing just the master key in Azure Key Vault.
  5. 可以在不访问 Key Vault 的情况下加密、包装和验证公钥操作,这不仅可以降低限制的风险,而且还能提高可靠性(前提是正确缓存公钥材料)。Encrypt, wrap, and verify public-key operations can be performed with no access to Key Vault, which not only reduces risk of throttling, but also improves reliability (as long as you properly cache the public key material).
  6. 如果使用 Key Vault 存储服务的凭据,请检查该服务是否支持使用 Azure AD 身份验证直接进行身份验证。If you use Key Vault to store credentials for a service, check if that service supports Azure AD Authentication to authenticate directly. 这可以减少 Key Vault 中的负载,提高可靠性并简化代码,因为 Key Vault 现在可以使用 Azure AD 令牌。This reduces the load on Key Vault, improves reliability and simplifies your code since Key Vault can now use the Azure AD token. 许多服务已改用 Azure AD 身份验证。在支持 Azure 资源托管标识的 Azure 服务中查看最新列表。Many services have moved to using Azure AD Auth. See the current list at Services that support managed identities for Azure resources.
  7. 考虑在一个较长的时间段内错开负载/部署,使其不会超过当前的 RPS 限制。Consider staggering your load/deployment over a longer period of time to stay under the current RPS limits.
  8. 如果应用包含多个需要读取相同机密的节点,请考虑使用扇出模式,让一个实体从 Key Vault 读取机密,并扇出到所有节点。If your app comprises multiple nodes that need to read the same secret(s), then consider using a fan out pattern, where one entity reads the secret from Key Vault, and fans out to all nodes. 仅在内存中缓存检索的机密。Cache the retrieved secrets only in memory. 如果你发现上述方案仍不能满足需求,请填写下表并联系我们,以确定可以添加多少附加容量(例如,以下示例仅供演示目的)。If you find that the above still does not meet your needs, please fill out the below table and contact us to determine what additional capacity can be added (example put below for illustrative purposes only).
保管库名称Vault name 保管库区域Vault Region 对象类型(机密、密钥或证书)Object type (Secret, Key, or Cert) 操作*Operation(s)* 键类型Key Type 密钥长度或曲线Key Length or Curve HSM 密钥?HSM key? 所需的稳定状态 RPSSteady state RPS needed 所需的峰值 RPSPeak RPS needed
https://mykeyvault.vault.azure.cn/ Key 签名Sign ECEC P-256P-256 No 200200 10001000

* 有关可能值的完整列表,请参阅 Azure Key Vault 操作* For a full list of possible values, see Azure Key Vault operations.

如果增加容量已获批准,请注意容量增加后的以下考虑因素:If additional capacity is approved, please note the following as result of the capacity increases:

  1. 数据一致性模型更改。Data consistency model changes. 将吞吐量容量更高的保管库加入允许列表后,Key Vault 服务数据一致性保证会发生更改(需要满足更大量的 RPS,因为底层 Azure 存储服务无法跟进)。Once a vault is allow listed with additional throughput capacity, the Key Vault service data consistency guarantee changes (necessary to meet higher volume RPS since the underlying Azure Storage service cannot keep up). 简而言之:In a nutshell:
  2. 不使用允许列表:Key Vault 服务在后续调用(例如Without allow listing: The Key Vault service will reflect the results of a write operation (eg. SecretGet、KeySign)中会立即反映写入操作(例如SecretSet, CreateKey) immediately in subsequent calls (eg. SecretSet、CreateKey)的结果。SecretGet, KeySign).
  3. 使用允许列表:Key Vault 服务在 60 秒内在后续调用(例如With allow listing: The Key Vault service will reflect the results of a write operation (eg. SecretGet、KeySign)中反映写入操作(例如SecretSet, CreateKey) within 60 seconds in subsequent calls (eg. SecretSet、CreateKey)的结果。SecretGet, KeySign).
  4. 客户端代码必须遵循 429 次重试的退避策略。Client code must honor back-off policy for 429 retries. 调用 Key Vault 服务的客户端代码在收到 429 响应代码时,不得立即重试 Key Vault 请求。The client code calling the Key Vault service must not immediately retry Key Vault requests when it receives a 429 response code. 此处发布的 Azure Key Vault 限制指导建议在收到 429 Http 响应代码时立即应用指数退避。The Azure Key Vault throttling guidance published here recommends applying exponential backoff when receiving a 429 Http response code.

如果出现限制值较高的有效业务用例,请与我们联系。If you have a valid business case for higher throttle limits, please contact us.

如何针对服务限制来限制应用How to throttle your app in response to service limits

以下是在服务受到限制时应实施的最佳做法The following are best practices you should implement when your service is throttled:

  • 减少每个请求的操作数。Reduce the number of operations per request.
  • 减少请求频率。Reduce the frequency of requests.
  • 避免立即重试。Avoid immediate retries.
    • 发出的所有请求要符合使用限制。All requests accrue against your usage limits.

实现应用的错误处理时,请使用 HTTP 错误代码 429 检测是否需要限制客户端。When you implement your app's error handling, use the HTTP error code 429 to detect the need for client-side throttling. 如果请求再次失败,错误代码为 HTTP 429,则仍会遇到 Azure 服务限制。If the request fails again with an HTTP 429 error code, you are still encountering an Azure service limit. 请继续使用推荐的客户端限制方法,重试请求直至成功。Continue to use the recommended client-side throttling method, retrying the request until it succeeds.

实现指数退避的代码如下所示。Code that implements exponential backoff is shown below.

SecretClientOptions options = new SecretClientOptions()
    {
        Retry =
        {
            Delay= TimeSpan.FromSeconds(2),
            MaxDelay = TimeSpan.FromSeconds(16),
            MaxRetries = 5,
            Mode = RetryMode.Exponential
         }
    };
    var credentialOption = new DefaultAzureCredentialOptions();
    credentialOption.AuthorityHost = new Uri("https://login.partner.microsoftonline.cn");
    var client = new SecretClient(new Uri(https://keyVaultName.vault.azure.cn"), new DefaultAzureCredential(credentialOption),options);
                                 
    //Retrieve Secret
    secret = client.GetSecret(secretName);

在客户端 C# 应用程序中使用此代码很简单。Using this code in a client C# application is straightforward.

出现 HTTP 错误代码 429 时,请使用指数延迟方法开始限制客户端:On HTTP error code 429, begin throttling your client using an exponential backoff approach:

  1. 等待 1 秒,然后重试请求Wait 1 second, retry request
  2. 如果仍受限制,请等待 2 秒,然后重试请求If still throttled wait 2 seconds, retry request
  3. 如果仍受限制,请等待 4 秒,然后重试请求If still throttled wait 4 seconds, retry request
  4. 如果仍受限制,请等待 8 秒,然后重试请求If still throttled wait 8 seconds, retry request
  5. 如果仍受限制,请等待 16 秒,然后重试请求If still throttled wait 16 seconds, retry request

此时,应不会收到 HTTP 429 响应代码。At this point, you should not be getting HTTP 429 response codes.