Using on

Introduction to the Mapping Resource

Mon, 01 Jan 0001 00:00:00 +0000

Emissary is designed around a declarative, self-service management model. The core resource used to support application development teams who need to manage the edge with Emissary is the Mapping resource.

Remember that Listener and Host resources are required for a functioning Emissary installation that can route traffic!
Learn more about Listener.
Learn more about Host.

Quick example

At its core a Mapping resource maps a resource to a service:

Required attribute	Description
`name`	is a string identifying the `Mapping` (e.g. in diagnostics)
`prefix`	is the URL prefix identifying your resource
`service`	is the name of the service handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than Emissary

These resources are defined as Kubernetes Custom Resource Definitions. Here’s a simple example that maps all requests to /httpbin/ to the httpbin.org web service:

Advanced Mapping configuration

Mon, 01 Jan 0001 00:00:00 +0000

Emissary is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the Mapping resource is used. For TCP, the TCPMapping resource is used.

Emissary must have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique.

Ambassador module defaults

Mon, 01 Jan 0001 00:00:00 +0000

If present, the ambassador Module can define a set of defaults that will automatically be applied to certain resources:

apiVersion: getambassador.io/v3alpha1
kind:  Module
metadata:
  name:  ambassador
spec:
  config:
    defaults:
      class1:           # This is a class. Different resource types will look in different classes.
        key1: value1    # Within a class, you can set different keys.
        key2: value2
        ...
      class2:
        ...
      top_key1: value1  # If a key isn't found in a resource's class, the system will look in the
      top_key2: value2  # toplevel defaults dictionary for it.

Mapping

Currently, only the Mapping resource uses the defaults mechanism. Mapping looks first for defaultable resources in the httpmapping class, including:

AuthService settings

Mon, 01 Jan 0001 00:00:00 +0000

A Mapping can pass these settings along to an AuthService. This is helpful to allow these specific configurations to apply only to certain Mappings and not globally.

Bypass authentication

An AuthService can be disabled for a specific Mapping with the bypass_auth attribute. This will tell Emissary to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API.

Automatic retries

Mon, 01 Jan 0001 00:00:00 +0000

Sometimes requests fail. When these requests fail for transient issues, Emissary can automatically retry the request.

Retry policy can be set for all Emissary mappings in the ambassador Module, or set per Mapping. Generally speaking, you should set retry_policy on a per mapping basis. Global retries can easily result in unexpected cascade failures.

Note that when setting retry_policy, adjusting max_retries in the circuit breaker configuration should also be considered in order to account for all desired retries.

Basic rate limiting

Mon, 01 Jan 0001 00:00:00 +0000

Rate limiting in Emissary is composed of two parts:

The RateLimitService resource tells Emissary what external service to use for rate limiting.

If Emissary cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration.
Labels that get attached to requests. A label is basic metadata that is used by the RateLimitService to decide which limits to apply to the request.

Canary releases

Mon, 01 Jan 0001 00:00:00 +0000

Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early (“canary”) release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release.

Circuit breakers

Mon, 01 Jan 0001 00:00:00 +0000

Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the “blast radius” of an overloaded service. By design, Emissary circuit breakers are distributed, i.e., different Emissary instances do not coordinate circuit breaker information.

Circuit breaker configuration

A default circuit breaking configuration can be set for all Emissary resources in the ambassador Module, or set to a different value on a per-resource basis for Mappings, TCPMappings, and AuthServices.

Cross-Origin Resource Sharing (CORS)

Mon, 01 Jan 0001 00:00:00 +0000

Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain.

CORS configuration can be set for all Emissary mappings in the ambassador Module, or set per Mapping.

When the CORS attribute is set at either the Mapping or Module level, Emissary will intercept the pre-flight OPTIONS request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS OPTIONS requests.

Gateway API

Mon, 01 Jan 0001 00:00:00 +0000

Emissary now supports a limited subset of the new v1alpha1 Gateway API. Note that the Gateway API is not supported when AMBASSADOR_LEGACY_MODE is set.

Support is currently limited to the following fields, however this will expand in future releases:

Gateway.spec.listeners.port
HTTPRoute.spec.rules.matches.path.type (Exact, Prefix, and RegularExpression)
HTTPRoute.spec.rules.matches.path.value
HTTPRoute.spec.rules.matches.header.type (Exact and RegularExpression)
HTTPRoute.spec.rules.matches.header.values
HTTPRoute.spec.rules.forwardTo.serviceName
HTTPRoute.spec.rules.forwardTo.port
HTTPRoute.spec.rules.forwardTo.weight

Please see the specification for more details.

Keepalive

Mon, 01 Jan 0001 00:00:00 +0000

Keepalive option indicates whether SO_KEEPALIVE on the socket should be enabled.

Keepalive configuration

Keepalive configuration can be set for all Emissary mappings in the ambassador Module or set per Mapping.

The keepalive attribute configures keepalive. The following fields are supported:

keepalive:
  idle_time: <integer>
  interval: <integer>
  probes: <integer>

`idle_time`

(Default: 7200) The number of seconds a connection needs to be idle before keep-alive probes start being sent.

`interval`

(Default: 75) The number of seconds between keep-alive probes.

Method-based routing

Mon, 01 Jan 0001 00:00:00 +0000

Emissary supports routing based on the HTTP method and regular expression.

Using `method`

The method annotation specifies the specific HTTP method for a mapping. The value of the method annotation must be in all upper case.

