DocsEmissary-ingressCustom error responses
Custom error responses
Custom error responses set overrides for HTTP response statuses generated either by Emissary-ingress or upstream services.
They can be configured either on the Emissary-ingress
or on an
Mapping, the schema is identical. See
below for more information on rule precedence.
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 Emissary-ingress pod.
filename: A file path on the Emissary-ingress 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.
Note that the AccessLog substitutions use
% as a delimiter (for example,
%RESPONSE_CODE%). To include a literal
% in a custom response body, use
would render as
for a request that resulted in a response code of 401.
Simple response bodies
Simple responses can be be added quickly for convenience. They are inserted into the manifest as either text or JSON:
File response bodies
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 Emissary-ingress pod.
content_type should be used set the specific file type, such as
First configure the Emissary-ingress module:
Then create the config map containing the HTML file:
Finally, mount the configmap to the Emissary-ingress pod:
NOTE: The following YAML is in patch format and does not represent the entire deployment spec.
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
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
Disabling response overrides
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:
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.