The core Emissary-ingress resource used to manage cluster ingress is the
Mapping resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).
Mapping would route requests to
https://<hostname>/webapp/ to the
webapp-svc Service. This is not a
complete example on its own; see below.
|String||Identifies the Mapping.|
|String||The URL prefix identifying your resource. See below on how Emissary-ingress handles resources.|
|String||The service handling the resource. If a Kubernetes service, it must include the namespace (in the format |
Here's another example using a web service that maps requests to
http://httpbin.org (again, this is not a
complete example on its own; see below):
For demonstration purposes, here's a possible way of combining a
Host, and both
Mappings above that is complete and functional:
- it will accept HTTP or HTTPS on port 8443;
- Emissary-ingress is terminating TLS;
- HTTPS to
foo.example.comwill be routed as above;
- HTTP to
foo.example.comwill be redirected to HTTPS;
- HTTP or HTTPS to other hostnames will be rejected; and
- the associations between the
Host, and the
Note the addition of
selectors to explicitly specify which resources should associate in this example.
A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or 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:
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, these URLs all share the
/resource1/ path prefix, so
/resource1/ can be considered a single resource:
On the other hand, these URLs 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; a prefix like
/v1/this/is/my/very/long/resource/name/ is valid.
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
/man would match all of the following, which probably is not what was intended:
Emissary-ingress routes traffic to a service. A service is defined as
[scheme://]service[.namespace][:port]. 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 Module resource. 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.
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):
Emissary-ingress's configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed.
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.
Gross errors will result in the Emissary-ingress refusing to start, in which case
kubectl logs will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong
rewrite rules. Emissary-ingress can't detect that on its own, although its diagnostic service can help you figure it out.
If two different developers try to map
/myservice/ 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.