From a37539b0b05000c0888001047494a5aa10536021 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 18 Oct 2025 15:56:40 -0700 Subject: [PATCH 1/6] Create installing-contour.md Initial write up --- docs/versioned/install/installing-contour.md | 207 +++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/versioned/install/installing-contour.md diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md new file mode 100644 index 0000000000..d0ff377540 --- /dev/null +++ b/docs/versioned/install/installing-contour.md @@ -0,0 +1,207 @@ +--- +audience: administrator +components: + - serving +function: how-to +--- + +# Installing Contour for Knative + +This guide shows how to install Contour in three ways: + +- By using Contour’s example YAML. +- By using the Helm chart for Contour. +- By using the Contour gateway provisioner. + +It then shows how to deploy a sample workload and route traffic to it through Contour. + +This guide uses all default settings. No additional configuration is required. + +## Before you begin + +This installation requires the following prerequisites: + +- A Kubernetes cluster with Knative installed and [load balancing](../serving/load-balancing/README.md) activated. + +## Supported Contour versions + +For information about Contour versions, see the Contour [Compatibility Matrix](https://projectcontour.io/resources/compatibility-matrix/). + +## Option 1 - YAML installation + +1. Use the following command to install Contour: + + ```bash + kubectl apply -f https://projectcontour.io/quickstart/contour.yaml + ``` + +1. Verify the Contour pods are ready: + + ```bash + kubectl get pods -n projectcontour -o wide + ``` + +You should see the following: + +- Two Contour pods each with status Running and 1/1 Ready. +- One or more Envoy pods, each with the status Running and 2/2 Ready. + +## Option 2 - Helm installation + +This option requires Helm to be installed locally. + +1. Use the following command to add the `bitnami` chart repository that contains the Contour chart: + + ```bash + helm repo add bitnami https://charts.bitnami.com/bitnami + ``` + +Install the Contour chart: + + ```bash + helm install my-release bitnami/contour --namespace projectcontour --create-namespace + ``` + +Verify Contour is ready: + + ```bash + kubectl -n projectcontour get po,svc + ``` + +You should see the following: + +- One instance of pod/my-release-contour-contour with status Running and 1/1 Ready. +- One or more instances of pod/my-release-contour-envoy with each status Running and 2/2 Ready. +- One instance of service/my-release-contour. +- One instance of service/my-release-contour-envoy. + +## Option 3: Contour Gateway Provisioner + +The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour+Envoy instances based on the Gateway's spec. Note that although the provisioning request itself is made via a Gateway API resource (Gateway), this method of installation still allows you to use any of the supported APIs for defining virtual hosts and routes: Ingress, HTTPProxy, or Gateway API’s HTTPRoute and TLSRoute. In fact, this guide will use an Ingress resource to define routing rules, even when using the Gateway provisioner for installation. + +1. Use the following commmand to deploy the Gateway provisioner: + + ```bash + kubectl apply -f https://projectcontour.io/quickstart/contour-gateway-provisioner.yaml + ``` + +1. Verify the Gateway provisioner deployment is available: + + ```bash + kubectl -n projectcontour get deployments + NAME READY UP-TO-DATE AVAILABLE AGE + contour-gateway-provisioner 1/1 1 1 1m + ``` + +1. Create a GatewayClass: + + ```bash + kubectl apply -f - < Date: Sat, 18 Oct 2025 16:09:46 -0700 Subject: [PATCH 2/6] Update .nav.yml Added installing-contour.md to Installing Plugins --- docs/versioned/.nav.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 75968b917d..e482d73293 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -255,6 +255,7 @@ nav: - Installing plugins: - Install Istio for Knative: install/installing-istio.md # TODO: docs for kourier, contour, gateway-api + - Install Contour for Knative: install/installing-contour.md - Install Kafka for Knative: install/eventing/kafka-install.md - Install RabbitMQ for Knative: install/eventing/rabbitmq-install.md # N.B. this duplicates an "eventing" topic above, cross-referenced here. From 6bd04070b7dfe2c4cf79c48ad9648a113838a5e0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 18 Oct 2025 16:41:21 -0700 Subject: [PATCH 3/6] Update installing-contour.md Misc edits --- docs/versioned/install/installing-contour.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index d0ff377540..d4651092b3 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -21,7 +21,8 @@ This guide uses all default settings. No additional configuration is required. This installation requires the following prerequisites: -- A Kubernetes cluster with Knative installed and [load balancing](../serving/load-balancing/README.md) activated. +- A Kubernetes cluster with Knative Serving component installed. +- Knative [load balancing](../serving/load-balancing/README.md) is activated. ## Supported Contour versions @@ -56,13 +57,13 @@ This option requires Helm to be installed locally. helm repo add bitnami https://charts.bitnami.com/bitnami ``` -Install the Contour chart: +1. Install the Contour chart: ```bash helm install my-release bitnami/contour --namespace projectcontour --create-namespace ``` -Verify Contour is ready: +1. Verify Contour is ready: ```bash kubectl -n projectcontour get po,svc From 76b41077d4a5402299c56fe61585d803b935da63 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 18 Oct 2025 16:56:11 -0700 Subject: [PATCH 4/6] Update installing-contour.md Minor edits --- docs/versioned/install/installing-contour.md | 24 +++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index d4651092b3..24a1475c34 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -21,7 +21,7 @@ This guide uses all default settings. No additional configuration is required. This installation requires the following prerequisites: -- A Kubernetes cluster with Knative Serving component installed. +- A Kubernetes cluster with the Knative Serving component installed. - Knative [load balancing](../serving/load-balancing/README.md) is activated. ## Supported Contour versions @@ -42,7 +42,7 @@ For information about Contour versions, see the Contour [Compatibility Matrix](h kubectl get pods -n projectcontour -o wide ``` -You should see the following: +You should see the following results: - Two Contour pods each with status Running and 1/1 Ready. - One or more Envoy pods, each with the status Running and 2/2 Ready. @@ -69,7 +69,7 @@ This option requires Helm to be installed locally. kubectl -n projectcontour get po,svc ``` -You should see the following: +You should see the following results: - One instance of pod/my-release-contour-contour with status Running and 1/1 Ready. - One or more instances of pod/my-release-contour-envoy with each status Running and 2/2 Ready. @@ -78,9 +78,11 @@ You should see the following: ## Option 3: Contour Gateway Provisioner -The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour+Envoy instances based on the Gateway's spec. Note that although the provisioning request itself is made via a Gateway API resource (Gateway), this method of installation still allows you to use any of the supported APIs for defining virtual hosts and routes: Ingress, HTTPProxy, or Gateway API’s HTTPRoute and TLSRoute. In fact, this guide will use an Ingress resource to define routing rules, even when using the Gateway provisioner for installation. +The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour+Envoy instances based on the Gateway's specification. -1. Use the following commmand to deploy the Gateway provisioner: +Although the provisioning request itself is made using a Gateway API resource (Gateway), this method of installation still allows you to use any of the supported APIs for defining virtual hosts and routes: Ingress, HTTPProxy, or Gateway API’s HTTPRoute and TLSRoute. + +1. Use the following command to deploy the Gateway provisioner: ```bash kubectl apply -f https://projectcontour.io/quickstart/contour-gateway-provisioner.yaml @@ -136,18 +138,18 @@ The Gateway provisioner watches for the creation of Gateway API Gateway resource contour contour True 27s ``` -1. Verify the Contour pods are ready by running the following: +1. Verify the Contour pods are ready: ```bash kubectl -n projectcontour get pods ``` -You should see the following: +You should see the following results: - Two Contour pods each with status Running and 1/1 Ready. - One or move Envoy pods, each with the status Running and 2/2 Ready. -## Test with a web application +## Test application Install a web application workload and get some traffic flowing to the backend. @@ -157,7 +159,7 @@ Install a web application workload and get some traffic flowing to the backend. kubectl apply -f https://projectcontour.io/examples/httpbin.yaml ``` -1. Verify the pods and service are ready by running: +1. Verify the pods and service are ready: ```bash kubectl get po,svc,ing -l app=httpbin @@ -175,9 +177,9 @@ Install a web application workload and get some traffic flowing to the backend. kubectl patch ingress httpbin -p '{"spec":{"ingressClassName": "contour"}}' ``` - Now we’re ready to send some traffic to our sample application, via Contour & Envoy. + You you can send some traffic to the sample application, via Contour & Envoy. - 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. + For simplicity and compatibility across all platforms use `kubectl port-forward` to get traffic to Envoy, but in a production environment you would typically use the Envoy service’s address. 1. Port-forward from your local machine to the Envoy service: From 22ae1987733abead9aecc7cb686c26258a2f80d2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 18 Oct 2025 22:07:05 -0700 Subject: [PATCH 5/6] Update installing-contour.md term fix --- docs/versioned/install/installing-contour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index 24a1475c34..f54b8618ae 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -78,7 +78,7 @@ You should see the following results: ## Option 3: Contour Gateway Provisioner -The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour+Envoy instances based on the Gateway's specification. +The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour+Envoy instances based on the Gateway's spec. Although the provisioning request itself is made using a Gateway API resource (Gateway), this method of installation still allows you to use any of the supported APIs for defining virtual hosts and routes: Ingress, HTTPProxy, or Gateway API’s HTTPRoute and TLSRoute. From b2e417fff47a227d4abbf8a21045e9e60d1ee691 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 19 Oct 2025 23:44:40 -0700 Subject: [PATCH 6/6] Update installing-contour.md Misc edits --- docs/versioned/install/installing-contour.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index f54b8618ae..b862fbe5c6 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -7,7 +7,7 @@ function: how-to # Installing Contour for Knative -This guide shows how to install Contour in three ways: +This page shows how to install Contour in three ways: - By using Contour’s example YAML. - By using the Helm chart for Contour. @@ -15,7 +15,7 @@ This guide shows how to install Contour in three ways: It then shows how to deploy a sample workload and route traffic to it through Contour. -This guide uses all default settings. No additional configuration is required. +This guidance uses all default settings. No additional configuration is required. ## Before you begin @@ -23,6 +23,7 @@ This installation requires the following prerequisites: - A Kubernetes cluster with the Knative Serving component installed. - Knative [load balancing](../serving/load-balancing/README.md) is activated. +- HELM installed locally, if selected as the installation method. ## Supported Contour versions @@ -78,7 +79,7 @@ You should see the following results: ## Option 3: Contour Gateway Provisioner -The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour+Envoy instances based on the Gateway's spec. +The Gateway provisioner watches for the creation of Gateway API Gateway resources, and dynamically provisions Contour and Envoy instances based on the Gateway's spec. Although the provisioning request itself is made using a Gateway API resource (Gateway), this method of installation still allows you to use any of the supported APIs for defining virtual hosts and routes: Ingress, HTTPProxy, or Gateway API’s HTTPRoute and TLSRoute. @@ -151,7 +152,7 @@ You should see the following results: ## Test application -Install a web application workload and get some traffic flowing to the backend. +Install a web application workload and activate traffic flowing to the backend. 1. Use the following command to install httpbin: @@ -203,8 +204,6 @@ Install a web application workload and get some traffic flowing to the backend. In a browser or via curl, make a request to `http://local.projectcontour.io:8888`. The `local.projectcontour.io` URL is a public DNS record resolving to `127.0.0.1` to make use of the forwarded port. You should see the httpbin home page. -Congratulations, you have installed Contour, deployed a backend application, created an Ingress to route traffic to the application, and successfully accessed the app with Contour. - ## See also Contour [Getting Started](https://projectcontour.io/getting-started/) documentation.