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.iohelm repo update# Create Namespace and Install:kubectl create namespace emissary && \kubectl apply -f https://app.getambassador.io/yaml/emissary/3.0.0/emissary-crds.yamlkubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-systemhelm install emissary-ingress --namespace emissary datawire/emissary-ingress && \kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress
Connecting your installation to Ambassador Cloud
Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of Emissary-ingress and the Developer Control Plane (DCP).
Log in to Ambassador Cloud with GitHub, GitLab or Google and select your team account.
At the top, click Add Services then click Connection Instructions in the "Connect your installation" section.
Follow the prompts to name the cluster and click Generate a Cloud Token.
Follow the prompts to install the cloud token into your cluster.
When the token installation completes, your services will be listed in the DCP.
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.
Start by creating a
Listener
resource for HTTP on port 8080:shellkubectl apply -f - <<EOF---apiVersion: getambassador.io/v3alpha1kind: Listenermetadata:name: emissary-ingress-listener-8080namespace: emissaryspec:port: 8080protocol: HTTPsecurityModel: XFPhostBinding:namespace:from: ALLEOFApply the YAML for the "Quote" service.
shellkubectl apply -f https://app.getambassador.io/yaml/v2-docs/3.0.0/quickstart/qotm.yamlGenerate the YAML for a
Mapping
to tell Emissary-ingress to route all traffic inbound to the/backend/
path to thequote
Service.In this step, we'll be using the Mapping Editor, which you can find in the service details view of your Ambassador Cloud connected installation. Open your browser to https://app.getambassador.io/cloud/services/quote/details and click on New Mapping.
Default options are automatically populated. Enable and configure the following settings, then click Generate Mapping:
Path Matching:
/backend/
OpenAPI Docs:
/.ambassador-internal/openapi-docs
Whether you decide to automatically push the change to Git for this newly create Mapping resource or not, the resulting Mapping should be similar to the example below.
Apply this YAML to your target cluster now.
yamlkubectl apply -f - <<EOF---apiVersion: getambassador.io/v3alpha1kind: Mappingmetadata:name: quote-backendspec:hostname: "*"prefix: /backend/service: quotedocs:path: "/.ambassador-internal/openapi-docs"EOFStore the Emissary-ingress load balancer IP address to a local environment variable. You will use this variable to test access to your service.
shellexport LB_ENDPOINT=$(kubectl -n emissary get svc emissary-ingress \-o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}")Test the configuration by accessing the service through the Emissary-ingress load balancer:
Terminal$ curl -i http://$LB_ENDPOINT/backend/HTTP/1.1 200 OKcontent-type: application/jsondate: Wed, 23 Jun 2021 15:49:02 GMTcontent-length: 137x-envoy-upstream-service-time: 0server: 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.