Create a rate limit quota

1. Enable a file audit device which outputs to /var/log/vault-audit.log (or your desired file location).

   $ vault audit enable file file_path="/var/log/vault-audit.log"
   

2. To enable the audit logging for rate limit quotas, execute the following command.

   $ vault write sys/quotas/config enable_rate_limit_audit_logging=true
   

3. Read the quota configuration to verify.

   $ vault read sys/quotas/config
   
   Key                                   Value
   ---                                   -----
   absolute_rate_limit_exempt_paths      []
   enable_rate_limit_audit_logging       true
   enable_rate_limit_response_headers    false
   rate_limit_exempt_paths               []
   

1. Enable file audit device.

   First, create the HTTP request payload specifying the audit log path to be /var/log/vault-audit.log (or your desired file location).

   $ tee audit-payload.json <<EOF
   {
     "type": "file",
     "options": {
         "file_path": "/var/log/vault-audit.log"
     }
   }
   EOF
   

   Use the sys/audit endpoint to enable file audit log.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST \
       --data @audit-payload.json \
       $VAULT_ADDR/v1/sys/audit/file
   

   Set the target file_path to your desired location.

2. Create the HTTP request payload to enable the rate limit quota audit logging.

   $ tee payload.json <<EOF
   {
      "enable_rate_limit_audit_logging": true
   }
   EOF
   

3. Invoke the sys/quotas/config endpoint.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST \
       --data @payload.json \
       $VAULT_ADDR/v1/sys/quotas/config
   

4. Read the quota configuration to verify.

   $ curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
       $VAULT_ADDR/v1/sys/quotas/config | jq -r ".data"
   

   Example output:

   {
      "absolute_rate_limit_exempt_paths": [],
      "enable_rate_limit_audit_logging": true,
      "enable_rate_limit_response_headers": false,
      "rate_limit_exempt_paths": []
   }
   

Use vault write and the sys/quotas/rate-limit/{quota-name} path to create a new rate limit quota.

$ vault write sys/quotas/rate-limit/<QUOTA_NAME> \
    name="<QUOTA_RULE_NAME>" \
    path="<TARGET_PATH>" \
    rate=<ALLOWED_REQUEST_RATE> \
    role="<ROLE_NAME>" \
    interval=<DURATION_OF_RATE_LIMIT> \
    block_interval=<DURATION_TO_BLOCK_REQUESTS> \
    inheritable=<BOOLEAN> \

Example: Create a rate limit quota applies on the Vault cluster.

1. Create a rate limit quota named, "global-rate" which limits inbound workload to 100 requests per second.

   $ vault write sys/quotas/rate-limit/global-rate rate=100
   Success! Data written to: sys/quotas/rate-limit/global-rate
   

2. Read the global-rate rule to verify its configuration.

   $ vault read sys/quotas/rate-limit/global-rate
   
   Key               Value
   ---               -----
   block_interval    0
   group_by          ip
   inheritable       true
   interval          1
   name              global-rate
   path              n/a
   rate              100
   role              n/a
   type              rate-limit
   

   Note

   In absence of path, this quota rule applies to the global level instead of a specific mount or namespace.

Example: Create a rate limit quota named, "transit-limit" which limits the access to the Transit secrets engine to be 1,000 requests per minute (60 seconds). It groups requests by their source IP address.

1. Enable Transit secrets engine at transit.

   $ vault secrets enable transit
   Success! Enabled the transit secrets engine at: transit/
   

2. Create a rate limit quota.

   $ vault write sys/quotas/rate-limit/transit-limit \
      path="transit" \
      rate=1000 \
      interval=60
   

   Output:

   Success! Data written to: sys/quotas/rate-limit/transit-limit
   

3. Read the transit-limit rule to verify its configuration.

   $ vault read sys/quotas/rate-limit/transit-limit
   

   Output:

   Key               Value
   ---               -----
   block_interval    0
   group_by          ip
   inheritable       true
   interval          60
   name              transit-limit
   path              transit/
   rate              1000
   role              n/a
   type              rate-limit
   

Path granularity

You can set the path to be deeper than the mount point (in this example, transit/).

Example: Create a rate limit quota named, "transit-order" to limit the data encryption requests using orders key to be 500 per second.

1. Create an encryption key named, "orders".

   $ vault write -f transit/keys/orders
   
   Key                       Value
   ---                       -----
   allow_plaintext_backup    false
   auto_rotate_period        0s
   deletion_allowed          false
   derived                   false
   exportable                false
   imported_key              false
   keys                      map[1:1695147293]
   latest_version            1
   min_available_version     0
   min_decryption_version    1
   min_encryption_version    0
   name                      orders
   supports_decryption       true
   supports_derivation       true
   supports_encryption       true
   supports_signing          false
   type                      aes256-gcm96
   

