Emissary-ingress 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-ingress is the
At its core a
Mapping resource maps a
resource to a
|is a string identifying the
Mapping (e.g. in diagnostics)
|is the URL prefix identifying your resource
|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-ingress
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:
Mapping resource can be managed using the same workflow as any other Kubernetes resources (e.g.,
deployment). For example, if the above
Mapping is saved into a file called
httpbin-mapping.yaml, the following command will apply the configuration directly to Emissary-ingress:
For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see the Ambassador Operating Model.
Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP):
More detail on each of the available annotations are discussed in subsequent sections.
To Emissary-ingress, 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 Emissary-ingress 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, Emissary-ingress can handle it.
Also note that Emissary-ingress 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.
Emissary-ingress 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 Emissary-ingress 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
Emissary-ingress's configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies:
Emissary-ingress's configuration should be under version control.
While you can always read back the Emissary-ingress's configuration from Kubernetes or its diagnostic service, the Emissary-ingress will not do versioning for you.
Be aware that the Emissary-ingress tries to not start with a broken configuration, but it's not perfect.
Gross errors will result in Emissary-ingress refusing to start, in which case
kubectl logswill be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong
rewriterules. Emissary-ingress can't detect that on its own, although its diagnostic pages can help you figure it out.
Be careful of mapping collisions.
If two different developers try to map
/user/to something, this can lead to unexpected behavior. Emissary-ingress's canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here.
Note: Unless specified, mapping attributes cannot be applied to any other resource type.