Docs
Plugin HubCategoriesTraffic ManagementProxy CacheConfiguration

Proxy Cache Configuration

Configuration reference for the Proxy Cache plugin (`proxy-cache`): the static configurations and parameters, each attribute with its type, whether it is required, its default and its accepted values.

Static Configurations

The gateway default configuration includes proxy cache settings for disk caching and cache zones. The file to update depends on how the gateway is deployed:

For host or Docker deployments, configure the following settings:

config.yaml
apisix:
  proxy_cache:
    cache_ttl: 10s  # default cache TTL used when caching on disk, only if none of the `Expires`
                    # and `Cache-Control` response headers is present, or if APISIX returns
                    # `502 Bad Gateway` or `504 Gateway Timeout` due to unavailable upstreams
    zones:
      - name: disk_cache_one
        memory_size: 50m
        disk_size: 1G
        disk_path: /tmp/disk_cache_one
        cache_levels: 1:2
      # - name: disk_cache_two
      #   memory_size: 50m
      #   disk_size: 1G
      #   disk_path: "/tmp/disk_cache_two"
      #   cache_levels: "1:2"
      - name: memory_cache
        memory_size: 50m

Then reload APISIX (opens in Apache APISIX docs) for changes to take effect.

Parameters

See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.

cache_strategy — string · optional · default: disk · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

Valid values: disk or memory

Caching strategy. Cache on disk or in memory.

cache_zone — string · optional · default: disk_cache_one · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

Cache zone used with the caching strategy. The value should match one of the cache zones defined in the configuration files and should correspond to the caching strategy. For example, when using the in-memory caching strategy, you should use an in-memory cache zone.

cache_key — array[string] · optional · default: ["$host", "$request_uri"] · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

Key to use for caching.

Support built-in variables (opens in Apache APISIX docs) and constant strings in values. Variables should be prefixed with a $ sign.

cache_bypass — array[string] · optional · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

One or more parameters to parse value from, such that if any of the values is not empty and is not equal to 0, response will not be retrieved from cache.

Support built-in variables (opens in Apache APISIX docs) and constant strings in values. Variables should be prefixed with a $ sign.

cache_method — array[string] · optional · default: ["GET", "HEAD"] · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

Valid values: Any combination of methods from "GET", "POST", and "HEAD"

Request methods of which the response should be cached.

cache_http_status — array[integer] · optional · default: [200, 301, 404] · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

Valid values: Any combination of integer values from 200 to 599 inclusive

Response HTTP status codes of which the response should be cached.

hide_cache_headers — boolean · optional · default: false · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

If true, hide Expires and Cache-Control response headers.

cache_control — boolean · optional · default: false · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

If true, the in-memory strategy honors supported request Cache-Control directives and derives the cache TTL from the upstream response's s-maxage, max-age, or Expires value. Regardless of this setting, responses containing Cache-Control: private, no-store, or no-cache are not cached in memory.

no_cache — array[string] · optional · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

One or more parameters to parse value from, such that if any of the values is not empty and is not equal to 0, response will not be cached.

Support built-in variables (opens in Apache APISIX docs) and constant strings in values. Variables should be prefixed with a $ sign.

cache_ttl — integer · optional · default: 300 · since APISIX 2.11.0 · API7 Gateway 3.2.16.3

Valid values: greater than or equal to 1

Cache time to live (TTL) in seconds when caching in memory.

To adjust the TTL when caching on disk, update cache_ttl in the configuration files. The TTL value is evaluated in conjunction with the values in the response headers Cache-Control and Expires received from the upstream service.

consumer_isolation — boolean · optional · default: true · since APISIX 3.17.0 · API7 Gateway 3.9.13

If true, prepend the authenticated consumer identity to the effective cache key when the request resolves to a consumer or remote user. This is skipped when cache_key already contains an identity-bearing variable such as $consumer_name, $consumer_group_id, $remote_user, or $http_authorization. Available in API7 Enterprise from version 3.9.13 and APISIX from version 3.17.0.

max_resp_body_size — integer · optional · default: 67108864 · since APISIX 3.18.0 · API7 Gateway 3.9.17

Valid values: greater than or equal to 1

Maximum response body size in bytes buffered by the memory cache strategy. A response that reaches or exceeds this size is streamed to the client without being cached. The chunk that crosses the threshold is buffered before the limit is enforced, so transient memory use can exceed the configured size. This field does not apply to disk caching. Introduced in API7 Enterprise 3.9.17 and 3.10.4, and APISIX 3.18.0.

Proxy Cache

Previous Page

Changelog

Next Page