- Advanced configuration topics
- Upgrading Ambassador
- Statistics and Monitoring
- Need Help?
Ambassador 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 can apply to HTTP, GRPC, and Websockets at layer 7 via a
Mapping resource, or to raw TCP connections at layer 4 via a
Ambassador must have one or more mappings defined to provide access to any services at all.
Each mapping can also specify, among other things:
- a rewrite rule which modifies the URL as it's handed to the Kubernetes service;
- a weight specifying how much of the traffic for the resource will be routed using the mapping;
- a host specifying a required value for the HTTP
- a shadow marker, specifying that this mapping will get a copy of traffic for the resource; and
- other headers which must appear in the HTTP request.
Ambassador supports a number of attributes to configure and customize mappings.
||specifies a dictionary of other HTTP headers that should be added to each request when talking to the service|
||specifies a dictionary of other HTTP headers that should be added to each response when returning response to client|
||enables Cross-Origin Resource Sharing (CORS) setting on a mapping|
||if true, enables IPv4 DNS lookups for this mapping's service (the default is set by the Ambassador module)|
||if true, enables IPv6 DNS lookups for this mapping's service (the default is set by the Ambassador module)|
||if true, tells the system that the service will be handling gRPC calls|
||specifies a list of other HTTP headers which must appear in the request for this mapping to be used to route the request|
||specifies the value which must appear in the request's HTTP
||if true, tells the system to interpret the
||forces the HTTP
||configures load balancer on a mapping|
||defines the HTTP method for this mapping (e.g. GET, PUT, etc. -- must be all uppercase)|
||if true, tells the system to interpret the
||if true, tells the system to interpret the
||specifies a list rate limit rules on a mapping|
||specifies a list of HTTP headers and regular expressions which must match for this mapping to be used to route the request|
||replaces the URL prefix with when talking to the service|
||the timeout, in milliseconds, for requests through this
||if true, tells the system that it should use HTTPS to contact this service. (It's also possible to use
||if true, tells Ambassador that this service will use websockets|
enable_ipv6 are set, Ambassador will prefer IPv6 to IPv4. See the Ambassador module documentation for more information.
Ambassador supports multiple deployment patterns for your services. These patterns are designed to let you safely release new versions of your service, while minimizing its impact on production users.
||if true, a copy of the resource's traffic will go the
||specifies the (integer) percentage of traffic for this resource that will be routed using this mapping|
These attributes are less commonly used, but can be used to override Ambassador's default behavior in specific cases.
||if true, forces the HTTP
||if true, this
||if set when
||an integer overriding Ambassador's internal ordering for
||if true, tells Ambassador that this service should bypass
The name of the mapping must be unique. If no
method is given, all methods will be proxied.
Mapping definitions are fairly straightforward. Here's an example for a REST service which Ambassador will contact using HTTP:
--- apiVersion: ambassador/v1 kind: Mapping name: qotm_mapping prefix: /qotm/ service: http://qotm
and a REST service which Ambassador will contact using HTTPS:
--- apiVersion: ambassador/v1 kind: Mapping name: quote_mapping prefix: /qotm/quote/ rewrite: /quotation/ service: https://qotm
(Note that the 'http://' prefix for an HTTP service is optional.)
Here's an example for a CQRS service (using HTTP):
--- apiVersion: ambassador/v1 kind: Mapping name: cqrs_get_mapping prefix: /cqrs/ method: GET service: getcqrs --- apiVersion: ambassador/v1 kind: Mapping name: cqrs_put_mapping prefix: /cqrs/ method: PUT service: putcqrs
Required attributes for mappings:
nameis a string identifying the
Mapping(e.g. in diagnostics)
prefixis the URL prefix identifying your resource
serviceis 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 Ambassador
Mapping Evaluation Order
Ambassador sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method and the constraint headers are all taken into account.
If absolutely necessary, you can manually set a
precedence on the mapping (see below). In general, you should not need to use this feature unless you're using the
host_regex matching features. If there's any question about how Ambassador is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated.
Optional Fallback Mapping
Ambassador will respond with a
404 Not Found to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service.
For example, defining a mapping with only a
/ prefix will catch all requests previously unhandled and forward them to an external service:
--- apiVersion: ambassador/v1 kind: Mapping name: catch-all prefix: / service: https://www.getambassador.io
Ambassador sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play.
For those situations, a
Mapping can explicitly specify the
Mapping with no
precedence is assumed to have a
precedence of 0; the higher the
precedence value, the earlier the
Mapping is attempted.
Mappings have the same
precedence, Ambassador's normal sorting determines the ordering within the
precedence; however, there is no way that Ambassador can ever sort a
Mapping with a lower
precedence ahead of one at a higher
In most cases, you won't need the
tls attribute: just use a
service with an
https:// prefix. However, note that if the
tls attribute is present and
true, Ambassador will originate TLS even if the
service does not have the
tls is present with a value that is not
true, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. TLS context handling is a beta feature of Ambassador at present; please contact us on Slack if you need to specify TLS origination certificates.
Namespaces and Mappings
AMBASSADOR_NAMESPACE is correctly set, Ambassador can map to services in other namespaces by taking advantage of Kubernetes DNS:
service: servicenamewill route to a service in the same namespace as the Ambassador, and
service: servicename.namespacewill route to a service in a different namespace.
To Ambassador, a
resource is a group of one or more URLs that all share a common prefix in the URL path. For example:
https://ambassador.example.com/resource1/foo https://ambassador.example.com/resource1/bar https://ambassador.example.com/resource1/baz/zing https://ambassador.example.com/resource1/baz/zung
all share the
/resource1/ path prefix, so can be considered a single resource. On the other hand:
https://ambassador.example.com/resource1/foo https://ambassador.example.com/resource2/bar https://ambassador.example.com/resource3/baz/zing https://ambassador.example.com/resource4/baz/zung
share only the prefix
/ -- you could tell Ambassador to treat them as a single resource, but it's probably not terribly useful.
Note that the length of the prefix doesn't matter: if you want to use prefixes like
/v1/this/is/my/very/long/resource/name/, go right ahead, Ambassador can handle it.
Also note that Ambassador does not actually require the prefix to start and end with
/ -- however, in practice, it's a good idea. Specifying a prefix of
would match all of the following:
https://ambassador.example.com/man/foo https://ambassador.example.com/mankind https://ambassador.example.com/man-it-is/really-hot-today https://ambassador.example.com/manohmanohman
which is probably not what was intended.
service is simply a URL to Ambassador. For example:
servicenameassumes that DNS can resolve the bare servicename, and that it's listening on the default HTTP port;
servicename.domainsupplies a domain name (for example, you might do this to route across namespaces in Kubernetes); and
service:3000supplies a nonstandard port number.
At present, Ambassador relies on Kubernetes to do load balancing: it trusts that using the DNS to look up the service by name will do the right thing in terms of spreading the load across all instances of the service.