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 Module 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-Type will default to text/plain if unspecified.
  • 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, filename must 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, json_format, or 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 %%. For example,

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 text/html.

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.

Known limitations

• text_formatand text_format_source perform 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.
• The json_format field does not support sourcing from a file. Instead consider using text_format_source with a JSON file and content_type set to application/json.

Rule precedence

If rules are set on both the Module and on a Mapping, the rule set on the Mapping will take precedence, ignoring any Module rules. This is true even if the rules are for different status codes. For example, consider this configuration:

The 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 the 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 Module.

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.