error-page
The error-page plugin customizes gateway-generated 404, 500, 502, and 503 responses. It does not modify responses returned by upstream services.
Enable the Plugin
API7 Gateway loads error-page by default. In APISIX, load the plugin in the gateway static configuration before configuring its metadata.
- Host or Docker
- Kubernetes (Helm)
Keep the existing plugin list in config.yaml and add error-page:
plugins:
# Keep the existing plugin list.
- error-page
Reload APISIX for the change to take effect.
The APISIX Helm chart value apisix.plugins replaces the loaded plugin list. Start from the complete list used by the gateway, add error-page, and keep the other plugins unchanged:
apisix:
plugins:
# Keep the complete plugin list used by the gateway.
- error-page
Apply the values file with the APISIX Helm chart.
Example
Customize Error Page
The example demonstrates how to customize a gateway-generated 404 response with plugin metadata.
- Admin API
- ADC
- Ingress Controller
Configure the plugin metadata for customized error page:
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"enable": true,
"error_404": {
"body": "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>Gateway</center>\n </body>\n</html>",
"content_type": "text/html"
}
}'
To demonstrate the function of the plugin, create a route with the serverless-post-function plugin, which returns a 404 error code from gateways for all requests to the route:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/*",
"id": "error-page-route",
"plugins": {
"serverless-post-function": {
"functions": [
"return function (conf, ctx)
local core = require(\"apisix.core\")
core.response.exit(404)
end"
]
},
"error-page": {}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}'
❶ Return a 404 status code for all requests to the route.
❷ Enable error-page to return the customized error page.
Configure the plugin metadata and create a route with the serverless-post-function and error-page plugins:
plugin_metadata:
error-page:
enable: true
error_404:
body: "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>Gateway</center>\n </body>\n</html>"
content_type: text/html
services:
- name: error-page-service
routes:
- name: error-page-route
uris:
- /*
plugins:
serverless-post-function:
functions:
- |
return function (conf, ctx)
local core = require("apisix.core")
core.response.exit(404)
end
error-page: {}
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
❶ Return a 404 status code for all requests to the route.
❷ Enable error-page to return the customized error page.
Synchronize the configuration to the gateway:
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
Create a route with the serverless-post-function and error-page plugins:
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: error-page-plugin-config
spec:
plugins:
- name: serverless-post-function
config:
functions:
- |
return function (conf, ctx)
local core = require("apisix.core")
core.response.exit(404)
end
- name: error-page
config: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: error-page-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: PathPrefix
value: /
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: error-page-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
❶ Return a 404 status code for all requests to the route.
❷ Enable error-page to return the customized error page.
Create a route with the serverless-post-function and error-page plugins:
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: error-page-route
spec:
ingressClassName: apisix
http:
- name: error-page-route
match:
paths:
- /*
upstreams:
- name: httpbin-external-domain
plugins:
- name: serverless-post-function
enable: true
config:
functions:
- |
return function (conf, ctx)
local core = require("apisix.core")
core.response.exit(404)
end
- name: error-page
enable: true
config: {}
❶ Return a 404 status code for all requests to the route.
❷ Enable error-page to return the customized error page.
Update your GatewayProxy manifest to configure the error-page plugin metadata:
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
namespace: aic
name: apisix-config
spec:
provider:
type: ControlPlane
controlPlane:
# ...
# your control plane connection configuration
pluginMetadata:
error-page:
enable: true
error_404:
body: "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>Gateway</center>\n </body>\n</html>"
content_type: text/html
Apply the configuration to your cluster:
kubectl apply -f gatewayproxy.yaml -f error-page-ic.yaml
Send a request to the route:
curl -i "http://127.0.0.1:9080/get"
You should see an HTTP/1.1 404 Not Found response with the following response body:
<html>
<head>
<title>404</title>
</head>
<body>
<center>
<h1>404 not found</h1>
</center>
<hr>
<center>Gateway</center>
</body>
</html>