Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(plugin): refactor proxy-cache.md #7858

Merged
merged 2 commits into from
Sep 6, 2022
Merged

docs(plugin): refactor proxy-cache.md #7858

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ae1e486
docs: update proxy-cache.md
lunarwhite Sep 4, 2022
2793584
update ref reviews
lunarwhite Sep 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 21 additions & 38 deletions docs/en/latest/plugins/proxy-cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,9 @@
title: proxy-cache
keywords:
- APISIX
- Plugin
- API Gateway
- Proxy Cache
- proxy-cache
description: This document contains information about the Apache APISIX proxy-cache Plugin.
description: This document contains information about the Apache APISIX proxy-cache Plugin, you can use it to cache the response from the Upstream.
---
<!--
#
Expand All @@ -28,7 +27,7 @@ description: This document contains information about the Apache APISIX proxy-ca

## Description

The `proxy-cache` Plugin can be used to cache the response from the Upstream. It can be used with other Plugins and currently supports disk-based caching.
The `proxy-cache` Plugin can be used to cache the response from the Upstream. It can be used with other Plugins and currently supports disk-based and memory-based caching.

The data to be cached can be filtered with response codes, request modes, or more complex methods using the `no_cache` and `cache_bypass` attributes.

Expand All @@ -37,25 +36,22 @@ The data to be cached can be filtered with response codes, request modes, or mor
| Name | Type | Required | Default | Valid values | Description |
|--------------------|----------------|----------|---------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| cache_strategy | string | False | disk | ["disk","memory"] | Specifies where the cached data should be stored. |
| cache_zone | string | False | disk_cache_one | | Specifies which cache area to use. Each cache area can be configured with different paths. Cache areas can be predefined in your configuration file (conf/config.yaml). If the specified cache area is inconsistent with the pre-defined cache area in your configuration file, the cache is invalid. |
| cache_zone | string | False | disk_cache_one | | Specifies which cache area to use. Each cache area can be configured with different paths. Cache areas can be predefined in your configuration file (`conf/config.yaml`). If the specified cache area is inconsistent with the pre-defined cache area in your configuration file, the cache is invalid. |
| cache_key | array[string] | False | ["$host", "$request_uri"] | | Key to use for caching. For example, `["$host", "$uri", "-cache-id"]`. |
| cache_bypass | array[string] | False | | | Conditions in which response from cache is bypassed. Whether to skip cache retrieval. If at least one value of the string parameters is not empty and is not equal to “0” then the response will not be taken from the cache. For example, `["$arg_bypass"]`. |
| cache_bypass | array[string] | False | | | Conditions in which response from cache is bypassed. Whether to skip cache retrieval. If at least one value of the string parameters is not empty and is not equal to `0` then the response will not be taken from the cache. For example, `["$arg_bypass"]`. |
| cache_method | array[string] | False | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | Request methods for which the response will be cached. |
| cache_http_status | array[integer] | False | [200, 301, 404] | [200, 599] | HTTP status codes of the Upstream response for which the response will be cached. |
| hide_cache_headers | boolean | False | false | | When set to true adds the `Expires` and `Cache-Control` headers to the client response. |
| cache_control | boolean | False | false | | When set to true, complies with Cache-Control behavior in the HTTP specification. Used only for memory strategy. |
| no_cache | array[string] | False | | | Conditions in which the response will not be cached. If at least one value of the string parameters is not empty and is not equal to “0” then the response will not be saved. |
| hide_cache_headers | boolean | False | false | | When set to `true` adds the `Expires` and `Cache-Control` headers to the client response. |
| cache_control | boolean | False | false | | When set to `true`, complies with Cache-Control behavior in the HTTP specification. Used only for memory strategy. |
| no_cache | array[string] | False | | | Conditions in which the response will not be cached. If at least one value of the string parameters is not empty and is not equal to `0` then the response will not be saved. |
| cache_ttl | integer | False | 300 seconds | | Time that a response is cached until it is deleted or refreshed. Comes in to effect when the `cache_control` attribute is not enabled or the proxied server does not return cache header. Used only for memory strategy. |

:::note

The cache expiration time cannot be configured dynamically. It can only be set by the Upstream response header `Expires` or `Cache-Control`. The default expiration time is 10s if there is no `Expires` or `Cache-Control` in the Upstream response header.

If the Upstream service is not available and APISIX returns a 502 or 504 status code, it will be cached for 10s.

Variables (start with `$`) can be specified in `cache_key`, `cache_bypass` and `no_cache`. It's worth mentioning that the variable value will be an empty string if it doesn't exist.

You can also combine a number of variables and strings (constants), by writing them into an array, eventually, variables will be parsed and stitched together with strings.
- The cache expiration time cannot be configured dynamically. It can only be set by the Upstream response header `Expires` or `Cache-Control`. The default expiration time is 10s if there is no `Expires` or `Cache-Control` in the Upstream response header.
- If the Upstream service is not available and APISIX returns a `502` or `504` status code, it will be cached for 10s.
- Variables (start with `$`) can be specified in `cache_key`, `cache_bypass` and `no_cache`. It's worth mentioning that the variable value will be an empty string if it doesn't exist.
- You can also combine a number of variables and strings (constants), by writing them into an array, eventually, variables will be parsed and stitched together with strings.

:::

Expand All @@ -77,7 +73,8 @@ proxy_cache:
You can enable the Plugin on a specific Route as shown below:

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
Expand Down Expand Up @@ -111,12 +108,7 @@ curl http://127.0.0.1:9080/hello -i

```shell
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 6
Connection: keep-alive
Server: APISIX web server
Date: Tue, 03 Mar 2020 10:45:36 GMT
Last-Modified: Tue, 03 Mar 2020 10:36:38 GMT
···
Apisix-Cache-Status: MISS

hello
Expand All @@ -130,37 +122,27 @@ curl http://127.0.0.1:9080/hello -i

```shell
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 6
Connection: keep-alive
Server: APISIX web server
Date: Tue, 03 Mar 2020 11:14:46 GMT
Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
···
Apisix-Cache-Status: HIT

hello
```

If you set `"cache_zone": "invalid_disk_cache"` attribute to an invalid value (cache not configured in the your configuration file), then it will return a 404 response.
If you set `"cache_zone": "invalid_disk_cache"` attribute to an invalid value (cache not configured in the your configuration file), then it will return a `404` response.

:::tip

To clear the cached data, you can send a request with PURGE method:
To clear the cached data, you can send a request with `PURGE` method:

```shell
curl -i http://127.0.0.1:9080/hello -X PURGE
```

```shell
HTTP/1.1 200 OK
Date: Tue, 03 Mar 2020 11:17:35 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX web server
```

If the response code is 200, the deletion is successful. If the cached data is not found, a 404 response code will be returned.
If the response code is `200`, the deletion is successful. If the cached data is not found, a `404` response code will be returned.

:::

Expand All @@ -169,7 +151,8 @@ If the response code is 200, the deletion is successful. If the cached data is n
To disable the `proxy-cache` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {},
Expand Down
Loading