Getting Started with Emissary

Success! You have installed Emissary, now let’s get some traffic flowing to your services.

2. Routing traffic from the edge

Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to declaratively define Emissary’s desired state. The workflow you are going to build uses a simple demo app and the Mapping CRD, which is the core resource that you will use with Emissary. It lets you route requests by host and URL path from the edge of your cluster to Kubernetes services.

1. First, apply the YAML for the “Quote of the Moment" service.

kubectl apply -f https://app.getambassador.io/yaml/ambassador-docs/$version$/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.

2. Copy the configuration below and save it to a file called quote-backend.yaml so that you can create a Mapping on your cluster. This Mapping tells Emissary to route all traffic inbound to the /backend/ path to the quote Service.

---
apiVersion: getambassador.io/v2
kind: Mapping
metadata:
  name: quote-backend
spec:
  prefix: /backend/
  service: quote

3. Apply the configuration to the cluster:

kubectl apply -f quote-backend.yaml

With our Mapping created, now we need to access it!

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

export EMISSARY_LB_ENDPOINT=$(kubectl get svc ambassador \
  -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 -Lk http://$EMISSARY_LB_ENDPOINT/backend/

$ curl -Lk http://$EMISSARY_LB_ENDPOINT/backend/

  {
   "server": "idle-cranberry-8tbb6iks",
   "quote": "Non-locality is the driver of truth. By summoning, we vibrate.",
   "time": "2021-02-26T15:55:06.884798988Z"
  }

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

3. Connect your cluster to Ambassador Cloud

The Service Catalog is a web-based interface that lists all of your cluster’s Services. You can view, add, and update metadata associated with each Service, such as the owner, version control repository, and associated Slack channel.

2. At the top, click Add Services then click Connection Instructions in the Edge Stack installation section.

3. Follow the prompts to name the cluster and click Generate a Cloud Token.

4. Follow the prompts to install the cloud token into your cluster.

5. When the token installation completes, refresh the Service Catalog page.

Fantastic! You can now see all your Services in your Ambassador Cloud account! Metadata on your Services about the owner, repo location, etc. can also be shown in Service Catalog via Kubernetes annotations. Continue in the Service Catalog docs to set annotations on your Services.

What’s next?

Explore some of the popular tutorials on Emissary:

• Intro to Mappings: declaratively routes traffic from the edge of your cluster to a Kubernetes service
• Host resource: configure a hostname and TLS options for your ingress.
• Rate Limiting: create policies to control sustained traffic loads

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.