From e1b40e768c86282721acb9ed455f913855fc44ca Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 16 Oct 2025 23:46:24 -0700 Subject: [PATCH 01/12] Create installing-kourier.md Initial write up --- docs/versioned/install/installing-kourier.md | 115 +++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/versioned/install/installing-kourier.md diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md new file mode 100644 index 0000000000..42be9b0025 --- /dev/null +++ b/docs/versioned/install/installing-kourier.md @@ -0,0 +1,115 @@ +--- +audience: administrator +components: + - serving +function: how-to +--- + +# Installing Kourier on Knative + +This guide walks you through manually installing and customizing Kourier for use with Knative. + +## Before you begin + +This installation is recommended for Knative installations without Istio installed. + +You need: + +- A Kubernetes cluster created. + +## Supported Kourier versions + +You can view the latest tested Kourier version on the [Kourier releases page](https://github.com/knative-extensions/net-kourier/releases). + +## Installing Kourier + +1. Install Knative Serving if not already installed: + +``` bash +kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-crds.yaml +kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-core.yaml +``` + +1. Install Kourier: + +```bash +kubectl apply -f https://github.com/knative/net-kourier/releases/latest/download/kourier.yaml +``` + +1. Configure Knative Serving to use the proper `ingress.class`: + +```bash +kubectl patch configmap/config-network \ + -n knative-serving \ + --type merge \ + -p '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}' +``` + +1. Optional - Set your desired domain (replace 127.0.0.1.nip.io to your preferred domain): + +```bash +kubectl patch configmap/config-domain \ + -n knative-serving \ + --type merge \ + -p '{"data":{"127.0.0.1.nip.io":""}}' +``` + +1. Optional - Deploy a sample hello world app: + +```bash +cat <<-EOF | kubectl apply -f - +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: helloworld-go +spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + env: + - name: TARGET + value: Go Sample v1 +EOF +``` + +1. Optional - For testing purposes, you can use port-forwarding to make requests to Kourier from your machine: + +```bash +kubectl port-forward --namespace kourier-system $(kubectl get pod -n kourier-system -l "app=3scale-kourier-gateway" --output=jsonpath="{.items[0].metadata.name}") 8080:8080 19000:9000 8443:8443 + +curl -v -H "Host: helloworld-go.default.127.0.0.1.nip.io" http://localhost:8080 +``` + +## Deployment + +By default, the deployment of the Kourier components is split between two different namespaces: + +- `knative-serving` - Namespace where Kourier control is deployed. +- `kourier-system` - Namespace where gateways are deployed. + +To change the Kourier gateway namespace, you will need to: + +- Modify the files in `config/` and replace all the namespaces fields that have `kourier-system` with the desired namespace. +- Set the `KOURIER_GATEWAY_NAMESPACE` environmental variable in the `kourier-control` deployment to the new namespace. + +## Features + +Kourier provides the following features: + +- Traffic splitting between Knative revisions. +- Automatic update of endpoints as they are scaled. +- Support for gRPC services. +- Timeouts and retries. +- TLS +- Cipher Suite +- External Authorization support. +- Proxy Protocol (AN EXPERIMENTAL / ALPHA FEATURE) + +## Clean up Kourier + +See the Uninstall Kourier. + +## What's next + +- View the [Knative Serving documentation](../serving/README.md). From 0f64acfb45702343cc2af55a7d60000b872dfefd Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Oct 2025 00:18:51 -0700 Subject: [PATCH 02/12] Added to nav and small edit --- docs/versioned/.nav.yml | 3 ++- docs/versioned/install/installing-kourier.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 75968b917d..ae345005bb 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -254,7 +254,8 @@ 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 Kourier for Knative: install/installing-kourier.md + # TODO: docs for contour, gateway-api - 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-kourier.md b/docs/versioned/install/installing-kourier.md index 42be9b0025..d869704491 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -5,7 +5,7 @@ components: function: how-to --- -# Installing Kourier on Knative +# Installing Kourier for Knative This guide walks you through manually installing and customizing Kourier for use with Knative. From c31c34b1c445496a640f221037c023a77a8f3eeb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Oct 2025 20:38:01 -0700 Subject: [PATCH 03/12] Update installing-kourier.md Finished bringing over content --- docs/versioned/install/installing-kourier.md | 187 +++++++++++++++---- 1 file changed, 146 insertions(+), 41 deletions(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index d869704491..ad72282abd 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -7,7 +7,7 @@ function: how-to # Installing Kourier for Knative -This guide walks you through manually installing and customizing Kourier for use with Knative. +This guide walks you through manually installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving. Kourier is a lightweight alternative for the Istio ingress as its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane for it. ## Before you begin @@ -25,61 +25,61 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht 1. Install Knative Serving if not already installed: -``` bash -kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-crds.yaml -kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-core.yaml -``` + ``` bash + kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-crds.yaml + kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-core.yaml + ``` 1. Install Kourier: -```bash -kubectl apply -f https://github.com/knative/net-kourier/releases/latest/download/kourier.yaml -``` + ```bash + kubectl apply -f https://github.com/knative/net-kourier/releases/latest/download/kourier.yaml + ``` 1. Configure Knative Serving to use the proper `ingress.class`: -```bash -kubectl patch configmap/config-network \ - -n knative-serving \ - --type merge \ - -p '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}' -``` + ```bash + kubectl patch configmap/config-network \ + -n knative-serving \ + --type merge \ + -p '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}' + ``` 1. Optional - Set your desired domain (replace 127.0.0.1.nip.io to your preferred domain): -```bash -kubectl patch configmap/config-domain \ - -n knative-serving \ - --type merge \ - -p '{"data":{"127.0.0.1.nip.io":""}}' -``` + ```bash + kubectl patch configmap/config-domain \ + -n knative-serving \ + --type merge \ + -p '{"data":{"127.0.0.1.nip.io":""}}' + ``` 1. Optional - Deploy a sample hello world app: -```bash -cat <<-EOF | kubectl apply -f - -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: helloworld-go -spec: - template: + ```bash + cat <<-EOF | kubectl apply -f - + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go spec: - containers: - - image: gcr.io/knative-samples/helloworld-go - env: - - name: TARGET - value: Go Sample v1 -EOF -``` + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + env: + - name: TARGET + value: Go Sample v1 + EOF + ``` 1. Optional - For testing purposes, you can use port-forwarding to make requests to Kourier from your machine: -```bash -kubectl port-forward --namespace kourier-system $(kubectl get pod -n kourier-system -l "app=3scale-kourier-gateway" --output=jsonpath="{.items[0].metadata.name}") 8080:8080 19000:9000 8443:8443 + ```bash + kubectl port-forward --namespace kourier-system $(kubectl get pod -n kourier-system -l "app=3scale-kourier-gateway" --output=jsonpath="{.items[0].metadata.name}") 8080:8080 19000:9000 8443:8443 -curl -v -H "Host: helloworld-go.default.127.0.0.1.nip.io" http://localhost:8080 -``` + curl -v -H "Host: helloworld-go.default.127.0.0.1.nip.io" http://localhost:8080 + ``` ## Deployment @@ -106,9 +106,114 @@ Kourier provides the following features: - External Authorization support. - Proxy Protocol (AN EXPERIMENTAL / ALPHA FEATURE) -## Clean up Kourier +## Setup TLS certificate + +Create a secret containing your TLS certificate and Private key: + +```bash +kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE} +``` + +Add the following env vars to net-kourier-controller in the "kourier" container: + +```bash +CERTS_SECRET_NAMESPACE: ${NAMESPACES_WHERE_THE_SECRET_HAS_BEEN_CREATED} +CERTS_SECRET_NAME: ${CERT_NAME} +``` + +### Cipher Suites + +You can specify the cipher suites for TLS external listener. To specify the cipher suites you want to allow, run the following command to patch config-kourier ConfigMap: + +```bash +kubectl -n "knative-serving" patch configmap/config-kourier \ + --type merge \ + -p '{"data":{"cipher-suites":"ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-ECDSA-CHACHA20-POLY1305"}}' +``` + +The default uses the default cipher suites of the envoy version. + +## External Authorization Configuration + +If you want to enable the external authorization support you can set these ENV vars in the net-kourier-controller deployment: + +| Environment Variable | Description | +|---| --- | +| `KOURIER_EXTAUTHZ_HOST` | Required. The external authorization service and port: my-auth:2222 | +| `KOURIER_EXTAUTHZ_FAILUREMODEALLOW` | Required. Allow traffic to go through if the ext auth service is down. Accepts true/false | +| `KOURIER_EXTAUTHZ_PROTOCOL` | The protocol used to query the ext auth service. Can be one of: GRPC, HTTP, or HTTPS. Defaults to GRPC | +| `KOURIER_EXTAUTHZ_MAXREQUESTBYTES` | Max request bytes defaults to 8192 bytes. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation.| +| `KOURIER_EXTAUTHZ_TIMEOUT` | Max time in ms to wait for the ext authz service. Defaults to 2s | +| `KOURIER_EXTAUTHZ_PATHPREFIX` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to HTTP or HTTPS path to query the ext auth service. For example, if set to `/verify` it will query `/verify/` (notice the trailing `/`). If not set it will query `/` | +| `KOURIER_EXTAUTHZ_PACKASBYTES` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to grpc sends the body as raw bytes instead of a UTF-8 string. Accepts only true/false t/f or 1/0. Attempting to set another value will throw an error. Defaults to false. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation. | + +## Proxy Protocol Configuration + +Note: this is an experimental/alpha feature. + +To enable proxy protocol feature, run the following command to patch config-kourier ConfigMap: + +```bash +kubectl patch configmap/config-kourier \ + -n knative-serving \ + --type merge \ + -p '{"data":{"enable-proxy-protocol":"true"}}' +``` + +Ensure that the file was updated successfully: + +```bash +kubectl get configmap config-kourier --namespace knative-serving --output yaml +``` + +### LoadBalancer configuration + +Use your LB provider annotation to enable proxy-protocol. + +- If you are planning to enable external-domain-tls, use your LB provider annotation to specify a custom name to use for the Load balancer, This is used to work around the issue of kube-proxy adding external LB address to node local iptables rule, which will break requests to an LB from in-cluster if the LB is expected to terminate SSL or proxy protocol. + +- Change the external Traffic Policy to local so the LB we'll preserve the client source IP and avoids a second hop for LoadBalancer. + +Example (Scaleway provider): + +```bash +apiVersion: v1 +kind: Service +metadata: + name: kourier + namespace: kourier-system + annotations: + service.beta.kubernetes.io/scw-loadbalancer-proxy-protocol-v2: '*' + service.beta.kubernetes.io/scw-loadbalancer-use-hostname: "true" + labels: + networking.knative.dev/ingress-provider: kourier +spec: + ports: + - name: http2 + port: 80 + protocol: TCP + targetPort: 8080 + - name: https + port: 443 + protocol: TCP + targetPort: 8443 + selector: + app: 3scale-kourier-gateway + externalTrafficPolicy: Local + type: LoadBalancer +``` + +## Tips + +Domain Mapping is configured to explicitly use http2 protocol only. This behaviour can be disabled by adding the following annotation to the Domain Mapping resource + +```bash +kubectl annotate domainmapping kourier.knative.dev/disable-http2=true --namespace +``` + +A good use case for this configuration is DomainMapping with Websocket -See the Uninstall Kourier. +This annotation is an experimental/alpha feature. The annotation name my change in the future. ## What's next From e5956c0dabe30f3b518039a9a1ec9f36108d0a57 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 20 Oct 2025 00:15:26 -0700 Subject: [PATCH 04/12] Update installing-kourier.md Misc edits --- docs/versioned/install/installing-kourier.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index ad72282abd..3ca184de2c 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -7,7 +7,7 @@ function: how-to # Installing Kourier for Knative -This guide walks you through manually installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving. Kourier is a lightweight alternative for the Istio ingress as its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane for it. +This page walks you through manually installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving. Kourier is a lightweight alternative for the Istio ingress as its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane for it. ## Before you begin @@ -15,7 +15,7 @@ This installation is recommended for Knative installations without Istio install You need: -- A Kubernetes cluster created. +- A Kubernetes cluster with the Knative Serving component installed. ## Supported Kourier versions @@ -45,7 +45,7 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht -p '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}' ``` -1. Optional - Set your desired domain (replace 127.0.0.1.nip.io to your preferred domain): +1. Optional - Set your desired domain (replace `127.0.0.1.nip.io` to your preferred domain): ```bash kubectl patch configmap/config-domain \ @@ -135,11 +135,11 @@ The default uses the default cipher suites of the envoy version. ## External Authorization Configuration -If you want to enable the external authorization support you can set these ENV vars in the net-kourier-controller deployment: +If you want to enable the external authorization support you can set these environment variables in the `net-kourier-controller` deployment: | Environment Variable | Description | |---| --- | -| `KOURIER_EXTAUTHZ_HOST` | Required. The external authorization service and port: my-auth:2222 | +| `KOURIER_EXTAUTHZ_HOST` | Required. The external authorization service and port: `my-auth:2222` | | `KOURIER_EXTAUTHZ_FAILUREMODEALLOW` | Required. Allow traffic to go through if the ext auth service is down. Accepts true/false | | `KOURIER_EXTAUTHZ_PROTOCOL` | The protocol used to query the ext auth service. Can be one of: GRPC, HTTP, or HTTPS. Defaults to GRPC | | `KOURIER_EXTAUTHZ_MAXREQUESTBYTES` | Max request bytes defaults to 8192 bytes. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation.| @@ -168,9 +168,9 @@ kubectl get configmap config-kourier --namespace knative-serving --output yaml ### LoadBalancer configuration -Use your LB provider annotation to enable proxy-protocol. +Use your load balancer provider annotation to enable proxy-protocol. -- If you are planning to enable external-domain-tls, use your LB provider annotation to specify a custom name to use for the Load balancer, This is used to work around the issue of kube-proxy adding external LB address to node local iptables rule, which will break requests to an LB from in-cluster if the LB is expected to terminate SSL or proxy protocol. +- If you are planning to enable external-domain-tls, use your load balancer (LB) provider annotation to specify a custom name to use for the load balancer. This is used to work around the issue of kube-proxy adding external LB address to node local iptables rule, which will break requests to an LB from in-cluster if the LB is expected to terminate SSL or proxy protocol. - Change the external Traffic Policy to local so the LB we'll preserve the client source IP and avoids a second hop for LoadBalancer. @@ -213,7 +213,7 @@ kubectl annotate domainmapping kourier.knative.dev/disable A good use case for this configuration is DomainMapping with Websocket -This annotation is an experimental/alpha feature. The annotation name my change in the future. +This annotation is an experimental feature. The annotation name my change in the future. ## What's next From b363d5793a8630eacd13ff2be6c921ca50ee63a2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 22:49:03 -0800 Subject: [PATCH 05/12] Update docs/versioned/install/installing-kourier.md Co-authored-by: Evan Anderson --- docs/versioned/install/installing-kourier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index 3ca184de2c..a0e0487184 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -33,7 +33,7 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht 1. Install Kourier: ```bash - kubectl apply -f https://github.com/knative/net-kourier/releases/latest/download/kourier.yaml + kubectl apply -f {{ artifact(repo="net-kourier",org="knative-extensions",file="kourier.yaml" }} ``` 1. Configure Knative Serving to use the proper `ingress.class`: From a15f4598f3c37ce3b2a1ad6ff459064e0a944ed5 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 22:51:36 -0800 Subject: [PATCH 06/12] Update docs/versioned/install/installing-kourier.md Co-authored-by: Evan Anderson --- docs/versioned/install/installing-kourier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index a0e0487184..243d11b00d 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -85,7 +85,7 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht By default, the deployment of the Kourier components is split between two different namespaces: -- `knative-serving` - Namespace where Kourier control is deployed. +- `knative-serving` - Namespace where Kourier controlle is deployed. - `kourier-system` - Namespace where gateways are deployed. To change the Kourier gateway namespace, you will need to: From daa34682b04524ef0ebd8eb9f6428f0d06999a55 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 22:54:36 -0800 Subject: [PATCH 07/12] Renamed title and moved Nav location --- docs/versioned/.nav.yml | 3 +-- docs/versioned/install/installing-kourier.md | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index ae345005bb..c9d6abe504 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 - - Install Kourier for Knative: install/installing-kourier.md - # TODO: docs for contour, gateway-api - 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. @@ -274,6 +272,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 + - Plugin Kourier: install/installing-kourier.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 diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index 243d11b00d..eb3473c0ec 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -5,7 +5,7 @@ components: function: how-to --- -# Installing Kourier for Knative +# Plugin: Kourier This page walks you through manually installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving. Kourier is a lightweight alternative for the Istio ingress as its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane for it. From 30d79ba0ff4d58a1b4cad24a7954e31368943fa6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 13 Nov 2025 23:10:18 -0800 Subject: [PATCH 08/12] Update installing-kourier.md Syntax error fix --- docs/versioned/install/installing-kourier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index eb3473c0ec..a4346fc46d 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -33,7 +33,7 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht 1. Install Kourier: ```bash - kubectl apply -f {{ artifact(repo="net-kourier",org="knative-extensions",file="kourier.yaml" }} + kubectl apply -f {{ artifact(repo="net-kourier",org="knative-extensions",file="kourier.yaml" )}} ``` 1. Configure Knative Serving to use the proper `ingress.class`: From d1f0578b84797a37b537fd0a8bf40e16e5056fa6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 14 Nov 2025 22:08:37 -0800 Subject: [PATCH 09/12] General edits also Nav title tweak --- docs/versioned/.nav.yml | 2 +- docs/versioned/install/installing-kourier.md | 115 ++++++------------- 2 files changed, 38 insertions(+), 79 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index c9d6abe504..88e982fcd9 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -272,7 +272,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 - - Plugin Kourier: install/installing-kourier.md + - Plugin - Kourier: install/installing-kourier.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 diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index a4346fc46d..e8c4b41520 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -7,15 +7,25 @@ function: how-to # Plugin: Kourier -This page walks you through manually installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving. Kourier is a lightweight alternative for the Istio ingress as its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane for it. +This page walks you through manually installing and customizing Kourier for use with Knative. +Kourier is an ingress for Knative Serving and a lightweight alternative for the Istio ingress. +Its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane. +Kourier provides the following features: + +- Traffic splitting between Knative revisions. +- Automatic update of endpoints as they are scaled. +- Support for gRPC services. +- Timeouts and retries. +- TLS +- Cipher Suite +- External Authorization support. ## Before you begin This installation is recommended for Knative installations without Istio installed. -You need: - -- A Kubernetes cluster with the Knative Serving component installed. +You will need a Kubernetes cluster with the Knative Serving component installed. +To install Knative Serving, see [Installing Knative Serving using YAML files](./yaml-install/serving/install-serving-with-yaml.md) or [Install by using the Knative Operator CLI Plugin](./operator/knative-with-operator-cli.md). ## Supported Kourier versions @@ -23,13 +33,6 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht ## Installing Kourier -1. Install Knative Serving if not already installed: - - ``` bash - kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-crds.yaml - kubectl apply -f https://github.com/knative/serving/releases/latest/download/serving-core.yaml - ``` - 1. Install Kourier: ```bash @@ -45,7 +48,11 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht -p '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}' ``` -1. Optional - Set your desired domain (replace `127.0.0.1.nip.io` to your preferred domain): +## Configuration + +### DNS configuration + +Set your desired domain. Replace `127.0.0.1.nip.io` with your preferred domain's IP address: ```bash kubectl patch configmap/config-domain \ @@ -54,61 +61,28 @@ You can view the latest tested Kourier version on the [Kourier releases page](ht -p '{"data":{"127.0.0.1.nip.io":""}}' ``` -1. Optional - Deploy a sample hello world app: - - ```bash - cat <<-EOF | kubectl apply -f - - apiVersion: serving.knative.dev/v1 - kind: Service - metadata: - name: helloworld-go - spec: - template: - spec: - containers: - - image: gcr.io/knative-samples/helloworld-go - env: - - name: TARGET - value: Go Sample v1 - EOF - ``` - -1. Optional - For testing purposes, you can use port-forwarding to make requests to Kourier from your machine: - - ```bash - kubectl port-forward --namespace kourier-system $(kubectl get pod -n kourier-system -l "app=3scale-kourier-gateway" --output=jsonpath="{.items[0].metadata.name}") 8080:8080 19000:9000 8443:8443 - - curl -v -H "Host: helloworld-go.default.127.0.0.1.nip.io" http://localhost:8080 - ``` - -## Deployment - By default, the deployment of the Kourier components is split between two different namespaces: - `knative-serving` - Namespace where Kourier controlle is deployed. - `kourier-system` - Namespace where gateways are deployed. -To change the Kourier gateway namespace, you will need to: +To change the Kourier gateway namespace, do the following steps: -- Modify the files in `config/` and replace all the namespaces fields that have `kourier-system` with the desired namespace. -- Set the `KOURIER_GATEWAY_NAMESPACE` environmental variable in the `kourier-control` deployment to the new namespace. +1. Modify the files in `config/` and replace all the namespaces fields that have `kourier-system` with the desired namespace. +1. Set the `KOURIER_GATEWAY_NAMESPACE` environmental variable in the `kourier-control` deployment to the new namespace. -## Features +Domain Mapping is configured to explicitly onluy use the http2 protocol. You can disable this behavior by adding the following annotation to the Domain Mapping resource. -Kourier provides the following features: +```bash +kubectl annotate domainmapping kourier.knative.dev/disable-http2=true --namespace +``` -- Traffic splitting between Knative revisions. -- Automatic update of endpoints as they are scaled. -- Support for gRPC services. -- Timeouts and retries. -- TLS -- Cipher Suite -- External Authorization support. -- Proxy Protocol (AN EXPERIMENTAL / ALPHA FEATURE) +A good use case for this configuration is DomainMapping with Websocket. +This annotation is an experimental feature and its name is subject to change. -## Setup TLS certificate +### TLS certificates -Create a secret containing your TLS certificate and Private key: +To set up a TLS certificate, create a secret containing your TLS certificate and Private key: ```bash kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE} @@ -133,21 +107,21 @@ kubectl -n "knative-serving" patch configmap/config-kourier \ The default uses the default cipher suites of the envoy version. -## External Authorization Configuration +### External Authorization -If you want to enable the external authorization support you can set these environment variables in the `net-kourier-controller` deployment: +If you want to enable the external authorization support, you can set the following environment variables in the `net-kourier-controller` deployment: | Environment Variable | Description | |---| --- | | `KOURIER_EXTAUTHZ_HOST` | Required. The external authorization service and port: `my-auth:2222` | | `KOURIER_EXTAUTHZ_FAILUREMODEALLOW` | Required. Allow traffic to go through if the ext auth service is down. Accepts true/false | -| `KOURIER_EXTAUTHZ_PROTOCOL` | The protocol used to query the ext auth service. Can be one of: GRPC, HTTP, or HTTPS. Defaults to GRPC | +| `KOURIER_EXTAUTHZ_PROTOCOL` | Use this protocol to query the ext auth service. Can be one of: GRPC, HTTP, or HTTPS. Defaults to GRPC | | `KOURIER_EXTAUTHZ_MAXREQUESTBYTES` | Max request bytes defaults to 8192 bytes. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation.| -| `KOURIER_EXTAUTHZ_TIMEOUT` | Max time in ms to wait for the ext authz service. Defaults to 2s | -| `KOURIER_EXTAUTHZ_PATHPREFIX` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to HTTP or HTTPS path to query the ext auth service. For example, if set to `/verify` it will query `/verify/` (notice the trailing `/`). If not set it will query `/` | -| `KOURIER_EXTAUTHZ_PACKASBYTES` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to grpc sends the body as raw bytes instead of a UTF-8 string. Accepts only true/false t/f or 1/0. Attempting to set another value will throw an error. Defaults to false. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation. | +| `KOURIER_EXTAUTHZ_TIMEOUT` | Maximum time in ms to wait for the `EXTAUTHZ` service. Defaults to 2s | +| `KOURIER_EXTAUTHZ_PATHPREFIX` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to HTTP or HTTPS path to query the ext auth service. For example, if set to `/verify` it will query `/verify/` (notice the trailing `/`). If not set it will query `/`. | +| `KOURIER_EXTAUTHZ_PACKASBYTES` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to GRPC sends the body as raw bytes instead of a UTF-8 string. Accepts only true/false t/f or 1/0. Attempting to set another value will throw an error. Defaults to false. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation. | -## Proxy Protocol Configuration +### Proxy Protocol Configuration Note: this is an experimental/alpha feature. @@ -203,18 +177,3 @@ spec: type: LoadBalancer ``` -## Tips - -Domain Mapping is configured to explicitly use http2 protocol only. This behaviour can be disabled by adding the following annotation to the Domain Mapping resource - -```bash -kubectl annotate domainmapping kourier.knative.dev/disable-http2=true --namespace -``` - -A good use case for this configuration is DomainMapping with Websocket - -This annotation is an experimental feature. The annotation name my change in the future. - -## What's next - -- View the [Knative Serving documentation](../serving/README.md). From 9635597125ed06846f0cf9caeaf91192ef5521ca Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 14 Nov 2025 22:54:16 -0800 Subject: [PATCH 10/12] Update installing-kourier.md Misc edits and formatting --- docs/versioned/install/installing-kourier.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index e8c4b41520..137494e2de 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -10,22 +10,17 @@ function: how-to This page walks you through manually installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving and a lightweight alternative for the Istio ingress. Its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane. -Kourier provides the following features: - -- Traffic splitting between Knative revisions. -- Automatic update of endpoints as they are scaled. -- Support for gRPC services. -- Timeouts and retries. -- TLS -- Cipher Suite -- External Authorization support. ## Before you begin This installation is recommended for Knative installations without Istio installed. -You will need a Kubernetes cluster with the Knative Serving component installed. -To install Knative Serving, see [Installing Knative Serving using YAML files](./yaml-install/serving/install-serving-with-yaml.md) or [Install by using the Knative Operator CLI Plugin](./operator/knative-with-operator-cli.md). +You will need a Kubernetes cluster with the Knative Serving component installed. To install Knative Serving, use either of the following installation methods: + +- [Installing Knative Serving using YAML files](./yaml-install/serving/install-serving-with-yaml.md) +- [Install by using the Knative Operator CLI Plugin](./operator/knative-with-operator-cli.md) + +See also [Installing Knative](README.md). ## Supported Kourier versions From 14a93d36e78d80d2a4e7d0d2e375c4938259d241 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 14 Nov 2025 22:58:15 -0800 Subject: [PATCH 11/12] Update installing-kourier.md Casing in heading titles fixes --- docs/versioned/install/installing-kourier.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index 137494e2de..92afab471d 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -90,7 +90,7 @@ CERTS_SECRET_NAMESPACE: ${NAMESPACES_WHERE_THE_SECRET_HAS_BEEN_CREATED} CERTS_SECRET_NAME: ${CERT_NAME} ``` -### Cipher Suites +### Cipher suites You can specify the cipher suites for TLS external listener. To specify the cipher suites you want to allow, run the following command to patch config-kourier ConfigMap: @@ -102,7 +102,7 @@ kubectl -n "knative-serving" patch configmap/config-kourier \ The default uses the default cipher suites of the envoy version. -### External Authorization +### External authorization If you want to enable the external authorization support, you can set the following environment variables in the `net-kourier-controller` deployment: @@ -116,7 +116,7 @@ If you want to enable the external authorization support, you can set the follow | `KOURIER_EXTAUTHZ_PATHPREFIX` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to HTTP or HTTPS path to query the ext auth service. For example, if set to `/verify` it will query `/verify/` (notice the trailing `/`). If not set it will query `/`. | | `KOURIER_EXTAUTHZ_PACKASBYTES` | If `KOURIER_EXTAUTHZ_PROTOCOL` is equal to GRPC sends the body as raw bytes instead of a UTF-8 string. Accepts only true/false t/f or 1/0. Attempting to set another value will throw an error. Defaults to false. For more information, see [BufferSettings](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-buffersettings) in Envoy documentation. | -### Proxy Protocol Configuration +### Proxy protocol configuration Note: this is an experimental/alpha feature. From e9ea30c1c70f107212037741f0324e82d7870b9e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 15 Nov 2025 22:30:08 -0800 Subject: [PATCH 12/12] Title tweak and edits Refinement edits --- docs/versioned/.nav.yml | 2 +- docs/versioned/install/installing-kourier.md | 29 ++++++++++---------- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 88e982fcd9..859b3056d6 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -272,7 +272,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 - - Plugin - Kourier: install/installing-kourier.md + - Configure Kourier plugin: install/installing-kourier.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 diff --git a/docs/versioned/install/installing-kourier.md b/docs/versioned/install/installing-kourier.md index 92afab471d..bda4eef0e3 100644 --- a/docs/versioned/install/installing-kourier.md +++ b/docs/versioned/install/installing-kourier.md @@ -5,9 +5,9 @@ components: function: how-to --- -# Plugin: Kourier +# Configure Kourier plugin -This page walks you through manually installing and customizing Kourier for use with Knative. +This page describes installing and customizing Kourier for use with Knative. Kourier is an ingress for Knative Serving and a lightweight alternative for the Istio ingress. Its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and a control plane. @@ -15,7 +15,7 @@ Its deployment consists only of an [Envoy proxy](https://www.envoyproxy.io) and This installation is recommended for Knative installations without Istio installed. -You will need a Kubernetes cluster with the Knative Serving component installed. To install Knative Serving, use either of the following installation methods: +You will need a Kubernetes cluster with the Knative Serving component installed. To install Knative Serving, use either of these installation methods: - [Installing Knative Serving using YAML files](./yaml-install/serving/install-serving-with-yaml.md) - [Install by using the Knative Operator CLI Plugin](./operator/knative-with-operator-cli.md) @@ -24,7 +24,7 @@ See also [Installing Knative](README.md). ## Supported Kourier versions -You can view the latest tested Kourier version on the [Kourier releases page](https://github.com/knative-extensions/net-kourier/releases). +You can access the latest tested Kourier version on the [Kourier releases page](https://github.com/knative-extensions/net-kourier/releases). ## Installing Kourier @@ -58,15 +58,15 @@ Set your desired domain. Replace `127.0.0.1.nip.io` with your preferred domain's By default, the deployment of the Kourier components is split between two different namespaces: -- `knative-serving` - Namespace where Kourier controlle is deployed. -- `kourier-system` - Namespace where gateways are deployed. +- `knative-serving` - Where Kourier controlle is deployed. +- `kourier-system` - Where gateways are deployed. To change the Kourier gateway namespace, do the following steps: 1. Modify the files in `config/` and replace all the namespaces fields that have `kourier-system` with the desired namespace. 1. Set the `KOURIER_GATEWAY_NAMESPACE` environmental variable in the `kourier-control` deployment to the new namespace. -Domain Mapping is configured to explicitly onluy use the http2 protocol. You can disable this behavior by adding the following annotation to the Domain Mapping resource. +Domain Mapping is configured to explicitly only use the HTTP2 protocol. You can disable this behavior by adding the following annotation to the Domain Mapping resource. ```bash kubectl annotate domainmapping kourier.knative.dev/disable-http2=true --namespace @@ -83,7 +83,7 @@ To set up a TLS certificate, create a secret containing your TLS certificate and kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE} ``` -Add the following env vars to net-kourier-controller in the "kourier" container: +Add the following environment variables to `net-kourier-controller` in the `kourier` container: ```bash CERTS_SECRET_NAMESPACE: ${NAMESPACES_WHERE_THE_SECRET_HAS_BEEN_CREATED} @@ -92,7 +92,7 @@ CERTS_SECRET_NAME: ${CERT_NAME} ### Cipher suites -You can specify the cipher suites for TLS external listener. To specify the cipher suites you want to allow, run the following command to patch config-kourier ConfigMap: +You can specify the cipher suites for TLS external listener. To specify the cipher suites you want to allow, run the following command to patch the `config-kourier` ConfigMap: ```bash kubectl -n "knative-serving" patch configmap/config-kourier \ @@ -120,7 +120,7 @@ If you want to enable the external authorization support, you can set the follow Note: this is an experimental/alpha feature. -To enable proxy protocol feature, run the following command to patch config-kourier ConfigMap: +To enable proxy protocol feature, run the following command to patch the `config-kourier` ConfigMap: ```bash kubectl patch configmap/config-kourier \ @@ -135,13 +135,13 @@ Ensure that the file was updated successfully: kubectl get configmap config-kourier --namespace knative-serving --output yaml ``` -### LoadBalancer configuration +### Load balancer configuration Use your load balancer provider annotation to enable proxy-protocol. -- If you are planning to enable external-domain-tls, use your load balancer (LB) provider annotation to specify a custom name to use for the load balancer. This is used to work around the issue of kube-proxy adding external LB address to node local iptables rule, which will break requests to an LB from in-cluster if the LB is expected to terminate SSL or proxy protocol. - -- Change the external Traffic Policy to local so the LB we'll preserve the client source IP and avoids a second hop for LoadBalancer. +- If you plan to enable TLS termination for external domains (external-domain-tls), use your load balancer provider’s annotation to specify a custom hostname for the load balancer. + This option is needed to fix a problem caused by kube-proxy. By default, kube-proxy adds the external load balancer’s IP to the node’s local iptables rules. When pods inside the cluster then try to contact the service via its external load balancer address, traffic is mistakenly routed to localhost instead of going out to the real load balancer. As a result, TLS termination and PROXY protocol handling fail entirely when the load balancer is intended to provide those features. +- Change the external Traffic Policy to local so the load balancer will preserve the client source IP and avoid a second hop for the load balancer. Example (Scaleway provider): @@ -171,4 +171,3 @@ spec: externalTrafficPolicy: Local type: LoadBalancer ``` -