Guides: Getting Started with Contour - To Ingress and Beyond

Introduction to Contour

Contour is an open source Kubernetes Ingress controller that acts as a control plane for the Envoy edge and service proxy (see below).​ Contour supports dynamic configuration updates and multi-team ingress delegation while maintaining a lightweight profile.

Contour is built for Kubernetes to empower you to quickly deploy cloud native applications by using the flexible HTTPProxy API which is a lightweight system that provides many of the advanced routing features of a Service Mesh.

Contour deploys the Envoy proxy as a reverse proxy and load balancer. Envoy is a Layer 7 (application layer) bus for proxy and communication in modern service-oriented architectures, such as Kubernetes clusters. Envoy strives to make the network transparent to applications while maximizing observability to ease troubleshooting.

Before You Begin

You’ll need a Kubernetes cluster. This guide uses a Tanzu Kubernetes Grid cluster, but any Kubernetes Cluster whether they’re running on a Public Cloud, in your [Home] Lab, or on your desktop such as KIND or minikube. You’ll also need the Kubernetes CLI kubectl.

1. Verify access to your Kubernetes cluster

   $ kubectl version --short
   Client Version: v1.20.2
   Server Version: v1.19.3+vmware.1
   

2. Create a scratch directory to work from

   mkdir ~/scratch/contour-demo
   cd ~/scratch/contour-demo
   

Installing Contour 1.12.0

Since version 1.11.0 we’ve got two primary options for installing Contour, A singleton install from manifests, or by using the Operator (which is currently in Alpha). Since we only plan to install Contour once on the cluster, we can stick to the safer method of using the Contour provided manifests.

You can install Contour directly from the manifests provided by the project, however best practice would have you download them locally first for validation and repeatability.

1. Download contour installation manifests

   wget https://projectcontour.io/quickstart/v1.12.0/contour.yaml
   

2. View the manifests in your favorite local text editor

   less contour.yaml
   

3. Validate even further by doing a dry run install

   kubectl apply -f contour.yaml --dry-run=client
   

4. If that all looks good (and it should!), perform the actual install

   kubectl apply -f contour.yaml
   

5. After a few moments you can confirm that its ready.

   You’re looking for both the deployment and DaemonSet to show as fully Available, and a valid IP (or hostname) in the EXTERNAL-IP field of your envoy service.

   $ kubectl -n projectcontour get deployment,daemonset,service
   
     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
     deployment.apps/contour   2/2     2            2           2m18s
   
     NAME                   DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
     daemonset.apps/envoy   3         3         3       3            3           <none>          2m17s
   
     NAME              TYPE           CLUSTER-IP       EXTERNAL-IP
     PORT(S)                      AGE
     service/contour   ClusterIP      100.71.191.199   <none>
     8001/TCP                     2m18s
     service/envoy     LoadBalancer   100.66.114.136   a36c85343e9284c1cb4236d844c31aab-1691151764.us-east-2.elb.amazonaws.com   80:30825/TCP,443:30515/TCP   2m18s
   

6. Save the Ingress EXTERNAL-IP for later use as a xip.io dynamic DNS host.

INGRESS_HOST=<external ip address from above>.xip.io

Creating an Ingress using Contour 1.12.0

Now that Contour is installed we can validate it is functioning correctly by deploying an application, exposing it as a service, then creating an Ingress resource. As well as creating the resources we’ll output the manifests to a file for later re-use.

1. Create a namespace

   kubectl create namespace my-ingress-app -o yaml > my-ingress-app-namespace.yaml
   

2. Create a deployment containing a basic nginx pod

   kubectl -n my-ingress-app create deployment --image=nginx \
     nginx -o yaml > my-ingress-app-deployment.yaml
   

3. Create a service for the deployment

   kubectl -n my-ingress-app expose deployment nginx --port 80 -o yaml > my-ingress-app-service.yaml
   

