5 min • read

Introduction to the Mapping resource

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 Mapping resource.

Quick example

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

Required attributeDescription
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 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:

apiVersion: getambassador.io/v3alpha1
kind: Mapping
name: httpbin-mapping
prefix: /httpbin/
service: http://httpbin.org

Applying a Mapping resource

A Mapping resource can be managed using the same workflow as any other Kubernetes resources (e.g., service, 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:

kubectl apply -f httpbin-mapping.yaml

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.

Extending Mappings

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):

apiVersion: getambassador.io/v3alpha1
kind: Mapping
name: cqrs-get
prefix: /cqrs/
method: GET
service: getcqrs
apiVersion: getambassador.io/v3alpha1
kind: Mapping
name: cqrs-put
prefix: /cqrs/
method: PUT
service: putcqrs

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. A service is defined as:


Where everything except for the service is optional.

  • scheme can be either http or https; if not present, the default is http.
  • service is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the . character.
  • namespace is 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 ambassador Module. When using a Consul resolver, namespace is not allowed.
  • port is the port to which a request should be sent. If not specified, it defaults to 80 when the scheme is http or 443 when the scheme is https. Note that the resolver may return a port in which case the port setting is ignored.

Note that while using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace.

Best practices for configuration

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 logs will be helpful. However, it's always possible to e.g. 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 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.