2. Create the "transit-order" rate limit quota.

   $ vault write sys/quotas/rate-limit/transit-order \
      path="transit/encrypt/orders" \
      rate=500
   

   Output:

   Success! Data written to: sys/quotas/rate-limit/transit-order
   

3. Verify the rate limit quota configuration.

   $ vault read sys/quotas/rate-limit/transit-order
   

   Output:

   Key               Value
   ---               -----
   block_interval    0
   group_by          ip
   inheritable       true
   interval          1
   name              transit-order
   path              transit/encrypt/orders
   rate              500
   role              n/a
   type              rate-limit
   

Vault Enterprise namespaces

For Vault Enterprise clusters, you can use the inheritable parameter to apply the resource quota set on a namespace to its subsequent child namespaces.

Think of the following namespace hierarchy:

root
   └── parent
      └── child
         └── grand-child

Under the root namespace, you have a parent namespace, and then parent/child and parent/child/grand-child namespaces.

You can set the resource quota on the parent namespace which gets applied to its child namespaces inheritably by setting the inheritable parameter to true. By default, it is set to false.

1. Create a quota rule on the us-west namespace which its child namespaces will inherit. The rate limit is 500 requests per minute.

   $ vault write sys/quotas/rate-limit/us-west \
      path="us-west" \
      rate=500 \
      interval=1m \
      inheritable=true
   

   Output:

   Success! Data written to: sys/quotas/rate-limit/us-west
   

2. Verify the quota rule.

   $ vault read sys/quotas/rate-limit/us-west
   
   Key               Value
   ---               -----
   block_interval    0
   group_by          ip
   inheritable       true
   interval          60
   name              us-west
   path              us-west/
   rate              500
   role              n/a
   type              rate-limit
   

Create a payload file with your quota settings, and then invoke the sys/quotas/rate-limit/{quota-name} endpoint.

{
  "name": "<QUOTA_RULE_NAME>",
  "path": "<TARGET_PATH>",
  "rate": <ALLOWED_REQUEST_RATE>,
  "role": "<ROLE_NAME>",
  "interval": <DURATION_OF_RATE_LIMIT>,
  "block_interval": <DURATION_TO_BLOCK_REQUESTS>,
  "inheritable": <BOOLEAN>
}

Example: Create a rate limit quota named, "global-rate" which limits inbound workload to 100 requests per second.

1. Invoke the sys/quotas/rate-limit endpoint.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST \
       --data '{ "rate": 100 }' \
       $VAULT_ADDR/v1/sys/quotas/rate-limit/global-rate
   

2. Read the newly created global-rate quota rule.

   $ curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
       $VAULT_ADDR/v1/sys/quotas/rate-limit/global-rate | jq -r ".data"
   

   Output:

   {
      "block_interval": 0,
      "group_by": "ip",
      "inheritable": true,
      "interval": 1,
      "name": "global-rate",
      "path": "",
      "rate": 100,
      "role": "",
      "type": "rate-limit"
   }
   

   Note

   In absence of path, this quota rule applies to the root namespace instead of a specific mount or namespace.

Example: Create a rate limit quota named, "transit-limit" which limits the access to the Transit secrets engine to be 1000 requests per minute (60 seconds).

1. Enable Transit secrets engine at transit.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST \
       --data '{"type":"transit"}' \
       $VAULT_ADDR/v1/sys/mounts/transit
   

2. Create a "transit-limit" rate limit quota.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      --request POST \
      --data '{"path": "transit", "rate": 1000, "interval": 60 }' \
      $VAULT_ADDR/v1/sys/quotas/rate-limit/transit-limit
   

3. Read the transit-limit rule to verify its configuration.

   $ curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
      $VAULT_ADDR/v1/sys/quotas/rate-limit/transit-limit | jq -r ".data"
   

   Output:

   {
      "block_interval": 0,
      "group_by": "ip",
      "inheritable": true,
      "interval": 60,
      "name": "transit-limit",
      "path": "transit/",
      "rate": 1000,
      "role": "",
      "type": "rate-limit"
   }
   

Path granularity

You can set the path to be deeper than the mount point (in this example, transit/).

Example: Create a rate limit quota named, "transit-order" to limit the data encryption requests using orders key to be 500 per second.

1. Create an encryption key named, "orders".

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST \
       $VAULT_ADDR/v1/transit/keys/orders
   

2. Create the "transit-order" rate limit quota.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      --request POST \
      --data '{ "path": "transit/encrypt/orders", "rate": 500 }' \
      $VAULT_ADDR/v1/sys/quotas/rate-limit/transit-order
   

3. Verify the rate limit quota configuration.

   $ curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
      $VAULT_ADDR/v1/sys/quotas/rate-limit/transit-order | jq -r ".data"
   

   Output:

   {
      "block_interval": 0,
      "group_by": "ip",
      "inheritable": true,
      "interval": 1,
      "name": "transit-order",
      "path": "transit/encrypt/orders",
      "rate": 500,
      "role": "",
      "type": "rate-limit"
   }
   

