Ambassador Edge Stack quick start

1. Installation

We'll start by installing Ambassador Edge Stack 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 ambassador && \
kubectl apply -f https://app.getambassador.io/yaml/edge-stack/2.2.2/aes-crds.yaml
kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
helm install edge-stack --namespace ambassador datawire/edge-stack && \
kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes

Connecting your installation to Ambassador Cloud

Now is a great time to enhance your Ambassador Edge Stack experience and take advantage of Ambassador Cloud's advanced capabilities.

1. Log in to Ambassador Cloud with GitHub, GitLab or Google and select your team account.

2. At the top, click Add Services then click Connection Instructions in the "Connect your 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 is completed, your services are listed in Ambassador Cloud.

2. Routing traffic from the edge

Ambassador Edge Stack 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 Ambassador Edge Stack what port to listen on, and the Mapping CRD tells Ambassador Edge Stack 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: edge-stack-listener-8080
     namespace: ambassador
   spec:
     port: 8080
     protocol: HTTP
     securityModel: XFP
     hostBinding:
       namespace:
         from: ALL
   ---
   apiVersion: getambassador.io/v3alpha1
   kind: Listener
   metadata:
     name: edge-stack-listener-8443
     namespace: ambassador
   spec:
     port: 8443
     protocol: HTTPS
     securityModel: XFP
     hostBinding:
       namespace:
         from: ALL
   EOF
   
   

2. Apply the YAML for the "Quote" service.

   shell

   copied

   kubectl apply -f https://app.getambassador.io/yaml/v2-docs/2.2.2/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. Generate the YAML for a Mapping to tell Ambassador Edge Stack to route all traffic inbound to the /backend/ path to the quote 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.

   yaml

   copied

   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 Ambassador Edge Stack 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 ambassador get svc  edge-stack \
     -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}")
   
   

5. Test the configuration by accessing the service through the Ambassador Edge Stack load balancer:

   Terminal

   copied
   $ curl -Lki https://$LB_ENDPOINT/backend/
     HTTP/1.1 200 OK
     content-type: application/json
     date: Wed, 23 Jun 2021 16:49:46 GMT
     content-length: 163
     x-envoy-upstream-service-time: 0
     server: envoy
     {
         "server": "serene-grapefruit-gjd4yodo",
         "quote": "The last sentence you read is often sensible nonsense.",
         "time": "2021-06-23T16:49:46.613322198Z"
     }
   

What's next?

Explore some of the popular tutorials on Ambassador Edge Stack:

• 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

Ambassador Edge Stack has a comprehensive range of features to support the requirements of any edge microservice.

To learn more about how Ambassador Edge Stack works, read the Ambassador Edge Stack Story.