Return custom 404 error in HTMLv1.3+
Configure the plugin to transform 404 responses into custom HTML and add a custom error message.
This example uses the handle_unknown parameter, which only takes effect on a globally configured instance of the plugin when a 404 error occurs.
If you’re running this plugin on-prem, you must configure it in the default Workspace.
For a full walkthrough, see Transform a 404 response message. Use the following example in place of the one in the guide.
Prerequisites
-
untrusted_luamust be set to eitheronorsandboxin yourkong.conffile for this plugin to work.
Add this section to your kong.yaml configuration file:
_format_version: "3.0"
plugins:
- name: exit-transformer
config:
handle_unknown: true
functions:
- |-
return function(status, body, headers)
if status == 404 then
body = [[
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>404 Not Found</title>
</head>
<body>
<h1>404</h1>
<p>Sorry, nothing to see here!</p>
</body>
</html>
]]
end
return status, body, headers
endMake the following request:
curl -i -X POST http://localhost:8001/plugins/ \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
"name": "exit-transformer",
"config": {
"handle_unknown": true,
"functions": [
"return function(status, body, headers)\n if status == 404 then\n body = [[\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<title>404 Not Found</title>\n</head>\n<body>\n<h1>404</h1>\n<p>Sorry, nothing to see here!</p>\n</body>\n</html>\n]]\nend\n return status, body, headers\nend"
]
}
}
'Make the following request:
curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $KONNECT_TOKEN" \
--data '
{
"name": "exit-transformer",
"config": {
"handle_unknown": true,
"functions": [
"return function(status, body, headers)\n if status == 404 then\n body = [[\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<title>404 Not Found</title>\n</head>\n<body>\n<h1>404</h1>\n<p>Sorry, nothing to see here!</p>\n</body>\n</html>\n]]\nend\n return status, body, headers\nend"
]
}
}
'Make sure to replace the following placeholders with your own values:
-
region: Geographic region where your Kong Konnect is hosted and operates. -
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account. -
controlPlaneId: Theidof the control plane.
See the Konnect API reference to learn about region-specific URLs and personal access tokens.
echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: exit-transformer
namespace: kong
annotations:
kubernetes.io/ingress.class: kong
labels:
global: 'true'
config:
handle_unknown: true
functions:
- |-
return function(status, body, headers)
if status == 404 then
body = [[
<!DOCTYPE html>
<html lang='en'>
<head>
<meta charset='utf-8'>
<title>404 Not Found</title>
</head>
<body>
<h1>404</h1>
<p>Sorry, nothing to see here!</p>
</body>
</html>
]]
end
return status, body, headers
end
plugin: exit-transformer
" | kubectl apply -f -Prerequisite: Configure your Personal Access Token
terraform {
required_providers {
konnect = {
source = "kong/konnect"
}
}
}
provider "konnect" {
personal_access_token = "$KONNECT_TOKEN"
server_url = "https://us.api.konghq.com/"
}Add the following to your Terraform configuration to create a Konnect Gateway Plugin:
resource "konnect_gateway_plugin_exit_transformer" "my_exit_transformer" {
enabled = true
config = {
handle_unknown = true
functions = [<<EOF
return function(status, body, headers)
if status == 404 then
body = [[
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>404 Not Found</title>
</head>
<body>
<h1>404</h1>
<p>Sorry, nothing to see here!</p>
</body>
</html>
]]
end
return status, body, headers
end
EOF]
}
control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}