Redis with OpenResty
Use Redis from NGINX through OpenResty for rate limiting and caching.
Open source NGINX has no built-in Redis module. The modules index lists none. You can use Redis from NGINX with OpenResty, a web platform that bundles NGINX, LuaJIT, and the lua-resty-redis client, which talks to Redis without blocking NGINX's event loop. See the rate limiter and cache-aside use cases for when to choose these patterns.
Requirements
The examples on this page were run with OpenResty 1.31 (the openresty/openresty:alpine image),
which includes lua-resty-redis 0.34, against Redis 8.0.
You also need a running Redis server. You can run one locally with Redis Open Source, use Docker, or connect to Redis Cloud.
Limit requests with Redis
Use access_by_lua_block to count requests in Redis before NGINX proxies them. This example
allows 3 requests a minute for each client address. A Lua script runs INCR and EXPIRE in one
atomic step, so a crash between the two commands can't leave a counter without an expiry:
location /api {
access_by_lua_block {
local redis = require "resty.redis"
local red = redis:new()
red:set_timeouts(1000, 1000, 1000) -- connect, send, read (ms)
local ok, err = red:connect("<your-redis-host>", 6379)
if not ok then
ngx.log(ngx.ERR, "redis unavailable: ", err)
return -- fail open: let the request through
end
local script = [[
local n = redis.call('INCR', KEYS[1])
if n == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
return n
]]
local n = red:eval(script, 1, "ratelimit:" .. ngx.var.remote_addr, 60)
red:set_keepalive(10000, 100)
if n and n > 3 then
return ngx.exit(429)
end
}
proxy_pass http://<your-upstream>;
}
In a test, five requests returned 200, 200, 200, 429, and 429. The counter was a string,
ratelimit:<client-ip>, with a TTL of 60 seconds, and it held 5 because the script also counts
rejected requests.
Cache responses with Redis
This route implements cache-aside in NGINX. It reads the response from Redis if it's there, and otherwise fetches it from an upstream, stores it with a 30-second expiry, and returns it:
location = /upstream { internal; proxy_pass http://<your-upstream>/; }
location = /cached {
content_by_lua_block {
local redis = require "resty.redis"
local red = redis:new()
red:set_timeouts(1000, 1000, 1000)
assert(red:connect("<your-redis-host>", 6379))
local key = "cache:" .. ngx.var.uri
local body = red:get(key)
if body and body ~= ngx.null then
ngx.header["X-Cache"] = "HIT"
ngx.say(body)
else
local res = ngx.location.capture("/upstream")
red:set(key, res.body, "EX", 30)
ngx.header["X-Cache"] = "MISS"
ngx.say(res.body)
end
red:set_keepalive(10000, 100)
}
}
In a test, the first request returned X-Cache: MISS and the next two returned X-Cache: HIT, and
the key cache:/cached had a TTL of 30 seconds.
When Redis is unavailable
The rate limiter above fails open: with the Redis server stopped, a request returned 200
after about 1 second, which is the connect timeout. The cache route uses assert, so it fails the
request if Redis is down. Handle the error in your own code if you want a different behavior.