Custom error responses set overrides for HTTP response statuses generated either by Ambassador or upstream services.
on_status_code: HTTP status code to match for this rewrite rule. Only 4xx and 5xx classes are supported.
body: Describes the response body contents and format.
content_type: A string that sets the content type of the response.
text_format: A string whose value will be used as the new response body.
Content-Typewill default to
json_format: A config object whose keys and values will be serialized as JSON and used as the new response body.
text_format_source: Describes a file to be used as the response. If used,
filenamemust be set and the file must exist on the Ambassador pod.
filename: A file path on the Ambassador pod that will be used as the new response body.
Only one of
text_format_source may be provided.
Custom response bodies are subject to Envoy's AccessLog substitution syntax and variables, see Envoy's documentation for more information.
Simple responses can be be added quickly for convenience. They are inserted into the manifest as either text or JSON:
apiVersion: getambassador.io/v2kind: Modulemetadata:name: ambassadornamespace: ambassadorspec:config:error_response_overrides:- on_status_code: 404body:text_format: "File not found"- on_status_code: 500body:json_format:error: "Application error"status: "%RESPONSE_CODE%"cluster: "%UPSTREAM_CLUSTER%"
For more complex response bodies a file can be returned as the response.
This could be used for a customer friendly HTML document for example. Use
text_format_source with a
filename set as a path on the Ambassador pod.
content_type should be used set the specific file type, such as
First configure the Ambassador module:
apiVersion: getambassador.io/v2kind: Modulemetadata:name: ambassadornamespace: ambassadorspec:config:error_response_overrides:- on_status_code: 404body:content_type: "text/html"text_format_source:filename: '/ambassador/ambassador-errorpages/404.html'
Then create the config map containing the HTML file:
---apiVersion: v1kind: ConfigMapmetadata:name: ambassador-errorpagesnamespace: ambassadordata:404.html: |<html><h1>File not found</h1><p>Uh oh, looks like you found a bad link.</p><p>Click <a href="index.html">here</a> to go back home.</p></html>
Finally, mount the configmap to the Ambassador pod:
NOTE: The following YAML is in patch format and does not represent the entire deployment spec.
spec:template:spec:containers:- name: aesvolumeMounts:- name: ambassador-errorpagesmountPath: /ambassador/ambassador-errorpagesvolumes:- name: ambassador-errorpagesconfigMap:name: ambassador-errorpages
text_format_sourceperform no string escaping on expanded variables. This may break the structural integrity of your response body if, for example, the variable contains HTML data and the response content type is
text/html. Be careful when using variables in this way, and consider whether the value may be coming from an untrusted source like request or response headers.
json_formatfield does not support sourcing from a file. Instead consider using
text_format_sourcewith a JSON file and
If rules are set on both the
Module and on a
Mapping, the rule set on
Mapping will take precedence, ignoring any
Module rules. This is true
even if the rules are for different status codes. For example, consider this
apiVersion: getambassador.io/v2kind: Modulemetadata:name: ambassadornamespace: ambassadorspec:config:error_response_overrides:- on_status_code: 404body:text_format: "Global 404"---apiVersion: getambassador.io/v2kind: Mappingmetadata:name: ambassadornamespace: ambassadorspec:config:prefix: /api/service: quoteerror_response_overrides:- on_status_code: 429body:text_format: "Per-mapping 429"
Mapping rule will prevent an override on the 404 rule defined on the
Module for this
Mapping. The rule on the
Mapping will cause all rules on
Module to be ignored, regardless of the status codes specified. A seperate
Mapping with no override rules defined will follow the 404 rule on the
If error response overrides are set on the
Module, they can be disabled on
individual mappings by setting
bypass_error_response_overrides: true on those mappings:
---apiVersion: getambassador.io/v2kind: Mappingmetadata:name: quote-backendnamespace: ambassadorspec:prefix: /api/service: quotebypass_error_response_overrides: true
This is useful if a portion of the domain serves an API whose errors should not be rewritten, but all other APIs should contain custom errors.