From a37539b0b05000c0888001047494a5aa10536021 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 18 Oct 2025 15:56:40 -0700 Subject: [PATCH 01/10] 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 02/10] 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 03/10] 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 04/10] 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 05/10] 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 06/10] 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. From aa9d44e63ab3b3b79d65f0d9755840ded260ad41 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 16 Nov 2025 22:07:49 -0800 Subject: [PATCH 07/10] Updates New Nav location and reviewer edits --- docs/versioned/.nav.yml | 3 +- docs/versioned/install/installing-contour.md | 213 +++---------------- 2 files changed, 32 insertions(+), 184 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index e482d73293..46ad8cf0b2 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -274,6 +274,7 @@ nav: - Configure domain names: serving/using-a-custom-domain.md - Istio Authorization: serving/istio-authorization.md - Extending Queue Proxy image with QPOptions: serving/queue-extensions.md + - Configure Contour adapter: ./install/installing-contour.md - Serving configuration: - Configure Deployment resources: serving/configuration/deployment.md - Configure gradual rollout of traffic to Revisions: serving/configuration/rolling-out-latest-revision-configmap.md @@ -292,7 +293,7 @@ nav: - Configure Kafka Broker features: eventing/brokers/broker-types/kafka-broker/configuring-kafka-features.md - Configure event source defaults: eventing/configuration/sources-configuration.md - Configure Sugar Controller: eventing/configuration/sugar-configuration.md - - Configure KEDA Autoscaling of Knative Kafka Resources: eventing/configuration/keda-configuration.md + - Configure KEDA Autoscaling of Knative Kafka Resources: eventing/configuration/ - Flagged features: - Serving Features: serving/configuration/feature-flags.md - Eventing Features: diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index b862fbe5c6..cab079dda6 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -5,205 +5,52 @@ components: function: how-to --- -# Installing Contour for Knative +# Configure Contour adapter -This page 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 guidance uses all default settings. No additional configuration is required. +This page describes how to install the Contour adapter for Knative. ## Before you begin -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 +This installation requires a Kubernetes cluster with [Contour](https://projectcontour.io/docs/) installed. 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 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. - -## 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 - ``` - -1. Install the Contour chart: - - ```bash - helm install my-release bitnami/contour --namespace projectcontour --create-namespace - ``` - -1. Verify Contour is ready: - - ```bash - kubectl -n projectcontour get po,svc - ``` - -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. -- 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 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. - -1. Use the following command 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: Sun, 16 Nov 2025 22:32:29 -0800 Subject: [PATCH 08/10] Misc fixes Nav adjustment and small edits --- docs/versioned/.nav.yml | 2 -- docs/versioned/install/installing-contour.md | 32 ++++++++------------ 2 files changed, 13 insertions(+), 21 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 46ad8cf0b2..c9fe881b44 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -254,8 +254,6 @@ nav: - Configuring Knative Eventing CRDs: install/operator/configuring-eventing-cr.md - 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. diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index cab079dda6..df002feadc 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -15,34 +15,28 @@ This installation requires a Kubernetes cluster with [Contour](https://projectco For information about Contour versions, see the Contour [Compatibility Matrix](https://projectcontour.io/resources/compatibility-matrix/). -## Install Contour adapter for Knative - -1. Install a properly configured Contour by running the folowing command command: - -```bash -kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="contour.yaml")}} -``` +## Install and Contour adapter for Knative 1. Install the Knative Contour controller: -```bash -kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="net-contour.yaml")}} -``` + ```bash + kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="net-contour.yaml")}} + ``` 1. Configure Knative Serving to use Contour by default: -```bash -kubectl patch configmap/config-network \ ---namespace knative-serving \ ---type merge \ ---patch '{"data":{"ingress-class":"contour.ingress.networking.knative.dev"}}' -``` + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"ingress-class":"contour.ingress.networking.knative.dev"}}' + ``` 1. Fetch the External IP address or CNAME: -```bash -kubectl --namespace contour-external get service envoy -``` + ```bash + kubectl --namespace contour-external get service envoy + ``` The adapter's configurations are performed natively through Contour. For more information and resources see [Contour](https://projectcontour.io/) home page. From 8645bd1077817c9fe7d06d61e5e71bfa31f516de Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 17 Nov 2025 09:22:13 -0800 Subject: [PATCH 09/10] Update installing-contour.md Coffee assisted edits --- docs/versioned/install/installing-contour.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index df002feadc..47308c7c97 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -7,7 +7,7 @@ function: how-to # Configure Contour adapter -This page describes how to install the Contour adapter for Knative. +This page describes how to install and configure the Contour adapter for Knative: `net-contour`. ## Before you begin @@ -15,7 +15,7 @@ This installation requires a Kubernetes cluster with [Contour](https://projectco For information about Contour versions, see the Contour [Compatibility Matrix](https://projectcontour.io/resources/compatibility-matrix/). -## Install and Contour adapter for Knative +## Install and configure the adapter 1. Install the Knative Contour controller: @@ -32,7 +32,7 @@ For information about Contour versions, see the Contour [Compatibility Matrix](h --patch '{"data":{"ingress-class":"contour.ingress.networking.knative.dev"}}' ``` -1. Fetch the External IP address or CNAME: +1. Get the External IP address or CNAME: ```bash kubectl --namespace contour-external get service envoy @@ -42,7 +42,7 @@ The adapter's configurations are performed natively through Contour. For more in ## Visibility -The following table shows the classes and services configurations for how to expose services. +The following table shows the classes and services that expose Contour services. | ExternalIP | ClusterLocal | | --- | --- | From b1747fc02bd78eda0b32ad6160f11a1298360174 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 17 Nov 2025 09:36:58 -0800 Subject: [PATCH 10/10] Update installing-contour.md Clarification edits --- docs/versioned/install/installing-contour.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/versioned/install/installing-contour.md b/docs/versioned/install/installing-contour.md index 47308c7c97..dd48e1e2a7 100644 --- a/docs/versioned/install/installing-contour.md +++ b/docs/versioned/install/installing-contour.md @@ -32,17 +32,19 @@ For information about Contour versions, see the Contour [Compatibility Matrix](h --patch '{"data":{"ingress-class":"contour.ingress.networking.knative.dev"}}' ``` -1. Get the External IP address or CNAME: +1. Get the External IP address or full qualified domain name (CNAME): ```bash kubectl --namespace contour-external get service envoy ``` + Use this value to configure your external DNS records. + The adapter's configurations are performed natively through Contour. For more information and resources see [Contour](https://projectcontour.io/) home page. ## Visibility -The following table shows the classes and services that expose Contour services. +The following table shows the classes and services that expose Contour networking. | ExternalIP | ClusterLocal | | --- | --- |