Contour Logo

Using Gateway API with Contour


Gateway API is an open source project managed by the Kubernetes SIG-NETWORK community. The project’s goal is to evolve service networking APIs within the Kubernetes ecosystem. Gateway API consists of multiple resources that provide user interfaces to expose Kubernetes applications- Services, Ingress, and more.


Gateway API targets three personas:

  • Platform Provider: The Platform Provider is responsible for the overall environment that the cluster runs in, i.e. the cloud provider. The Platform Provider will interact with GatewayClass and Contour resources.
  • Platform Operator: The Platform Operator is responsible for overall cluster administration. They manage policies, network access, application permissions and will interact with the Gateway resource.
  • Service Operator: The Service Operator is responsible for defining application configuration and service composition. They will interact with xRoute resources and other typical Kubernetes resources.

Gateway API contains three primary resources:

  • GatewayClass: Defines a set of gateways with a common configuration and behavior.
  • Gateway: Requests a point where traffic can be translated to a Service within the cluster.
  • xRoutes: Describes how traffic coming via the Gateway maps to the Services.

Resources are meant to align with personas. For example, a platform operator will create a Gateway, so a developer can expose an HTTP application using an HTTPRoute resource.


The following prerequisites must be met before using Gateway API with Contour:

Using Gateway API with Contour Operator

The preferred method for using Gateway API is with Contour Operator. This is because the GatewayClass and Gateway resources should be managed by active controllers that are implemented by the operator. Refer to the contour and operator designs for additional background on the gateway API implementation.

Run the operator:

$ kubectl apply -f

This command creates:

  • Namespace contour-operator to run the operator.
  • Operator and Contour CRDs.
  • Operator RBAC resources for the operator.
  • A Deployment to manage the operator.
  • A Service to front-end the operator’s metrics endpoint.

Create the Gateway API resources:

Option 1: Using a LoadBalancer Service:

$ kubectl apply -f

Option 2: Using a NodePort Service:

$ kubectl apply -f

Either of the above options create:

  • Namespace projectcontour to run the Gateway and child resources, i.e. Envoy DaemonSet.
  • A Contour custom resource named contour-gateway-sample in the operator’s namespace. This resource exposes infrastructure-specific configuration and is referenced by the GatewayClass.
  • A GatewayClass named sample-gatewayclass that abstracts the infrastructure-specific configuration from Gateways.
  • A Gateway named contour in namespace projectcontour. This gateway will serve the test application through routing rules deployed in the next step.

Testing the Gateway API

Run the test application:

$ kubectl apply -f

This command creates:

  • A Deployment named kuard in namespace projectcontour to run kuard as the test application.
  • A Service named kuard in namespace projectcontour to expose the kuard application on TCP port 80.
  • An HTTPRoute named kuard in namespace projectcontour to route requests for “*” to the kuard service.

Verify the kuard resources are available:

$ kubectl get po,svc,httproute -n projectcontour -l app=kuard
NAME                         READY   STATUS    RESTARTS   AGE
pod/kuard-798585497b-78x6x   1/1     Running   0          21s
pod/kuard-798585497b-7gktg   1/1     Running   0          21s
pod/kuard-798585497b-zw42m   1/1     Running   0          21s

NAME            TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
service/kuard   ClusterIP   <none>        80/TCP    21s

NAME                                  HOSTNAMES   [""]

Test access to the kuard application:

Get the Envoy Service IP address:

export GATEWAY=$(kubectl -n projectcontour get svc/envoy -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

Note: Replace hostname with ip in the above command if your cloud provide uses an IP address for a load-balancer.

Use curl to test access to the application:

$ curl -H "Host:" -s -o /dev/null -w "%{http_code}" "http://$GATEWAY/"

A 200 HTTP status code should be returned.

Ready to try Contour?

Read our getting started documentation.