diff --git a/docs/snippets/dns.md b/docs/snippets/dns.md index b5b6d6d8ce..5b1d1219a5 100644 --- a/docs/snippets/dns.md +++ b/docs/snippets/dns.md @@ -1,20 +1,11 @@ -You can configure DNS to prevent the need to run curl commands with a host header. + +Knative provides a Kubernetes Job called `default-domain` that configures Knative Serving to use [sslip.io](http://sslip.io) as the default DNS suffix. -The following tabs expand to show instructions for configuring DNS. -Follow the procedure for the DNS of your choice: +```bash +kubectl apply -f {{artifact(repo="serving",file="serving-default-domain.yaml")}} +``` -=== "Magic DNS (sslip.io)" - - Knative provides a Kubernetes Job called `default-domain` that configures Knative Serving to use [sslip.io](http://sslip.io) as the default DNS suffix. - - ```bash - kubectl apply -f {{artifact(repo="serving",file="serving-default-domain.yaml")}} - ``` - - !!! warning - This will only work if the cluster `LoadBalancer` Service exposes an - IPv4 address or hostname, so it will not work with IPv6 clusters or local setups - like minikube unless [`minikube tunnel`](https://minikube.sigs.k8s.io/docs/commands/tunnel/) - is running. - - In these cases, see the "Real DNS" or "No DNS" tabs. +This configuration works only if the cluster `LoadBalancer` Service exposes an IPv4 address or hostname. It does not work with IPv6 clusters or local setups such as minikube unless the [`minikube tunnel`](https://minikube.sigs.k8s.io/docs/commands/tunnel/) is running. diff --git a/docs/snippets/netadapter-contour.md b/docs/snippets/netadapter-contour.md new file mode 100644 index 0000000000..a1d56ef23f --- /dev/null +++ b/docs/snippets/netadapter-contour.md @@ -0,0 +1,31 @@ + +Use the following steps to install and enable Contour and set it as the ingress controller. + +1. Install the Knative Contour configuration: + + ```bash + kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="contour.yaml")}} + ``` + +1. Install the Knative Contour integration controller: + + ```bash + kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="net-contour.yaml")}} + ``` + +1. Configure Knative Serving to use Contour: + + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"ingress-class":"contour.ingress.networking.knative.dev"}}' + ``` + +1. Get the external IP address (FQDN) to later configure DNS: + + ```bash + kubectl --namespace contour-external get service envoy + ``` diff --git a/docs/snippets/netadapter-gatewayapi.md b/docs/snippets/netadapter-gatewayapi.md new file mode 100644 index 0000000000..e6c92ac8e8 --- /dev/null +++ b/docs/snippets/netadapter-gatewayapi.md @@ -0,0 +1,62 @@ + +This component is in beta. For the latest information including supported implementations, see the [Knative net-gateway-api](https://github.com/knative-extensions/net-gateway-api). + +Use the following steps to install and configure the Knative Gateway API controller. Note that you need to have a [Gateway API implementation](https://gateway-api.sigs.k8s.io/implementations/) installed in your cluster. The Knative team currently tests the Istio, Contour, and Envoy-Gateway implementations of Gateway API. + +1. Install the Knative Gateway API: + + ```bash + kubectl apply -f {{ artifact(repo="net-gateway-api",org="knative-extensions",file="net-gateway-api.yaml") }} + ``` + + + +1. Configure Gateway resources for external ("north-south") and local ("east-west") Knative traffic. If you do not need separate routing for local traffic (or [private Knative services](../../../serving/services/private-services.md)), you can use the external Gateway for both. + + Knative verifies traffic settings according to the Kubernetes namespace, the name of the Gateways, and an underlying DNS name such as a Kubernetes service DNS name that corresponds to the Gateway. + + ```bash + cat < +Use the following steps to install Istio and set it as the ingress controller. + +1. Install a properly configured Istio: + + ```bash + kubectl apply -l knative.dev/crd-install=true -f {{ artifact(repo="net-istio",org="knative-extensions",file="istio.yaml") }} + kubectl apply -f {{ artifact(repo="net-istio",org="knative-extensions",file="istio.yaml") }} + ``` + +1. Install the Knative Istio controller: + + ```bash + kubectl apply -f {{ artifact(repo="net-istio",org="knative-extensions", file="net-istio.yaml") }} + ``` + +1. Configure the `config-network` ConfigMap to use Istio: + + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"ingress-class":"istio.ingress.networking.knative.dev"}}' + ``` + +1. Get the external IP address (FQDN) to later configure DNS: + + ```bash + kubectl --namespace istio-system get service istio-ingressgateway + ``` diff --git a/docs/snippets/netadapter-kourier.md b/docs/snippets/netadapter-kourier.md new file mode 100644 index 0000000000..50d47057d3 --- /dev/null +++ b/docs/snippets/netadapter-kourier.md @@ -0,0 +1,25 @@ + +Use the following steps to install Kourier and set it as the ingress controller. + +1. Install the Knative Kourier controller: + + ```bash + kubectl apply -f {{ artifact(repo="net-kourier",org="knative-extensions", file="kourier.yaml") }} + ``` + +1. Configure Knative Serving to use Kourier by default: + + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"ingress-class":"kourier.ingress.networking.knative.dev"}}' + ``` + +1. Get the external IP address (FQDN) to later configure DNS: + + ```bash + kubectl --namespace kourier-system get service kourier + ``` diff --git a/docs/snippets/no-dns.md b/docs/snippets/no-dns.md index 2a6bbd1f95..74314c0588 100644 --- a/docs/snippets/no-dns.md +++ b/docs/snippets/no-dns.md @@ -2,40 +2,42 @@ - install/operator/knative-with-operators.md - install/yaml-install/serving/install-serving-with-yaml.md --> -=== "No DNS" - - If you are using `curl` to access [the sample applications](/docs/getting-started/first-service/), or your own Knative app, and are unable to use the "Magic DNS (sslip.io)" or "Real DNS" methods, there is a temporary approach. This is useful for those who wish to evaluate Knative without altering their DNS configuration, as per the "Real DNS" method, or cannot use the "Magic DNS" method due to using, - for example, minikube locally or IPv6 clusters. - - To access your application using `curl` using this method: - - 1. Configure Knative to use a domain reachable from outside the cluster: - ```bash - kubectl patch configmap/config-domain \ - --namespace knative-serving \ - --type merge \ - --patch '{"data":{"example.com":""}}' - ``` - - 1. After starting your application, get the URL of your application: - ```bash - kubectl get ksvc - ``` - The output should be similar to: - ```bash - NAME URL LATESTCREATED LATESTREADY READY REASON - helloworld-go http://helloworld-go.default.example.com helloworld-go-vqjlf helloworld-go-vqjlf True - ``` - - 1. Instruct `curl` to connect to the External IP or CNAME defined by the - networking layer mentioned in section 3, and use the `-H "Host:"` command-line - option to specify the Knative application's host name. - For example, if the networking layer defines your External IP and port to be `http://192.168.39.228:32198` and you wish to access the `helloworld-go` application mentioned earlier, use: - ```bash - curl -H "Host: helloworld-go.default.example.com" http://192.168.39.228:32198 - ``` - In the case of the provided `helloworld-go` sample application, using the default configuration, the output is: - ``` - Hello Go Sample v1! - ``` - Refer to the "Real DNS" method for a permanent solution. +If you are using `curl` to access [the sample applications](/docs/getting-started/first-service/), or your own Knative app, and are unable to use the "Magic DNS (sslip.io)" or "Real DNS" methods, you can evaluate Knative without altering your DNS configuration. You might have this need if minikube locally or IPv6 clusters. + +To access your application using `curl` using this method: + +1. Configure Knative to use a domain reachable from outside the cluster: + + ```bash + kubectl patch configmap/config-domain \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"example.com":""}}' + ``` + +1. After starting your application, get the URL of your application: + + ```bash + kubectl get ksvc + ``` + + The output should be similar to: + + ```bash + NAME URL LATESTCREATED LATESTREADY READY REASON + helloworld-go http://helloworld-go.default.example.com helloworld-go-vqjlf helloworld-go-vqjlf True + ``` + +1. Instruct `curl` to connect to the External IP or CNAME defined by the networking layer mentioned in section 3, and use the `-H "Host:"` command-line option to specify the Knative application's host name. For example, if the networking layer defines your External IP and port to be `http://192.168.39.228:32198` and you wish to access the `helloworld-go` application mentioned earlier, use: + + ```bash + curl -H "Host: helloworld-go.default.example.com" http://192.168.39.228:32198 + ``` + + In the case of the provided `helloworld-go` sample application, using the default configuration, the output is: + + ```bash + Hello Go Sample v1! + ``` + + Refer to the "Real DNS" method for a permanent solution. diff --git a/docs/snippets/real-dns-yaml.md b/docs/snippets/real-dns-yaml.md index d0ec6cf0e7..8e64c90de0 100644 --- a/docs/snippets/real-dns-yaml.md +++ b/docs/snippets/real-dns-yaml.md @@ -1,30 +1,28 @@ -=== "Real DNS" + +To configure DNS for Knative, take the External IP +or CNAME from setting up networking, and configure it with your DNS provider as +follows: - To configure DNS for Knative, take the External IP - or CNAME from setting up networking, and configure it with your DNS provider as - follows: +- If the networking layer produced an External IP address, then configure a wildcard `A` record for the domain. In the following example, `knative.example.com` is the domain suffix for a cluster. - - If the networking layer produced an External IP address, then configure a - wildcard `A` record for the domain: + ```bash + *.knative.example.com == A 35.233.41.212 + ``` - ``` - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == A 35.233.41.212 - ``` +- If the networking layer produced a CNAME, then configure a CNAME record for the domain. In the following example, `knative.example.com` is the domain suffix for a cluster. - - If the networking layer produced a CNAME, then configure a CNAME record for the domain: + ```bash + *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com + ``` - ``` - # Here knative.example.com is the domain suffix for your cluster - *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com - ``` +- After your DNS provider has been configured, direct Knative to use that domain: - - Once your DNS provider has been configured, direct Knative to use that domain: - - ```yaml - # Replace knative.example.com with your domain suffix - kubectl patch configmap/config-domain \ - --namespace knative-serving \ - --type merge \ - --patch '{"data":{"knative.example.com":""}}' - ``` + ```yaml + # Replace knative.example.com with your domain suffix + kubectl patch configmap/config-domain \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"knative.example.com":""}}' + ``` diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index dafe945ba1..e7e6fdd657 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -267,7 +267,8 @@ nav: - Configure high-availability components: serving/config-ha.md - Exclude namespaces from the Knative webhook: serving/webhook-customizations.md - Networking Options: - - Configure the ingress gateway: serving/setting-up-custom-ingress-gateway.md + - Configure Knative networking: serving/config-network-adapters.md + - Configure Istio's ingress gateway: serving/setting-up-custom-ingress-gateway.md - 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 diff --git a/docs/versioned/install/yaml-install/serving/install-serving-with-yaml.md b/docs/versioned/install/yaml-install/serving/install-serving-with-yaml.md index 24762fa252..22a5842da9 100644 --- a/docs/versioned/install/yaml-install/serving/install-serving-with-yaml.md +++ b/docs/versioned/install/yaml-install/serving/install-serving-with-yaml.md @@ -41,104 +41,24 @@ To install the Knative Serving component: ## Install a networking layer -The following tabs expand to show instructions for installing a networking layer. -Follow the procedure for the networking layer of your choice: - -!!! note - **Only Kourier network plugin supported for IBM Z and IBM Power platform.** - Follow the below steps to install Kourier. Post installation, patch the envoy image based on RedHat Maistra as described in [this link](./install-serving-with-yaml-on-IBM-Z-and-IBM-P.md). - - - - -=== "Kourier (Choose this if you are not sure)" - - The following commands install Kourier and enable its Knative integration. - - 1. Install the Knative Kourier controller by running the command: - ```bash - kubectl apply -f {{ artifact(repo="net-kourier",org="knative-extensions",file="kourier.yaml")}} - ``` - - 1. Configure Knative Serving to use Kourier by default by running the command: - ```bash - kubectl patch configmap/config-network \ - --namespace knative-serving \ - --type merge \ - --patch '{"data":{"ingress-class":"kourier.ingress.networking.knative.dev"}}' - ``` - - 1. Fetch the External IP address or CNAME by running the command: - - ```bash - kubectl --namespace kourier-system get service kourier - ``` - - !!! tip - Save this to use in the following [Configure DNS](#configure-dns) section. - - -=== "Istio" - - The following commands install Istio and enable its Knative integration. - - 1. Install a properly configured Istio by following the - [Advanced Istio installation](../../installing-istio.md) instructions or by running the command: - - ```bash - kubectl apply -l knative.dev/crd-install=true -f {{ artifact(repo="net-istio",org="knative-extensions",file="istio.yaml")}} - kubectl apply -f {{ artifact(repo="net-istio",org="knative-extensions",file="istio.yaml")}} - ``` - - 1. Install the Knative Istio controller by running the command: - - ```bash - kubectl apply -f {{ artifact(repo="net-istio",file="net-istio.yaml")}} - ``` - - 1. Fetch the External IP address or CNAME by running the command: - - ```bash - kubectl --namespace istio-system get service istio-ingressgateway - ``` - - !!! tip - Save this to use in the following [Configure DNS](#configure-dns) section. - +Expand the following tabs for instructions on installing network layers. For an overview of network layer options, architecture, and configurations see the [ingress providers](../../../serving/config-network-adapters.md#ingress-providers) on the [Configure Knative Networking](../../../serving/config-network-adapters.md) page. +=== "Kourier" +{% filter indent(width=4) %} +{% include "netadapter-kourier.md" %} +{% endfilter %} === "Contour" - - The following commands install Contour and enable its Knative integration. - - 1. Install a properly configured Contour by running the command: - - ```bash - kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="contour.yaml")}} - ``` - - - 1. Install the Knative Contour controller by running the command: - ```bash - kubectl apply -f {{ artifact(repo="net-contour",org="knative-extensions",file="net-contour.yaml")}} - ``` - - 1. Configure Knative Serving to use Contour by default by running the command: - ```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 by running the command: - - ```bash - kubectl --namespace contour-external get service envoy - ``` - - !!! tip - Save this to use in the following [Configure DNS](#configure-dns) section. - +{% filter indent(width=4) %} +{% include "netadapter-contour.md" %} +{% endfilter %} +=== "Istio" +{% filter indent(width=4) %} +{% include "netadapter-istio.md" %} +{% endfilter %} +=== "Gateway API" +{% filter indent(width=4) %} +{% include "netadapter-gatewayapi.md" %} +{% endfilter %} ## Verify the installation @@ -163,9 +83,22 @@ Follow the procedure for the networking layer of your choice: ## Configure DNS +You can configure DNS to avoid specifying the host header in curl commands, or to access the content with a web browser. + +The following tabs show instructions for configuring DNS. Follow the procedure for the DNS of your choice. + +=== "Magic DNS (sslip.io)" +{% filter indent(width=4) %} {% include "dns.md" %} +{% endfilter %} +=== "Real DNS" +{% filter indent(width=4) %} {% include "real-dns-yaml.md" %} +{% endfilter %} +=== "No DNS" +{% filter indent(width=4) %} {% include "no-dns.md" %} +{% endfilter %} ## Install optional Serving extensions diff --git a/docs/versioned/serving/config-network-adapters.md b/docs/versioned/serving/config-network-adapters.md new file mode 100644 index 0000000000..c1f6e3fe1f --- /dev/null +++ b/docs/versioned/serving/config-network-adapters.md @@ -0,0 +1,317 @@ +--- +audience: administrator +components: + - serving +function: how-to +--- + +# Configure Knative networking + +This page provides configuration guidance for Knative Serving's integration with Kubernetes ingress controllers and gateway implementations. Knative leverages existing ingress controls in your Kubernetes cluster, allowing you to use the same monitoring features and capabilities. + +For installation instructions, see [install a networking layer](../install/yaml-install/serving/install-serving-with-yaml.md#install-a-networking-layer) on the [Install Serving with YAML](../install/yaml-install/serving/install-serving-with-yaml.md) page. + +The Knative `networking.internal.knative.dev` Ingress type is generally referred to as KIngress objects. KIngress is a common abstraction used to support different ingress implementations. It is a custom resource with the name ingresses and apiGroup `networking.internal.knative.dev`. + +Knative Ingress architecture: + +```mermaid +--- +config: + layout: elk + theme: default +--- +flowchart LR + subgraph top[" "] + direction LR + kingress1["Ingress object (KIngress)
networking.internal.knative.dev"] + serving("Serving
controller") + route["Route object
serving.knative.dev"] + end + route -- read by --> serving + serving -- creates --> kingress1 + + style kingress1 fill:#BBDEFB,stroke-width:1px,stroke-dasharray: 0 + style serving fill:#FFE0B2 + style top fill:transparent +``` + +Although Knative uses the same interface for different ingress providers, they behave differently according to their native configurations and additional Knative options specific to the ingress provider. + +## Ingress providers + +Review the tabbed content in this section to determine the optimal networking layer for your cluster. If you already have one of the ingress controllers installed in your cluster, we recommend using your existing installation. For most users without a supported ingress, the Kourier ingress controller is sufficient. You can expand your capabilities with the Contour ingress, a full-feature service mesh with Istio, and the Kubernetes Gateway API. + +=== "Kourier" + + Kourier ingress provider architecture: + + ```mermaid + --- + config: + layout: elk + theme: default + --- + flowchart LR + subgraph bottom[" "] + direction LR + envoy("Envoy deployment
kourier-system namespace") + kourier("net-kourier
controller") + kingress2["KIngress class:
kourier.ingress.networking.knative.dev"] + end + kingress2 -- read by --> kourier + kourier -- programs --> envoy + + style envoy fill:#BBDEFB + style kourier fill:#FFE0B2 + style bottom fill:transparent + ``` + + [Kourier](https://github.com/knative-extensions/net-kourier/blob/main/README.md#deployment), a Knative extension, is a lightweight implementation of the KIngress resource and is suitable for clusters that don't need other ingress features. Kourier is optimal for learning and prototyping, and is installed by the Knative [Quickstart](../getting-started/README.md). + + Kourier is the only supported option for IBM-Z and IBM-P platforms. These IBM platforms require additional steps as documented in [Install Serving with YAML on IBM-Z and IBM-P](../install/yaml-install/serving/install-serving-with-yaml-on-IBM-Z-and-IBM-P.md). + + Kourier provides the following additional configuration options: + + - Access logging. + - Deep Envoy tuning including proxy-protocol, cipher suites, trusted hops, and remote address. + - External authorization, `extauthz`. + - Experimental features: CryptoMB, internal TLS. + +=== "Contour" + + Courier ingress provider architecture: + + ```mermaid + --- + config: + layout: elk + theme: default + --- + flowchart LR + subgraph bottom[" "] + direction LR + C1["KIngress objects"] + C2("Knative
net-contour") + C3["HTTPProxy
projectcontour.io"] + C4("Contour") + end + C1 -- "read by" --> C2 + C2 -- "creates" --> C3 + C3 -- "read by" --> C4 + + style C2 fill:#FFE0B2 + style C3 fill:#BBDEFB + style C4 fill:#BBDEFB + style bottom fill:transparent + ``` + + The Contour ingress controller, `net-contour`, bridges Knative's KIngress resources to Contour's HTTPProxy resources. Contour is a good choice for clusters that already run non-Knative apps, are already using a Contour envoy, or don't need a full-feature service mesh. + + You can include the full native Contour configuration as described in the [Contour Configuration Reference](https://projectcontour.io/docs/1.33/configuration/). Capabilities include CORS policy configuration, direct visibility classes for external and internal traffic, and several cluster-wide configuration options. + +=== "Istio" + + Istio ingress provider architecture: + + ```mermaid + --- + config: + layout: elk + theme: default + --- + flowchart LR + subgraph bottom[" "] + direction LR + VirtualService["Istio
VirtualService"] + istiod("Istio") + net-istio("net-istio
controller") + kingress["KIngress class:
istio.ingress.networking.knative.dev"] + end + kingress -- read by --> net-istio + net-istio -- creates --> VirtualService + VirtualService -- read by --> istiod + + style VirtualService fill:#BBDEFB + style istiod fill:#BBDEFB + style net-istio fill:#FFE0B2 + style bottom fill:transparent + ``` + + The Knative `net-istio` is a KIngress controller for Istio. Istio is a full-feature service mesh that also functions as a Knative ingress. `net-istio` is well suited for enterprises already running Istio or who need advanced service mesh features. + + Knative has a default Istio integration without the full-feature service mesh. The `knative-ingress-gateway` in the `knative-serving` namespace is a shared Istio gateway resource that handles all incoming (north-south) traffic to Knative services. This gateway points to the underlying `istio-ingressgateway` service in the `istio-system` namespace. You can replace this gateway with one of your own. See [Configure Istio's ingress gateway](setting-up-custom-ingress-gateway.md). + + Istio provides the following additional configuration options: + + - Advanced gateway selection with label selectors for fine-grained routing. + - Support for mesh-aware and cluster-local access. + + In addition to [Istio's configuration options](https://istio.io/latest/docs/reference/config/), `net-istio` provides the following additional configuration options for mapping Knative Routes to Istio VirtualServices: + + - Advanced gateway selection with label selectors for fine-grained routing. + - Support for mesh-aware and cluster-local access. + +=== "Gateway API" + + Knative Gateway APU architecture: + + ```mermaid + --- + config: + layout: elk + theme: default + --- + flowchart LR + net-gateway("net-gateway-api
controller") + GW["Gateway"] + KIngress["KIngress objects"] + HR["HTTPRoute"] + subgraph underlying["Gateway-API Implementation
(Contour, Istio, Envoy Gateway, …)"] + Controller("GatewayClass Controller") + end + KIngress -- read by --> net-gateway + net-gateway -- updates --> GW + net-gateway -- creates --> HR + GW -- read by --> Controller + HR -- read by --> Controller + style net-gateway fill:#FFE0B2 + style GW fill:#BBDEFB + style HR fill:#BBDEFB + style Controller fill:#BBDEFB + style underlying fill:#fff3e0,stroke:#ef6c00 + ``` + + The [Knative net-gateway-api](https://github.com/knative-extensions/net-gateway-api) is a KIngress implementation for Knative integration with the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). A recommended choice for many teams adopting the Gateway API to unify ingress across Kubernetes. Clusters with large numbers of Knative Services however, may experience limitations. + + The Kubernetes Gateway API supports a number of implementations. Istio, Contour, and Envoy-Gateway implementations are tested. For more information see [Tested Gateway API version and Ingress](https://github.com/knative-extensions/net-gateway-api/blob/main/docs/test-version.md). + + Knative is designed to support attaching Gateway API policies to both Knative-created HTTPRoutes and the existing Gateway resources which manage with those routes. + +## Ingress configurations + +The Knative tested ingress controllers (Kourier, Contour, and Istio) have the following common configurations: + +- Certificate management: Configurable secrets for TLS encrypted traffic. See [Using a custom TLS certificate for DomainMapping](./services/custom-tls-certificate-domain-mapping.md). +- Timeout policies: Controls for idle, and response stream timeouts. To review timeout settings, see [Configuring the Defaults ConfigMap](./configuration/config-defaults.md). +- Traffic visibility: Mechanisms to expose services externally or cluster-locally. See [Traffic management](./traffic-management.md). +- The mapping of Route objects to `networking.internal.knative.dev` objects is common to these controllers. + +#### Ascertain status and settings + +Use the following command to determine which ingress controllers are installed and their status. + +``` bash +kubectl get pods -n knative-serving +``` + +The ingress controllers have the following names: + +- Kourier: `kourier-control-*`, and `kourier-gateway-*`. Kourier is included in the Knative Serving installation should appear in the results when your cluster is first created. +- Contour: `contour-*`. +- Istio: `istio-webhook-*`. The main Istio control plane pods such as `istiod-*` are in the `istio-system` namespace. Knative adds the `istio-webhook-*` pod in the `knative-serving` namespace when Istio is the chosen networking layer. +- Gateway API: `net-gateway-api-*`. Created whenever Gateway API KIngress class is available. + +Each ingress controller manages only those ingress objects that are annotated with its key. Knative Serving selects the controller based on the rules in the `network-config` ConfigMap. + +You can determine the controller in use by examining the `config-network.yaml`: + +```bash +kubectl describe configmaps config-network -n knative-serving +``` + +Look for the `ingress-class` key. It could also be the `ingress.class` key with a dot. The dash usage is more current and supersedes any key with the dot. In the following example, the `ingress.class` key was initially set for the Kourier controller, but is now set to Contour because the ingress key with a dash takes precedence. + +```yml +ingress-class: contour.ingress.networking.knative.dev +ingress.class: kourier.ingress.networking.knative.dev +``` + +### Changing the controller + +If you want to switch to a controller that is already installed, patch the `config-network` ConfigMap with the new controller as shown in the following example using Kourier. + +```bash +kubectl patch cm config-network -n knative-serving \ + --type merge -p '{"data":{"ingress-class":"kourier.ingress.networking.knative.dev"}}' +``` + +You can remove an unused key with a dot with the following command: + +```bash +kubectl patch configmap config-network -n knative-serving \ +--type=json -p='[{"op": "remove", "path": "/data/ingress.class"}]' +``` + +If you want to install a new controller, see [Install serving with YAML](../install/yaml-install/serving/install-serving-with-yaml.md). Be aware that changing the Ingress class of an existing Route may result in undefined behavior. + +In scenarios where there are multiple networking implementations, you can create a custom ingress class to specify different ingress class annotations for each service. For more information, see [Configuring Services custom ingress class](./services/ingress-class.md). + +There are also third-party Knative networking options and Knative products available but are not tested or managed by the Knative community. For more information, see [Knative offerings](../install/knative-offerings.md). + +## Gateway configurations + +The configurations in this section apply only to an Gateway API implementation. + +Knative assumes two gateways in the cluster: + +- Externally exposed - defines the gateway for external traffic. +- Internally exposed - defines the gateway for local traffic. + +Both gateways route traffic to the Knative services inside the cluster. + +Knative Gateway API architecture: + +```mermaid +--- +config: + look: neo + theme: redux + layout: elk +--- +flowchart LR + subgraph Cluster["Knative Cluster"] + direction TB + ExtGateway["External Gateway
Exposed to external traffic"] + IntGateway["Internal Gateway
Only for local internal traffic"] + KServe["Knative Services"] + InternalClient["Internal Client
Pod / Service inside cluster"] -- "Cluster-internal" --> IntGateway + end + ExtGateway -- Routes external HTTP/HTTPS traffic --> KServe + IntGateway -- Routes internal traffic --> KServe + ExternalClient["External Client
Internet / Outside cluster"] -- Ingress --> ExtGateway + + style ExtGateway fill:#ffe4e1,stroke:#ff0000,stroke-width:2px + style IntGateway fill:#e6ffe6,stroke:#008000,stroke-width:2px + style ExternalClient fill:#f0f8ff,stroke:#333 + style InternalClient fill:#f0fff0,stroke:#333 + style Cluster stroke:#333,stroke-width:3px,stroke-dasharray: 5 5 +``` + +To install the Gateway API and configure the gateways, see the Gateway API tab in [Install a networking layer](../install/yaml-install/serving/install-serving-with-yaml.md#install-a-networking-layer). + +Use the following command to determine the current configuration: + +```bash +kubectl describe configmaps config-gateway -n knative-serving +``` + +The following `config-gateway` example shows an Istio implementation: + +```bash +# external-gateways defines the Gateway to be used for external traffic +external-gateways: | +- class: istio + gateway: istio-system/knative-gateway + service: istio-system/istio-ingressgateway + supported-features: + - HTTPRouteRequestTimeout + +# local-gateways defines the Gateway to be used for cluster local traffic +local-gateways: | + - class: istio + gateway: istio-system/knative-local-gateway + service: istio-system/knative-local-gateway + supported-features: + - HTTPRouteRequestTimeout +``` diff --git a/docs/versioned/serving/setting-up-custom-ingress-gateway.md b/docs/versioned/serving/setting-up-custom-ingress-gateway.md index 27945ad6a0..143a94dbf1 100644 --- a/docs/versioned/serving/setting-up-custom-ingress-gateway.md +++ b/docs/versioned/serving/setting-up-custom-ingress-gateway.md @@ -5,7 +5,7 @@ components: function: how-to --- -# Configuring the ingress gateway +# Configure Istio's ingress gateway Knative uses a shared ingress Gateway to serve all incoming traffic within Knative service mesh, which is the `knative-ingress-gateway` Gateway under