Vault Enterprise namespaces

For Vault Enterprise clusters, you can use the inheritable parameter to apply the resource quota set on a namespace to its subsequent child namespaces.

Think of the following namespace hierarchy:

root
   └── parent
      └── child
         └── grand-child

Under the root namespace, you have a parent namespace, and then parent/child and parent/child/grand-child namespaces.

You can set the resource quota on the parent namespace which gets applied to its child namespaces inheritably by setting the inheritable parameter to true. By default, it is set to false.

1. Create a quota rule on the us-west namespace which its child namespace inherits. The rate limit is 500 requests per minute.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      --request POST \
      --data '{"path": "us-west", "rate": 500, "interval": 60, "inheritable": true }' \
      $VAULT_ADDR/v1/sys/quotas/rate-limit/us-west
   

2. Verify the quota rule.

   $ curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
      $VAULT_ADDR/v1/sys/quotas/rate-limit/us-west | jq -r ".data"
   

   Output:

   {
      "block_interval": 0,
      "group_by": "ip",
      "inheritable": true,
      "interval": 60,
      "name": "us-west",
      "path": "us-west/",
      "rate": 500,
      "role": "",
      "type": "rate-limit"
   }
   

You can use HashiCorp Terraform to set the rate limit quotas.

Example:

1. Create a file named, main.tf with the following content.

   # Use Vault provider
   provider vault {}
   
   # Create "global-rate" which limits inbound workload to 100 requests per second
   resource "vault_quota_rate_limit" "global" {
      name = "global-rate"
      path = ""
      rate = 100
   }
   
   # Create "transit-limit" which limits the access to the Transit secrets engine to be 1000 requests per minute (60 seconds)
   resource "vault_quota_rate_limit" "transit-limit" {
      name = "transit-limit"
      path = "transit/"
      rate = 1000
      interval = 60
   
      depends_on = [ vault_mount.transit ]
   }
   
   # Path granularity: Create a rate limit quota, "transit-order" to limit the data encryption requests using orders key to be 500 per second
   resource "vault_quota_rate_limit" "transit-order" {
      name = "transit-order"
      path = "transit/encrypt/orders"
      rate = 500
   
   depends_on = [ vault_mount.transit, vault_transit_secret_backend_key.key ]
   }
   
   # Enable transit secrets engine & create a test key
   resource "vault_mount" "transit" {
      path                      = "transit"
      type                      = "transit"
      description               = "Test resource quota"
   }
   
   resource "vault_transit_secret_backend_key" "key" {
      backend = vault_mount.transit.path
      name    = "orders"
   }
   

   The main.tf performs the following operations:

   • Create a rate limit quota named, "global-rate" which limits inbound workload to 100 requests per second (line 5 - 9)

   • Create a rate limit quota named, "transit-limit" which limits the access to the Transit secrets engine to be 1000 requests per minute (line 12 - 19)

   • Create a rate limit quota named, "transit-order" to limit the data encryption requests using orders key to be 500 per second (line 22 - 28)

   • Enable transit secrets engine for testing (line 31 - 35)

   • Create an encryption key named, orders for testing (line 37 - 40)

2. Initialize Terraform.

   $ terraform init
   
   Initializing the backend...
   
   Initializing provider plugins...
   ...snip...
   
   Terraform has been successfully initialized!
   

3. After you run terraform init, you can verify that it will create the resources with terraform plan.

   $ terraform plan
   
   An execution plan has been generated and is shown below.
   Resource actions are indicated with the following symbols:
   ...snip...
   
   Plan: 5 to add, 0 to change, 0 to destroy.
   

   You should note resources listed in the output.

4. Deploy the resources with terraform apply.

   $ terraform apply -auto-approve
   
   Terraform used the selected providers to generate the following execution plan.
   ...snip...
   Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
   

To learn more about Terraform, visit the Terraform tutorials site.

Vault Enterprise namespaces

For Vault Enterprise clusters, you can use the inheritable parameter to apply the resource quota set on a namespace to its subsequent child namespaces.

Think of the following namespace hierarchy:

root
   └── parent
      └── child
         └── grand-child

Under the root namespace, you have a parent namespace, and then parent/child and parent/child/grand-child namespaces.

You can set the resource quota on the parent namespace which gets applied to its child namespaces inheritably by setting the inheritable parameter to true. By default, it is set to false.

You can use Terraform to create a quota rule on the us-west namespace which its child namespaces will inherit. The following Terraform configuration sets the rate limit to 500 requests per minute.

provider vault {}

# Create a "us-west" namespace
resource "vault_namespace" "us-west" {
   path = "us-west"
}

# Create a "us-west" rate limit quota 
resource "vault_quota_rate_limit" "us-west" {
  name = "us-west"
  path = "us-west"
  rate = 500
  interval = 60
  inheritable = true
}