Create Configure Knative Networking page

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,4 @@ 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.
-
-        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 [`minikube tunnel`](https://minikube.sigs.k8s.io/docs/commands/tunnel/) is running, and should consider using the "Real DNS" or "No DNS" tabs.

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
+    ```

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
+    ```

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
+    ```

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
+    ```

docs/snippets/no-dns.md

@@ -1,7 +1,3 @@
-<!-- Referenced by:
-- 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,

docs/versioned/.nav.yml

@@ -266,6 +266,7 @@ nav:
         - Working with ConfigMaps: admin/editing-configmaps.md
         - Configure high-availability components: serving/config-ha.md
         - Exclude namespaces from the Knative webhook: serving/webhook-customizations.md
+        - Configure Knative networking: serving/config-network-adapters.md
         - Networking Options:
           - Configure the ingress gateway: serving/setting-up-custom-ingress-gateway.md
           - Configure domain names: serving/using-a-custom-domain.md

docs/versioned/serving/config-network-adapters.md

@@ -0,0 +1,189 @@
+---
+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"
+
+    ```mermaid
+    ---
+    config:
+      theme: default
+      layout: elk
+      look: neo
+    ---
+    flowchart LR
+    K1["Knative<br>net-kourier"] -- creates --> K2["KIngress&nbsp;objects"]
+    K2 --> K3["Class: kourier.ingress.networking.knative.dev"]
+    ```
+
+    The Kourier ingress controller, `net-kourier`, is installed with Knative Serving. 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).
+
+    **Install and configure Kourier**
+
+    --8<-- "netadapter-kourier.md"
+
+=== "Contour"
+
+    ```mermaid
+    ---
+    config:
+      theme: default
+      layout: elk
+      look: neo
+    ---
+    flowchart LR
+    C1["Knative<br>net-contour"] -- creates --> C2["KIngress&nbsp;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.
+
+    **Install and configure Contour**
+
+    --8<-- "netadapter-contour.md"
+
+=== "Istio"
+
+    ```mermaid
+    ---
+    config:
+      theme: default
+      layout: elk
+    ---
+    flowchart LR
+        I1["Knative&nbsp;net-istio"] -- creates --> I2["Service + Gateway"]
+        I2 --> I3["Class: istio.ingress.networking.knative.dev<br>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.
+
+    **Install and configure Istio**
+
+    --8<-- "netadapter-istio.md"
+
+=== "Ingress Gateway"
+
+    ```mermaid
+    ---
+    config:
+      layout: elk
+      theme: default
+      look: neo
+    ---
+    flowchart LR
+        Client["External&nbsp;Client"] --> CGW["Custom&nbsp;Ingress&nbsp;Gateway"]
+        CGW --> KIGW["Knative&nbsp;Ingress&nbsp;Gateway"] & Client
+        KIGW --> Revision["Knative&nbsp;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.
+
+    **Install and configure Ingress Gateway**
+
+    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&nbsp;controller"]
+            GW["Gateway"]
+            Route["Knative&nbsp;Route"]
+            HR["HTTPRoute"]
+      end
+     subgraph underlying["Underlying&nbsp;Controller<br>(Contour │ Istio │ Envoy Gateway │ …)"]
+        Controller["GatewayClass&nbsp;Controller"]
+      end
+        KSvc["Knative&nbsp;Service"] --> Route
+        Route -- translates&nbsp;to --> GW & HR
+        GW --> Controller
+        HR --> Controller
+        Controller -- routes&nbsp;traffic&nbsp;to --> Pods["Your&nbsp;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. 
+
+    **Install and configure Gateway API**
+
+    --8<-- "netadapter-gatewayapi.md"
+
+## 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.
+
+## Configure DNS
+
+--8<-- "dns.md"
+--8<-- "real-dns-yaml.md"
+--8<-- "no-dns.md"
+
+## 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
+ubectl patch configmap config-network -n knative-serving \                                                    
+  --type=json -p='[{"op": "remove", "path": "/data/ingress.class"}]'
+```