2. Routing traffic from the edge

Emissary uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a Listener CRD, and a Mapping CRD. The Listener CRD tells Emissary what port to listen on, and the Mapping CRD tells Emissary how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services.

1. Start by creating a Listener resource for HTTP on port 8080:

   kubectl apply -f - <<EOF
   ---
   apiVersion: getambassador.io/v3alpha1
   kind: Listener
   metadata:
     name: $productDeploymentName$-listener-8080
     namespace: $productNamespace$
   spec:
     port: 8080
     protocol: HTTP
     securityModel: XFP
     hostBinding:
       namespace:
         from: ALL
   EOF
   

   This Listener will associate with all Hosts in your cluster. This is fine for the quickstart, but is likely not what you really want for production use.
   
   Learn more about Listener.
   Learn more about Host.

2. Apply the YAML for the “Quote” service.

kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml

The Service and Deployment are created in your default namespace. You can use kubectl get services,deployments quote to see their status.

3. Generates the YAML for a Mapping to tell Emissary to route all traffic inbound to the /backend/ path to the quote Service.
   • Path Matching: /backend/
   • OpenAPI Docs: /.ambassador-internal/openapi-docs

Apply this YAML to your target cluster now.

kubectl apply -f - <<EOF
---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: quote-backend
spec:
  hostname: "*"
  prefix: /backend/
  service: quote
  docs:
    path: "/.ambassador-internal/openapi-docs"
EOF

4. Store the Emissary load balancer IP address to a local environment variable. You will use this variable to test access to your service.

export LB_ENDPOINT=$(kubectl -n $productNamespace$ get svc  $productDeploymentName$ \
  -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}")

5. Test the configuration by accessing the service through the Emissary load balancer:

$ curl -i http://$LB_ENDPOINT/backend/

  HTTP/1.1 200 OK
  content-type: application/json
  date: Wed, 23 Jun 2021 15:49:02 GMT
  content-length: 137
  x-envoy-upstream-service-time: 0
  server: envoy

  {
      "server": "ginormous-kumquat-7mkgucxo",
      "quote": "Abstraction is ever present.",
      "time": "2021-06-23T15:49:02.255042819Z"
  }

Victory! You have created your first Emissary Listener and Mapping, routing a request from your cluster’s edge to a service!

What’s next?

Explore some of the popular tutorials on Emissary:

• Configuring Emissary communications: configure how Emissary handles communication with clients
• Intro to Mappings: declaratively routes traffic from the edge of your cluster to a Kubernetes service
• Listener resource: configure ports, protocols, and security options for your ingress.
• Host resource: configure a hostname and TLS options for your ingress.

Emissary has a comprehensive range of features to support the requirements of any edge microservice.

To learn more about how Emissary works, read the Emissary Story.