Emissary-ingress quick start

1. Installation

We'll start by installing Emissary-ingress into your cluster.

We recommend using Helm but there are other options below to choose from.

# Add the Repo:
helm repo add datawire https://app.getambassador.io
helm repo update
 
# Create Namespace and Install:
kubectl create namespace emissary && \
helm install emissary-ingress --devel --namespace emissary datawire/emissary-ingress && \
kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress

2. Routing traffic from the edge

Emissary-ingress 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-ingress what port to listen on, and the Mapping CRD tells Emissary-ingress 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:

   shell

   copied

   kubectl apply -f - <<EOF
   ---
   apiVersion: getambassador.io/v3alpha1
   kind: Listener
   metadata:
     name: emissary-ingress-listener-8080
     namespace: emissary
   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 of the Moment" service.

   shell

   copied

   kubectl apply -f https://app.getambassador.io/yaml/v2-docs/latest/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. 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-ingress to route all traffic inbound to the /backend/ path to the quote Service.

   yaml

   copied

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

4. Apply the configuration to the cluster:

   shell

   copied

   kubectl apply -f quote-backend.yaml
   
   

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

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

   shell

   copied

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

6. Test the configuration by accessing the service through the Emissary-ingress load balancer:

   Terminal

   copied
   $ 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"
     }
   

What's next?

Explore some of the popular tutorials on Emissary-ingress:

• Configuring Emissary-ingress communications: configure how Emissary-ingress 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-ingress has a comprehensive range of features to support the requirements of any edge microservice.

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