4. Finally create an Ingress for the service

   kubectl -n my-ingress-app create ingress nginx --class=default \
     --rule="nginx.$INGRESS_HOST/*=nginx:80" -o yaml > my-ingress-app-ingress.yaml
   

5. Validate that your resources are deployed and ready

   $ kubectl -n my-ingress-app get all,ingress
   
   Warning: extensions/v1beta1 Ingress is deprecated in v1.14+, unavailable in v1.22+; use networking.k8s.io/v1 Ingress
   NAME                         READY   STATUS    RESTARTS   AGE
   pod/nginx-6799fc88d8-dphdt   1/1     Running   0          13m
   
   NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
   service/nginx   ClusterIP   100.69.247.38   <none>        80/TCP    12m
   
   NAME                    READY   UP-TO-DATE   AVAILABLE   AGE
   deployment.apps/nginx   1/1     1            1           13m
   
   NAME                               DESIRED   CURRENT   READY   AGE
   replicaset.apps/nginx-6799fc88d8   1         1         1       13m
   
   NAME                       CLASS     HOSTS                                                                     ADDRESS                                                                   PORTS   AGE
   ingress.extensions/nginx   default   a36c85343e9284c1cb4236d844c31acb-1691151764.us-east-2.elb.amazonaws.com   a36c85343e9284c1cb4236d844c31acb-1691151764.us-east-2.elb.amazonaws.com   80      51s
   

6. Validate that you can access the application

   $ curl -s nginx.3.13.150.109.xip.io  | grep h1
   
   <h1>Welcome to nginx!</h1>
   

Congratulations! If you see the Welcome to nginx! message, that means you’ve successfully installed and tested Contour as an Ingress Controller. However its so much more than that, so lets explore further.

However let’s clean up our resources before we move on. Since all of our resources are in a single namespace we could use kubectl delete namespace my-ingress-app, However we also saved the manifests so we can use those like so:

mkdir my-ingress-app
mv my-ingress-app-* my-ingress-app/
kubectl delete -f my-ingress-app

Beyond Ingress with Contour 1.12.0

As well as Ingress Contour supports a resource type HTTPProxy which extends the concept of Ingress to add many features that you would normally have to reach for Istio or a similar service mesh to get. We can explore some of those features here.

Having learned our lesson about sub directories above, lets create a directory for our exploration of HTTPProxy.

mkdir http-proxy
cd http-proxy

As we did earlier we’ll start by deploying a nginx Pod and a Service.

1. Create a namespace

   kubectl create namespace http-proxy -o yaml > http-proxy-namespace.yaml
   

2. Create a Deployment containing a basic nginx pod

   kubectl -n http-proxy create deployment --image=nginx \
     nginx -o yaml > http-proxy-nginx-deployment.yaml
   

3. Create a service for the deployment

   kubectl -n http-proxy expose deployment nginx --port 80 -o yaml \
     > http-proxy-nginx-service.yaml
   

Now that we have the Deployment and Service created we can create the HTTPProxy resource. Unfortunately we can’t just sling a kubectl create httpproxy like we could with the other resources so we’ll need to get creative.

1. Create a HTTPProxy manifest

   cat << EOF > http-proxy.yaml
   apiVersion: projectcontour.io/v1
   kind: HTTPProxy
   metadata:
     name: www
     namespace: http-proxy
   spec:
     virtualhost:
       fqdn: www.$INGRESS_HOST
     routes:
       - conditions:
         - prefix: /
         services:
           - name: nginx
             port: 80
   EOF
   

2. Apply the HTTPProxy manifest

   kubectl apply -n http-proxy -f http-proxy.yaml
   

3. Wait a few moments and then attempt to access the nginx service

   curl -s www.3.13.150.109.xip.io | grep h1
   <h1>Welcome to nginx!</h1>
   

Rate Limiting

Now that your nginx is working via HTTPProxy we can look at some of the more advanced features. Let’s start with Rate limiting. Contour 1.12.0 supports doing local rate limiting, which means that each Envoy Pod will have its own limits, vs a global rate limit which would need further coordination between the Envoy Pods. You can also set the Rate limit for the virtualhost, or for a specific route.

