- Features and Benefits
- Using Ambassador Edge Stack in Your Organization
- Ambassador Edge Stack vs. Other Software
- Certified Builds
- Ambassador Edge Stack Architecture
- Ambassador Edge Stack Deployment Architecture
- Continuous Delivery, Declarative Config, and GitOps
- Microservices API Gateways
- Rate Limiting Concepts
- Self-Service Routing and Deployment Control
- Safely Testing in Production
- OAuth & OIDC Overview
- Why Ambassador Edge Stack Uses Envoy Proxy (External Link)
- Configuring Ambassador Edge Stack
- Mapping Services
- Canary Releases
- Circuit Breakers
- Cross Origin Resource Sharing
- Header-based routing
- Host Header
- Host CRD
- Prefix Regex
- Rate Limits
- Remove Request Headers
- Remove Response Headers
- Add Request Headers
- Add Response Headers
- Automatic Retries
- Routing TCP Connections
- Traffic Shadowing
- Developer Portal
- Filter Reference
- Statistics and Monitoring
Ambassador Edge Stack 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 Edge Stack must have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique.
Ambassador Edge Stack supports a number of attributes to configure and customize mappings.
|is a string identifying the |
|is the URL prefix identifying your resource|
|is the name of the service handling the resource; must include the namespace (e.g. |
|When true, Ambassador Edge Stack adds the ||boolean|
|Specifies a dictionary of other HTTP headers that should be added to each request when talking to the service.||string list|
|Specifies a dictionary of other HTTP headers that should be added to each response when returning response to client.||string list|
|The timeout, in milliseconds, before an idle connection upstream is closed (may be set on a Mapping, AuthService, or in the ||integer|
|The timeout, in milliseconds, for requests coming through the Cluster for this Mapping. Defaults to 3000.||integer|
|Enables Cross-Origin Resource Sharing (CORS) setting on a mapping||dictionary|
|Configures circuit breaking on a mapping.||dictionary|
|If true, enables IPv4 DNS lookups for this mapping's service (the default is set by the ambassadorModule)||boolean|
|If true, enables IPv6 DNS lookups for this mapping's service (the default is set by the ||boolean|
|If true, tells the system that the service will be handling gRPC calls.||boolean|
|Specifies a list of other HTTP headers which must appear in the request for this mapping to be used to route the request.||string list|
|Specifies the value which must appear in the request's HTTP Host header for this mapping to be used to route the request.||string|
|If true, tells the system to interpret the host as a regular expression.||boolean|
|Forces the HTTP Host header to a specific value when talking to the service.||string|
|The timeout, in milliseconds, after which connections through this Mapping will be terminated if no traffic is seen. Defaults to 300000 (5 minutes).||integer|
|Configures load balancer on a mapping.||dictionary|
|Defines the HTTP method for this mapping (e.g. GET, PUT, etc. -- must be all uppercase).||string|
|If true, tells the system to interpret the method as a regular expression.||boolean|
|If true, tells the system to interpret the prefix as a regular expression and requires that the entire path must match the regex, not just the prefix.||boolean|
|Specifies a list rate limit rules on a mapping.||dictionary|
|Specifies a list of HTTP headers that are dropped from the request before sending upstream.||string list|
|Specifies a list of HTTP headers that are dropped from the response before sending to the client.||string list|
|Specifies a list of HTTP headers and regular expressions which must match for this mapping to be used to route the request.||string list|
|Replaces the URL prefix with when talking to the service. Defaults to ||string|
|Performs automatic retries upon request failures.||dictionary|
|The timeout, in milliseconds, for requests through this Mapping. Defaults to 3000.||integer|
|If true, tells the system that it should use HTTPS to contact this service. (It's also possible to use TLS to specify a certificate to present to the service.)||boolean|
|If true, tells Ambassador Edge Stack that this service will use web sockets.||boolean|
enable_ipv6 are set, Ambassador Edge Stack will prefer IPv6 to IPv4. See the
ambassadorModule documentation for more information.
Ambassador Edge Stack 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 Edge Stack's default behavior in specific cases.
|if true, forces the HTTP |
|determines whether |
|if true, this |
|if set when |
|an integer overriding Ambassador Edge Stack's internal ordering for |
|if true, tells Ambassador Edge Stack that this service should bypass |
method is given, the Mapping will apply to all HTTP
Mapping resources can be defined as annotations on Kubernetes services or as independent custom resource definitions.
For example, here is a
Mapping on a Kubernetes
---apiVersion: v1kind: Servicemetadata:name: quannotations:getambassador.io/config: |---apiVersion: ambassador/v1kind: Mappingname: httpbin-mappingprefix: /httpbin/service: http://httpbin.orgspec:ports:- name: httpbinport: 80
Mapping can be created as an independent resource:
---apiVersion: getambassador.io/v2kind: Mappingmetadata:name: httpbin-mappingspec:prefix: /httpbin/service: http://httpbin.org
If you're new to Ambassador, start with the CRD approach. Note that you must use the
apiVersion as noted above.
Here's an example service for implementing the CQRS pattern (using HTTP):
---apiVersion: getambassador.io/v2kind: Mappingmetadata:name: cqrs-getspec:prefix: /cqrs/method: GETservice: getcqrs---apiVersion: getambassador.io/v2kind: Mappingmetadata:name: cqrs-putspec:prefix: /cqrs/method: PUTservice: putcqrs
To Ambassador, a
resource is a group of one or more URLs that all share a common prefix in the URL path. For example:
all share the
/resource1/ path prefix, so it can be considered a single resource. On the other hand:
share only the prefix
/ -- you could tell Ambassador Edge Stack 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 Edge Stack can handle it.
Also note that Ambassador Edge Stack 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:
which is probably not what was intended.
Ambassador Edge Stack routes traffic to a
service is defined as:
Where everything except for the
service is optional.
schemecan be either
https; if not present, the default is
serviceis the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the
namespaceis the namespace in which the service is running. Starting with Ambassador 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the
ambassadorModule. When using a Consul resolver,
namespaceis not allowed.
portis the port to which a request should be sent. If not specified, it defaults to
80when the scheme is
443when the scheme is
https. Note that the resolver may return a port in which case the
portsetting is ignored.
Note that while using
service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is
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 Edge Stack 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 Edge Stack 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.
Ambassador Edge Stack 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: getambassador.io/v2kind: Mappingmetadata:name: catch-allspec:prefix: /service: https://www.getambassador.io
Ambassador Edge Stack 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 Edge Stack's normal sorting determines the ordering within the
precedence; however, there is no way that Ambassador Edge Stack 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 Edge Stack 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 Edge Stack at present; please contact us on Slack if you need to specify TLS origination certificates.
AMBASSADOR_NAMESPACE is correctly set, Ambassador Edge Stack 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 Edge Stack, and
service: servicename.namespacewill route to a service in a different namespace.
When using Linkerd, requests going to an upstream service need to include the
l5d-dst-override header to ensure that Linkerd will route them correctly. Setting
add_linkerd_headers does this automatically, based on the
service attribute in the
add_linkerd_headers is not specified for a given
Mapping, the default is taken from the
ambassadorModule. The overall default is
false: you must explicitly enable
add_linkerd_headers for Ambassador Edge Stack to add the header for you (although you can always add it yourself with
add_request_headers, of course).