This page will help you get up and running with Contour.
Before you start
Before you start you will need:
- A Kubernetes cluster (See Deployment Options for provider specific details)
kubectlconfigured with admin access to your cluster
- RBAC must be enabled on your cluster
Add Contour to your cluster
Option 1: Quickstart
As the name suggests, use this option for a quick start with reasonable defaults. If you have specific requirements to customize Contour for environment, see Options 2 and 3.
$ kubectl apply -f https://projectcontour.io/quickstart/contour.yaml
Option 2: Install using Operator
FEATURE STATE: Contour v1.11.0 alpha
Deploy Contour using the operator. First deploy the operator:
$ kubectl apply -f https://projectcontour.io/quickstart/operator.yaml
This command creates:
contour-operatorto run the operator.
- Operator and Contour CRDs
- Operator RBAC resources
- A Deployment to manage the operator
- A Service to front-end the operator’s metrics endpoint.
Then create an instance of the Contour custom resource:
$ kubectl apply -f https://projectcontour.io/quickstart/contour-custom-resource.yaml
Deploying Contour using either option creates:
- Two instances of Contour in the namespace
- A Kubernetes Daemonset running Envoy on each node in the cluster listening on host ports 80/443
- A Service of
type: LoadBalancerthat points to the Contour’s Envoy instances
- Depending on your deployment environment, new cloud resources – for example, a cloud load balancer
Option 3: Install using Helm
The Contour Helm chart contains a large set of configuration options for customizing your Contour deployment.
$ helm repo add bitnami https://charts.bitnami.com/bitnami $ helm install my-release bitnami/contour
NOTE: As of 13 Nov 2020, Helm 2 support has ended and is obsolete. Please ensure you use Helm 3.
If you don’t have an application ready to run with Contour, you can explore with kuard.
$ kubectl apply -f https://projectcontour.io/examples/kuard.yaml
This example specifies a default backend for all hosts, so that you can test your Contour install. It’s recommended for exploration and testing only, however, because it responds to all requests regardless of the incoming DNS that is mapped.
Send requests to application
There are a number of ways to validate everything is working. The first way is to use the external address of the Envoy service and the second is to port-forward to an Envoy pod:
Retrieve the external address of Contour’s Envoy load balancer:
$ kubectl get -n projectcontour service envoy -o wide NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) envoy LoadBalancer 10.100.161.248 a9be.eu-west-1.elb.amazonaws.com 80:30724/TCP,443:32097/TCP 4m58s app=envoy
How you configure DNS depends on your platform:
- On AWS, create a CNAME record that maps the host in your Ingress object to the ELB address.
- If you have an IP address instead (on GCE, for example), create an A record.
Port-forward to an Envoy pod:
$ kubectl port-forward -n projectcontour svc/envoy 80:80
You probably want to run with specific Ingress rules for specific hostnames.
For more deployment options, see the deployment documentation which includes information about .
The detailed documentation provides additional information, including an introduction to Envoy and an explanation of how Contour maps key Envoy concepts to Kubernetes.
We’ve also got a FAQ for short-answer questions and conceptual stuff that doesn’t quite belong in the docs.