Let’s create a fairly aggressive rate limit so we can see the affects of it fairly quickly. The example cluster I am using has three worker nodes, which means three Envoy Pods so if I set a rate limit of 2 per minute we should be able to hit the limit after 6 requests.

1. Create a new HTTPProxy resource with rate limiting enabled

   cat << EOF > rate-limit.yaml
   apiVersion: projectcontour.io/v1
   kind: HTTPProxy
   metadata:
     name: rate
     namespace: http-proxy
   spec:
     virtualhost:
       fqdn: rate.$INGRESS_HOST
       rateLimitPolicy:
         local:
           requests: 2
           unit: minute
     routes:
       - conditions:
         - prefix: /
         services:
           - name: nginx
             port: 80
   EOF
   

2. Apply the new rate limited manifest:

   kubectl -n http-proxy apply -f rate-limit.yaml
   

3. Wait a few moments and then fire up a while loop to connecting to the service and watch it hit the limit after a few hits.

   Note: You’ll need to hit CTRL-C to break the while loop.

   $ while true; do curl -s rate.$INGRESS_HOST | grep -E 'h1|rate' ; done
   
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   local_rate_limited
   local_rate_limited
   local_rate_limited
   ^C
   

That’s it, rate limiting is enabled. This is incredibly useful if you have a service with known limitations or you want to restrict any one user from overwhelming the service.

Weighted routing

The HTTPProxy resource can also route a Virtual Host to multiple services, this is a great feature if you want to perform Blue/Green deployments, or you want to send a small percentage of requests to a special debug endpoint. Let’s explore Weighted routing by adding an Apache service to receive 10% of the requests.

1. Create a Deployment containing a basic httpd pod

   kubectl -n http-proxy create deployment --image=httpd \
     httpd -o yaml > http-proxy-httpd-deployment.yaml
   

2. Create a service for the deployment

   kubectl -n http-proxy expose deployment httpd --port 80 -o yaml \
     > http-proxy-httpd-service.yaml
   

3. Ensure the new Pod is available beside the existing nginx one.

   kubectl get pods -n http-proxy
   NAME                     READY   STATUS    RESTARTS   AGE
   httpd-757fb56c8d-kz476   1/1     Running   0          23s
   nginx-6799fc88d8-jxvj7   1/1     Running   0          163m
   

4. Create a HTTPProxy resource to perform weighted routing across the two services

   cat << EOF > weighted.yaml
   apiVersion: projectcontour.io/v1
   kind: HTTPProxy
   metadata:
     name: weight
     namespace: http-proxy
   spec:
     virtualhost:
       fqdn: weight.$INGRESS_HOST
     routes:
       - conditions:
         - prefix: /
         services:
           - name: httpd
             port: 80
             weight: 10
           - name: nginx
             port: 80
             weight: 90
   EOF
   

5. Apply the new resource

   kubectl -n http-proxy apply -f weighted.yaml
   

6. Test the weighting

   Note: It’s not clear in the documentation, but it appears that the weighting is applied per Envoy Pod, so it might not be exactly 10% for small test runs, but would statistically work out over time.

   $ while true; do curl -s weight.$INGRESS_HOST | grep h1 ; done
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <h1>Welcome to nginx!</h1>
   <html><body><h1>It works!</h1></body></html>
   ^C
   

That’s it! we’ve successfully done a walk through of some of the new features of Contour 1.12.0 and tested out both Rate Limiting and Weighted Routing. Let’s clean up.

Cleanup

1. Delete your http-proxy namespace and resources

   kubectl -n http-proxy delete -f .
   

2. Uninstall Contour

   cd ..
   kubectl delete -f contour.yaml
   

Conclusion

As you can see Contour 1.12.0 is more than just an Ingress Controller as it brings some of the more advanced features of a service mesh but without all the extra resources required. Next time you find yourself looking to run Istio, remember to check in with Contour and see if it will do what you need.