error-page
The error-page plugin allows customizing the error page served when gateways throw 404, 500, 502, and 503 exceptions. Note that it does not allow customizing the error page if the exceptions are thrown by upstream services.
Example
Customize Error Page
The example demonstrates how you can customize the error page by configuring the customized content on plugin metadata and serve the error page when a 404 error is encountered.
- 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>API7 Enterprise</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>API7 Enterprise</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>API7 Enterprise</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>API7 Enterprise</center>
</body>
</html>