Documentation
Introduction
Configuration
- HTTPProxy Fundamentals
- Gateway API Support
- Ingress v1 Support
- Virtual Hosts
- Inclusion and Delegation
- TLS Termination
- Upstream TLS
- Request Routing
- External Service Routing
- Request Rewriting
- CORS
- Websockets
- Upstream Health Checks
- Client Authorization
- TLS Delegation
- Rate Limiting
- Access logging
- Cookie Rewriting
- Overload Manager
- JWT Verification
- IP Filtering
- Annotations Reference
- Slow Start Mode
- Tracing Support
- API Reference
Deployment
- Deployment Options
- Contour Configuration
- Upgrading Contour
- Enabling TLS between Envoy and Contour
- Redeploy Envoy
Guides
- Deploying Contour on AWS with NLB
- AWS Network Load Balancer TLS Termination with Contour
- Deploying HTTPS services with Contour and cert-manager
- External Authorization Support
- FIPS 140-2 in Contour
- Using Gatekeeper with Contour
- Using Gateway API with Contour
- Global Rate Limiting
- Configuring ingress to gRPC services with Contour
- Health Checking
- Creating a Contour-compatible kind cluster
- Collecting Metrics with Prometheus
- How to Configure PROXY Protocol v1/v2 Support
- Contour/Envoy Resource Limits
Troubleshooting
- Troubleshooting Common Proxy Errors
- Envoy Administration Access
- Contour Debug Logging
- Envoy Debug Logging
- Visualize the Contour Graph
- Show Contour xDS Resources
- Profiling Contour
- Envoy Container Stuck in Unready State
Resources
- Support Policy
- Compatibility Matrix
- Contour Deprecation Policy
- Release Process
- Frequently Asked Questions
- Tagging
- Adopters
- Ecosystem
Security
Contribute
This tutorial walks through an example of using Gateway API with Contour. See the Contour reference documentation for more information on Contour’s Gateway API support.
Prerequisites
The following prerequisites must be met before following this guide:
- A working Kubernetes cluster. Refer to the compatibility matrix for cluster version requirements.
- The kubectl command-line tool, installed and configured to access your cluster.
Deploy Contour with Gateway API enabled
First, deploy Contour with Gateway API enabled. This can be done using either static or dynamic provisioning.
Option #1: Statically provisioned
Create Gateway API CRDs:
$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour/release-1.30/examples/gateway/00-crds.yaml
Create a GatewayClass:
kubectl apply -f - <<EOF
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: contour
spec:
controllerName: projectcontour.io/gateway-controller
EOF
Create a Gateway in the projectcontour
namespace:
kubectl apply -f - <<EOF
kind: Namespace
apiVersion: v1
metadata:
name: projectcontour
---
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: contour
namespace: projectcontour
spec:
gatewayClassName: contour
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
EOF
Deploy Contour:
$ kubectl apply -f https://projectcontour.io/quickstart/contour.yaml
This command creates:
- Namespace
projectcontour
to run Contour - Contour CRDs
- Contour RBAC resources
- Contour Deployment / Service
- Envoy DaemonSet / Service
- Contour ConfigMap
Update the Contour configmap to enable Gateway API processing by specifying a gateway, and restart Contour to pick up the config change:
kubectl apply -f - <<EOF
kind: ConfigMap
apiVersion: v1
metadata:
name: contour
namespace: projectcontour
data:
contour.yaml: |
gateway:
gatewayRef:
name: contour
namespace: projectcontour
EOF
kubectl -n projectcontour rollout restart deployment/contour
See the next section ( Testing the Gateway API) for how to deploy an application and route traffic to it using Gateway API!
Option #2: Dynamically provisioned
Deploy the Gateway provisioner:
$ kubectl apply -f https://projectcontour.io/quickstart/contour-gateway-provisioner.yaml
This command creates:
- Namespace
projectcontour
to run the Gateway provisioner - Contour CRDs
- Gateway API CRDs
- Gateway provisioner RBAC resources
- Gateway provisioner Deployment
Create a GatewayClass:
kubectl apply -f - <<EOF
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: contour
spec:
controllerName: projectcontour.io/gateway-controller
EOF
Create a Gateway:
kubectl apply -f - <<EOF
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: contour
namespace: projectcontour
spec:
gatewayClassName: contour
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
EOF
The above creates:
- A
GatewayClass
namedcontour
controlled by the Gateway provisioner (via theprojectcontour.io/gateway-controller
string) - A
Gateway
resource namedcontour
in theprojectcontour
namespace, using thecontour
GatewayClass - Contour and Envoy resources in the
projectcontour
namespace to implement theGateway
, i.e. a Contour deployment, an Envoy daemonset, an Envoy service, etc.
See the next section ( Testing the Gateway API) for how to deploy an application and route traffic to it using Gateway API!
Configure an HTTPRoute
Deploy the test application:
$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour/release-1.30/examples/example-workload/gatewayapi/kuard/kuard.yaml
This command creates:
- A Deployment named
kuard
in the default namespace to run kuard as the test application. - A Service named
kuard
in the default namespace to expose the kuard application on TCP port 80. - An HTTPRoute named
kuard
in the default namespace, attached to thecontour
Gateway, to route requests forlocal.projectcontour.io
to the kuard service.
Verify the kuard resources are available:
$ kubectl get po,svc,httproute -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 172.30.168.168 <none> 80/TCP 21s
NAME HOSTNAMES
httproute.gateway.networking.k8s.io/kuard ["local.projectcontour.io"]
Test Routing
Note, for simplicity and compatibility across all platforms we’ll use kubectl port-forward
to get traffic to Envoy, but in a production environment you would typically use the Envoy service’s address.
Port-forward from your local machine to the Envoy service:
# If using static provisioning
$ kubectl -n projectcontour port-forward service/envoy 8888:80
# If using dynamic provisioning
$ kubectl -n projectcontour port-forward service/envoy-contour 8888:80
In another terminal, make a request to the application via the forwarded port (note, local.projectcontour.io
is a public DNS record resolving to 127.0.0.1 to make use of the forwarded port):
$ curl -i http://local.projectcontour.io:8888
You should receive a 200 response code along with the HTML body of the main kuard
page.
You can also open http://local.projectcontour.io:8888/ in a browser.
Further reading
This guide only scratches the surface of the Gateway API’s capabilities. See the Gateway API website for more information.