Plugin: Kourier

docs/versioned/.nav.yml

@@ -254,7 +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 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.
@@ -273,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
+          - 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

docs/versioned/install/installing-kourier.md

@@ -0,0 +1,173 @@
+---
+audience: administrator
+components:
+  - serving
+function: how-to
+---
+
+# Configure Kourier plugin
+
+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.
+
+## 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, 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)
+
+See also [Installing Knative](README.md).
+
+## Supported Kourier versions
+
+You can access the latest tested Kourier version on the [Kourier releases page](https://github.com/knative-extensions/net-kourier/releases).
+
+## Installing Kourier
+
+1. Install Kourier:
+
+    ```bash
+    kubectl apply -f {{ artifact(repo="net-kourier",org="knative-extensions",file="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"}}'
+    ```
+
+## 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 \
+      -n knative-serving \
+      --type merge \
+      -p '{"data":{"127.0.0.1.nip.io":""}}'
+    ```
+
+By default, the deployment of the Kourier components is split between two different namespaces:
+
+- `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 only use the HTTP2 protocol. You can disable this behavior by adding the following annotation to the Domain Mapping resource.
+
+```bash
+kubectl annotate domainmapping <domain_mapping_name> kourier.knative.dev/disable-http2=true --namespace <namespace>
+```
+
+A good use case for this configuration is DomainMapping with Websocket.
+This annotation is an experimental feature and its name is subject to change.
+
+### TLS certificates
+
+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}
+```
+
+Add the following environment variables 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 the `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
+
+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` | 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` | 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
+
+Note: this is an experimental/alpha feature.
+
+To enable proxy protocol feature, run the following command to patch the `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
+```
+
+### Load balancer configuration
+
+Use your load balancer provider annotation to enable proxy-protocol.
+
+- 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):
+
+```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
+```