diff --git a/docs/snippets/dns.md b/docs/snippets/dns.md index b5b6d6d8ce..a6709e38a7 100644 --- a/docs/snippets/dns.md +++ b/docs/snippets/dns.md @@ -1,7 +1,6 @@ -You can configure DNS to prevent the need to run curl commands with a host header. +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 expand to show instructions for configuring DNS. -Follow the procedure for the DNS of your choice: +The following tabs show instructions for configuring DNS. Follow the procedure for the DNS of your choice: === "Magic DNS (sslip.io)" @@ -11,10 +10,5 @@ Follow the procedure for the DNS of your choice: 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. + 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. - In these cases, see the "Real DNS" or "No DNS" tabs. diff --git a/docs/snippets/netadapter-contour.md b/docs/snippets/netadapter-contour.md new file mode 100644 index 0000000000..069e9f382f --- /dev/null +++ b/docs/snippets/netadapter-contour.md @@ -0,0 +1,28 @@ +Use the following steps to install and enable Contour and set it as the ingress conroller. + +1. Install the Knative Contour controller: + + ```bash + kubectl apply -f {{ artifact(org="knative-extensions", repo="net-contour", file="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. Verify the installation by having a pod with the base name of `contour` in the results. + + ```bash + kubectl get pods -n knative-serving + ``` + +1. Get the external IP address (FQDN) to configure DNS records: + + ```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..2d2f117bbe --- /dev/null +++ b/docs/snippets/netadapter-gatewayapi.md @@ -0,0 +1,22 @@ +Use the following steps to install and configure the Knative Gateway API. + +1. Install the Knative Gateway API channel: + + ```bash + kubectl apply -f {{ artifact(repo="net-gateway-api",org="knative-extensions",file="net-gateawy-api.yaml") }} + ``` + +1. Configure Knative Serving to use Knative Gateway API channel: + + ```bash + kubectl patch configmap/config-network \ + --namespace knative-serving \ + --type merge \ + --patch '{"data":{"ingress-class":"gateway-api.ingress.networking.knative.dev"}}' + ``` + +1. Get the external IP address (FQDN) to configure DNS records: + + ```bash + kubectl get gateway --all-namespaces + ``` diff --git a/docs/snippets/netadapter-istio.md b/docs/snippets/netadapter-istio.md new file mode 100644 index 0000000000..37d7236b50 --- /dev/null +++ b/docs/snippets/netadapter-istio.md @@ -0,0 +1,35 @@ +Use the following steps to install Istio and set it as the ingress conroller. + +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",file="net-istio.yaml") }} + ``` + +1. Set 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. Verify the installation by having pods with the base name of `istio` and `istio-webhook` in the results. + + ```bash + kubectl get pods -n knative-serving + ``` + +1. Get the external IP address (FQDN) to configure DNS records: + + ```bash + kubectl --namespace istio-system get service istio-ingressgateway + ``` \ No newline at end of file diff --git a/docs/snippets/netadapter-kourier.md b/docs/snippets/netadapter-kourier.md new file mode 100644 index 0000000000..6b3ff4108d --- /dev/null +++ b/docs/snippets/netadapter-kourier.md @@ -0,0 +1,28 @@ +Use the following steps to install Kourier and set it as the ingress controller. + +1. Install the Knative Kourier controller: + + ```bash + kubectl apply -f https://github.com/knative/net-kourier/releases/latest/download/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. Verify the installation by having pods with the base name of `kourier-controller` and `kourier-gateway` in the results. + + ```bash + kubectl get pods -n knative-serving + ``` + +1. Get the external IP address (FQDN) to configure DNS records: + + ```bash + kubectl --namespace kourier-system get service kourier + ``` diff --git a/docs/snippets/no-dns.md b/docs/snippets/no-dns.md index 2a6bbd1f95..a0826e5284 100644 --- a/docs/snippets/no-dns.md +++ b/docs/snippets/no-dns.md @@ -1,7 +1,3 @@ - === "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, diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index dafe945ba1..2c2ad9a631 100644 --- a/docs/versioned/.nav.yml +++ b/docs/versioned/.nav.yml @@ -267,6 +267,7 @@ nav: - Configure high-availability components: serving/config-ha.md - Exclude namespaces from the Knative webhook: serving/webhook-customizations.md - Networking Options: + - Configure Knative networking: serving/config-network-adapters.md - Configure the ingress gateway: serving/setting-up-custom-ingress-gateway.md - Configure domain names: serving/using-a-custom-domain.md - Istio Authorization: serving/istio-authorization.md diff --git a/docs/versioned/serving/config-network-adapters.md b/docs/versioned/serving/config-network-adapters.md new file mode 100644 index 0000000000..18836a273d --- /dev/null +++ b/docs/versioned/serving/config-network-adapters.md @@ -0,0 +1,181 @@ +--- +audience: administrator +components: + - serving +function: how-to +--- + +# Configure Knative networking + +This page provides installation and configuration guidance for Knative networking. You can configure Ingress controls, service-meshes, and gateways. + +## Network layer options + +Review the following tabs to determine the optimal networking layer for your cluster. For most users, 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. + +The Knative `networking.internal.knative.dev` Ingress type is generally referred to as KIngress objects. + +=== "Kourier" + + The following diagram depicts the flow of KIngress objects, as read by Knative serving. + + ```mermaid + --- + config: + theme: default + layout: elk + look: neo + --- + flowchart LR + + route["Route object"] -- "read by" --> serving-core("Serving
controller") -- creates --> KIngress["Ingress object
networking.internal.knative.dev
(KIngress)"] + ``` + + The following diagram depicts the flow of KIngress objects by Kourier. + + ```mermaid + --- + config: + theme: default + layout: elk + look: neo + --- + flowchart LR + KIngress["KIngress
Class:kourier.ingress.networking.knative.dev"] -- "read by" --> controller("net-kourier
controller") -- programs --> envoy("Envoy deployment
kourier-system namespace") + ``` + + Kourier is a lightweight alternative for the Istio ingress as its deployment consists only of an envoy proxy and a control plane. If Kourier is satisfactory, no further configurations are required. + + Kourier is a fine choice for all platforms, but for IBM-Z and IBM-P platforms it's the only supported option and requires 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). + +=== "Contour" + + ```mermaid + --- + config: + theme: default + layout: elk + look: neo + --- + flowchart LR + C1["Knative
net-contour"] -- creates --> C2["KIngress objects"] + C2 --> C3["Class: contour.ingress.networking.knative.dev"] + ``` + + The Contour ingress controller, `net-contour`, bridges Knative's KIngress resources to Contour's HTTPProxy resources. A good choice for clusters that already run non-Knative apps, teams who want to use a single Ingress controller, and are already using Contour envoy but don't need a full-feature service mesh. + +=== "Istio" + + ```mermaid + --- + config: + theme: default + layout: elk + --- + flowchart LR + I1["Knative net-istio"] -- creates --> I2["Service + Gateway"] + I2 --> I3["Class: istio.ingress.networking.knative.dev
No native Ingress objects"] + ``` + + The Knative `net-istio` is a KIngress controller for Istio. It's a full-feature service mesh that also functions as a Knative ingress. Good for enterprises already running Istio or needing advanced service mesh features. + +=== "Ingress Gateway" + + ```mermaid + --- + config: + layout: elk + theme: default + look: neo + --- + flowchart LR + Client["External Client"] --> CGW["Custom Ingress Gateway"] + CGW --> KIGW["Knative Ingress Gateway"] & Client + KIGW --> Revision["Knative Revision"] & CGW + Revision --> KIGW + ``` + + 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 [Configuring the Ingress gateway](setting-up-custom-ingress-gateway.md). + +=== "Gateway API" + + ```mermaid + --- + config: + layout: elk + theme: default + --- + flowchart LR + subgraph net-gateway-api["net-gateway-api controller"] + GW["Gateway"] + Route["Knative Route"] + HR["HTTPRoute"] + end + subgraph underlying["Underlying Controller
(Contour │ Istio │ Envoy Gateway │ …)"] + Controller["GatewayClass Controller"] + end + KSvc["Knative Service"] --> Route + Route -- translates to --> GW & HR + GW --> Controller + HR --> Controller + Controller -- routes traffic to --> Pods["Your Pods"] + + style net-gateway-api fill:#e3f2fd,stroke:#1976d2 + style underlying fill:#fff3e0,stroke:#ef6c00 + ``` + + The Knative `net-gateway-api` is a KIngress implementation and testing for Knative integration with the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). Good for teams adopting the Gateway API to unify ingress across Kubernetes. + + The Kubernetes Gateway API requires a controller or service mesh. Istio and Contour implementations are tested though other Gateway API implementations should work. Currently, there is no native Gateway API support for Kourier. For more information see [Tested Gateway API version and Ingress](https://github.com/knative-extensions/net-gateway-api/blob/main/docs/test-version.md). + + The controller that Knative uses is determined by which Gateway API-compatible controller you install and configure in your cluster. + +## Determine current state + +Use the following command to determine which ingress controllers are installed and their status. + + ``` bash + kubectl get pods -n knative-serving + ``` + +The Knative team tests the following ingress controllers: + +- 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. + +Each ingress controller manages only those ingress objects that are annotated with its key. Knative Serving uses a default value of the key based on the `network-config` ConfigMap. See [Changing the ingress controller](#change-the-controller) for important information about using this key. + +## Changing the controller + +If you want to change the controller, install and configure the new controller as instructed in the [Network layer options](#network-layer-options). There is no requirement to remove ingress controllers that are not in use. + +You can determine the controller in use by examining the `config-network.yaml`: + + ```bash + kubectl get cm config-network -n knative-serving -o yaml + ``` + +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 + ``` + +If you want to switch back to a previously installed controller, patch the `config-network` ConfigMap with the new controller. In the following example Kourier is used because of the dash in `ingress-class`. + + ```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"}]' + ```