For example:

---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: get
spec:
  hostname: "*"
  prefix: /backend/get_only/
  method: GET
  service: quote

Using `method_regex`

When method_regex is set to true, the value of the method annotation will be interpreted as a regular expression.

Prefix regex

Mon, 01 Jan 0001 00:00:00 +0000

Using `prefix` and `prefix_regex`

When the prefix_regex attribute is set to true, Emissary configures a regex route instead of a prefix route in Envoy. This means the entire path must match the regex specified, not only the prefix.

Example with a version in the URL

If the version is a path parameter and the resources are served by different services, then

---
apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  qotm
spec:
  prefix: "/(v1|v2)/qotm/.*"
  prefix_regex: true
  service: qotm

will map requests to both /v1 and /v2 to the qotm service.

Query parameter-based routing

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can route to target services based on HTTP query parameters with the query_parameters and regex_query_parameters specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules.

The `query_parameters` annotation

The query_parameters attribute is a dictionary of query_parameter: value pairs. Emissary will only allow requests that match the specified query_parameter: value pairs to reach the target service.

You can also set the value of a query parameter to true to test for the existence of a query parameter.

Redirects

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can perform 3xx redirects on Mappings to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301.

Schema

Name	Type	Description
`spec.host_redirect`	Boolean	This is required to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected.
`spec.path_redirect`	String	Optional, changes the path for the redirect.
`spec.prefix_redirect`	String	Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value.
`spec.regex_redirect`	String	Optional, uses regex to match and replace the `prefix` value.
`spec.redirect_response_code`	Integer	Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308.
`spec.config. x_forwarded_proto_redirect`	Boolean	Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through.
`spec.config. use_remote_address`	Boolean	Required to be set to `false` to use the `x_forwarded_proto_redirect` feature.

Examples

Basic redirect

To effect any type of HTTP Redirect, the Mapping must set host_redirect to true, with service set to the host to which the client should be redirected:

Rewrites

Mon, 01 Jan 0001 00:00:00 +0000

Once Emissary uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service.

There are two approaches for rewriting: rewrite for simpler scenarios and regex_rewrite for more advanced rewriting.

Please note that only one of these two can be configured for a mapping at the same time. As a result Emissary ignores rewrite when regex_rewrite is provided.

TCPMapping resources

Mon, 01 Jan 0001 00:00:00 +0000

In addition to managing HTTP, gRPC, and WebSockets at layer 7, Emissary can also manage TCP connections at layer 4. The core abstraction used to support TCP connections is the TCPMapping.

An Emissary TCPMapping associates TCP connections with upstream services. Cleartext TCP connections are defined by destination IP address and/or destination TCP port; TLS-encrypted TCP connections can also be defined by the hostname presented using SNI. A service is exactly the same as in HTTP Mappings and other Emissary resources.

Timeouts

Mon, 01 Jan 0001 00:00:00 +0000

Emissary enables you to control timeouts in several different ways.

Request timeout: `timeout_ms`

timeout_ms is the end-to-end timeout for an entire user-level transaction in milliseconds. It begins after the full incoming request is received up until the full response stream is returned to the client. This timeout includes all retries. It can be disabled by setting the value to 0.

Default: 3000

Idle timeout: `idle_timeout_ms`

idle_timeout_ms controls how long a connection should remain open when no traffic is being sent through the connection. idle_timeout_ms is distinct from timeout_ms, as the idle timeout applies on either down or upstream request events and is reset every time an encode/decode event occurrs or data is processed for the stream. idle_timeout_ms operates on a per-route basis and will overwrite behavior of the cluster_idle_timeout_ms. If not set, Emissary will default to the value set by cluster_idle_timeout_ms. It can be disabled by setting the value to 0.

Traffic shadowing

Mon, 01 Jan 0001 00:00:00 +0000

Traffic shadowing is a deployment pattern where production traffic is asynchronously copied to a non-production service for testing. Shadowing is a close cousin to two other commonly known deployment patterns, canary releases and blue/green deployments. Shadowing traffic has several important benefits over blue/green and canary testing:

Zero production impact. Since traffic is duplicated, any bugs in services that are processing shadow data have no impact on production.
Test persistent services. Since there is no production impact, shadowing provides a powerful technique to test persistent services. You can configure your test service to store data in a test database, and shadow traffic to your test service for testing. Both blue/green deployments and canary deployments require more machinery for testing.

Using on

Introduction to the Mapping Resource

Quick example

Advanced Mapping configuration

Ambassador module defaults

Mapping

AuthService settings

Bypass authentication

Automatic retries

Basic rate limiting

Canary releases

Circuit breakers

Circuit breaker configuration

Cross-Origin Resource Sharing (CORS)

Gateway API

Keepalive

Keepalive configuration

idle_time

interval

Method-based routing

Using method

Using method_regex

Prefix regex

Using prefix and prefix_regex

Example with a version in the URL

Query parameter-based routing

The query_parameters annotation

Redirects

Schema

Examples

Basic redirect

Rewrites

TCPMapping resources

Timeouts

Request timeout: timeout_ms

Idle timeout: idle_timeout_ms

Traffic shadowing

`idle_time`

`interval`

Using `method`

Using `method_regex`

Using `prefix` and `prefix_regex`

The `query_parameters` annotation

Request timeout: `timeout_ms`

Idle timeout: `idle_timeout_ms`