4 min • read

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:

    kubectl apply -f - <<EOF
    apiVersion: getambassador.io/v3alpha1
    kind: Listener
    name: emissary-ingress-listener-8080
    namespace: emissary
    port: 8080
    protocol: HTTP
    securityModel: XFP
    from: ALL
  2. Apply the YAML for the “Quote of the Moment" service.

    kubectl apply -f https://app.getambassador.io/yaml/v2-docs/latest/quickstart/qotm.yaml
  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.

    apiVersion: getambassador.io/v3alpha1
    kind: Mapping
    name: quote-backend
    hostname: "*"
    prefix: /backend/
    service: quote
    path: "/.ambassador-internal/openapi-docs"
  4. Apply the configuration to the cluster:

    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.

    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:

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

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.