Skip to content

Conversation

@iRaindrop
Copy link
Contributor

The content for the Kourier, Contour, Gateway API, and Istio is could be helpful consolidated as opposed to separate install and config topics.

Proposed Changes

  • Create "Configure network adapters" under "Administration->Configuring Knative->Networking options

Create file - table test
@netlify
Copy link

netlify bot commented Nov 19, 2025

Deploy Preview for knative ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit 1a4ba6c
🔍 Latest deploy log https://app.netlify.com/projects/knative/deploys/69609be6d6f87a0008a552d7
😎 Deploy Preview https://deploy-preview-6518--knative.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@knative-prow knative-prow bot requested review from mmejia02 and nainaz November 19, 2025 05:58
@knative-prow knative-prow bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Nov 19, 2025
@iRaindrop iRaindrop marked this pull request as draft November 19, 2025 05:59
@knative-prow knative-prow bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 19, 2025
@knative-prow knative-prow bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Nov 19, 2025
@knative-prow knative-prow bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 22, 2025
Snippet formatting
Misc edits
Added tabs for Network layer setup
Minor edit to rebuild

# Configure Knative networking

This page provides configuration guidance for Knative Serving's integration with Kubernetes ingress controllers. Knative leverages existing ingress controls in your Kubernetes cluster, allowing you to use the same monitoring features and capabilities.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added "features and capabilities" at end of sentence.


The Knative `networking.internal.knative.dev` Ingress type is generally referred to as KIngress objects.

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)
Copy link
Contributor Author

@iRaindrop iRaindrop Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI - I added this link to the custom ingress class (new).

Also name change to "Configure Istio's ingress gateway"
And tab test with snippet references
tabs with snippet references fix
Formatting tasks
Copy link
Member

@evankanderson evankanderson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the tab thing - it looks like you'll probably want to use the following format to indent the tabs:

{% filter indent(width=4) %}
{% include "netadapter-foo.md" %}
{% endfilter %}

The other edits are fairly confined, I think, with the possible exception of the gatewayclass discussion at the end of "configuring network adapters", which needs to be clarified that it only applies to Gateway API.

Comment on lines 3 to 21
1. Clone the Gateway API repo:

```bash
git clone https://github.com/knative-extensions/net-gateway-api.git
cd net-gateway-api
```

1. Set environment variables:

```bash
export KO_DOCKER_REPO=kind.local
export KIND_CLUSTER_NAME=knative # (keep this if your cluster is named "knative")
```

1. Deploy Gateway API resources:

```bash
ko apply -f config/
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't need these if people are installing the release version (which they should).

--patch '{"data":{"ingress-class":"gateway-api.ingress.networking.knative.dev"}}'
```

1. Edit the `config-gateway` ConfigMap in the knative-serving namespace to specify gateway resources for external and local traffic. For the `external-gateways` key, specify the value for `name` and for `service` as needed. Do the same for the `local gateways`. The `namespace` should be kept at `knative-serving`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Edit the `config-gateway` ConfigMap in the knative-serving namespace to specify gateway resources for external and local traffic. For the `external-gateways` key, specify the value for `name` and for `service` as needed. Do the same for the `local gateways`. The `namespace` should be kept at `knative-serving`.
1. Create Gateway resources for use by external ("north-south") Knative traffic, and local ("east-west") 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. Note both the Kubernetes namespace and name of the Gateways, and an underlying DNS name (such as a Kubernetes service DNS name) corresponding to the Gateway, which will be used by Knative to verify traffic routing.
1. Edit the `config-gateway` ConfigMap in the `knative-serving` namespace to specify the Gateway resources for external and local traffic. For the `external-gateways` key, specify the values for `name`, `namespace` and for `service` corresponding to the external Gateway resource. Do the same for the `local-gateways` key:

Comment on lines 47 to 49
labels:
app.kubernetes.io/component: net-gateway-api
app.kubernetes.io/name: knative-serving
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't need these labels on the ConfigMap.

Suggested change
labels:
app.kubernetes.io/component: net-gateway-api
app.kubernetes.io/name: knative-serving

ExtGateway -- Routes external HTTP/HTTPS traffic --> KServe
IntGateway -- Routes internal traffic --> KServe
ExternalClient["External Client<br>Internet / Outside cluster"] -- Ingress --> ExtGateway
InternalClient["Internal Client<br>Pod / Service inside cluster"] -- "Cluster-internal" --> IntGateway
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"InternalClient" needs to be in the "Knative Cluster" subgraph.

layout: elk
---
flowchart LR
subgraph Cluster["Knative Cluster"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
subgraph Cluster["Knative Cluster"]
subgraph Cluster["Kubernetes Cluster"]

direction TB
ExtGateway["External Gateway<br>Exposed to external traffic"]
IntGateway["Internal Gateway<br>Only for local internal traffic"]
KServe["Knative Services<br>Serving and Eventing"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
KServe["Knative Services<br>Serving and Eventing"]
KServe["Knative Services"]

This is all Serving. Unfortunately, Eventing has a somewhat different model and doesn't have clear abstractions for exposing the event ingress from outside the cluster.

istio-remote istio.io/unmanaged-gateway True 11d
```

When gateways are installed, the `config-gateway` ConfigMap is updated to track the `class`, `gateway`, and `service`. The service is the Kubernetes Service name that points to the pods in the Gateway implementation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't happen automatically -- this needs to be done by a cluster administrator when they want to change the Gateways used by a certain type of traffic. There's one extra layer here which I didn't describe previously (because it's Gateway-API general, rather than Knative-specific):

NAME      CONTROLLER                                      ACCEPTED   AGE
cilium    io.cilium/gateway-controller                    True       134d
default   gateway.envoyproxy.io/gatewayclass-controller   True       127d

$ kubectl get gateway --context prod --all-namespaces
NAMESPACE              NAME     CLASS     ADDRESS          PROGRAMMED   AGE
envoy-gateway-system   shared   default   100.100.100.100   True         127d

So specific Gateways (which go in config-network) will reference a GatewayClass, which says which implementation that Gateway should use. But it may make more sense to simply have people list the Gateway objects in their cluster, and ignore the GatewayClass in this document.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Edit the config-gateway ConfigMap" step in netadapter-gateway.api (in the installation instructions) show editing the YAML for the external and internal clusters. Does that step suffice? Should it be repeated here?

Save this to use in the following [Configure DNS](#configure-dns) section.
=== "Kourier"

{% include "netadapter-kourier.md" %}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did a little more digging, and it looks like we can use the indent jinja2 filter here to avoid needing to indent the contents of each netadapter-* file:

Suggested change
{% include "netadapter-kourier.md" %}
{% filter indent(width=4) %}
{% include "netadapter-kourier.md" %}
{% endfilter %}

Comment on lines 46 to 51
{% filter indent(width=4) %}
{% include "netadapter-kourier.md" %}
{% include "netadapter-contour.md" %}
{% include "netadapter-istio.md" %}
{% include "netadapter-gatewayapi.md" %}
{% endfilter %}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't need (or want) {% filter indent(width=4) %} if you're going to put the tab headers in the included documents. A 4-space indent (absent other context) in Markdown is going to mean "preformatted text", which is what we see in the render.

Comment on lines 46 to 51
{% include "netadapter-kourier.md" %}
{% filter indent(width=4) %}
{% include "netadapter-contour.md" %}
{% include "netadapter-istio.md" %}
{% include "netadapter-gatewayapi.md" %}
{% endfilter %}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't want to include the {% filter indent(width=4) %} directive if you're putting the tab headers into the included documents. Absent other context, a 4-space indent means "preformatted text" in markdown, which is what you get in the render. So, either:

=== Kourier
{% filter indent(width=4) %}
{% include "netadapter-kourier.md" %}
{% endfilter %}

with no indent in the netadapter-kourier.md file, OR:

{% include "netadapter-kourier.md" %}

Where the included file looks like:

=== Kourier

    Some words about kourier...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I've been trying the right combo. But not this yet:
=== Kourier
{% filter indent(width=4) %}
{% include "netadapter-kourier.md" %}
{% endfilter %}

Fingers crossed!

Copy link
Member

@evankanderson evankanderson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A small number of comments left:

  1. We should move the introduction of KIngress to the top of the configuring networking page, and use that to extract the common [Route] -> (controller) -> [KIngress] diagram.

  2. A few details on Gateway API implementation that were missing -- a link to how to configure request handling with Gateway API, and how to tell that Gateway API is present.

  3. A couple other spots where clarification might be needed.

kubectl apply -f {{ artifact(repo="net-gateway-api",org="knative-extensions",file="net-gateway-api.yaml") }}
```

Alternatively, you can also install a preconfigured Gateways for either Contour or Istio. Replace the filename in this step with either `contour-gateway.yaml` or `istio-gateway.yaml`. If you use either file you can skip the next step to configure gateway resources.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The contour-gateway.yaml and istio-gateway.yaml don't replace the net-gateway-api.yaml file, but they replace steps 2 and 3. Not sure how to make that clearer here, but right now, it reads as if you can just install those files instead of the net-gateway-api.yaml (which won't produce a working system, but the commands will succeed).

Comment on lines 38 to 49
flowchart LR
subgraph top[" "]
direction LR
kingress1["Ingress object (KIngress)<br>networking.internal.knative.dev"]
serving["Serving<br>controller"]
route["Route object"]
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving this content out of each tab still needs to happen. I'd suggest moving the diagram up to the first section (maybe around line 11), and also moving line 222 explaining what a KIngress is up to that area. I'd probably also include an explanation of why the type exists:

The Knative networking.internal.knative.dev Ingress type is generally referred to as KIngress objects. Knative uses the KIngress type to provide a common interface across multiple ingress implementations.

(bold added)

I'd also use this diagram, which includes the Knative Route object to make it clear what user-visible resource maps to the "hidden" KIngress resource:

    ```mermaid
    ---
    config:
      layout: elk
      theme: default
    ---
    flowchart LR
      subgraph top[" "]
        direction LR
            kingress1["Ingress object (KIngress)<br>networking.internal.knative.dev"]
            serving("Serving<br>controller")
            route["Route object<br>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
    ```


Kourier is is the only supported option for IBM-Z and IBM-P platforms. These IBM platforms require additional steps as documented in [Install Serving th 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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


The Knative `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 requires a controller or service mesh. Istio and Contour 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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Kubernetes Gateway API requires a controller or service mesh. Istio and Contour 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).
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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Service meshes and controllers are different types of things. It would be like saying "gardens need fruit or paths". Let's call them implementations, and include envoy-gateway.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also suggested another sentence here covering how options were configured, to match the other tabs. In this case, I'd probably say:

Knative is designed to support attaching Gateway API policies to both Knative-created HTTPRoutes and the existing Gateway resources which manage with those routes.

theme: default
---
flowchart LR
net-gateway["net-gateway-api controller"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
net-gateway["net-gateway-api controller"]
net-gateway("net-gateway-api<br>controller")

Let's narrow this text so we can get slightly bigger font here. Also, let's use rounded-boxes for software components like controllers, and square boxes for Kubernetes resources (objects).

Comment on lines +51 to +52
envoy["Envoy deployment<br>kourier-system namespace"]
kourier["net-kourier<br>controller"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
envoy["Envoy deployment<br>kourier-system namespace"]
kourier["net-kourier<br>controller"]
envoy("Envoy deployment<br>kourier-system namespace")
kourier("net-kourier<br>controller")

Let's use rounded-boxes for software components.


- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, I think I had a comment here, but Gateway API will create net-gateway-api-* pods in the knative-serving namespace, which can be used to recognize that Gateway API KIngress class is available. (The same as the other directions.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you did - thanks for catching it


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is all Gateway-API specific. I don't know if you want to create a parallel page with "Configure Istio's ingress gateway" (e.g. "Configure Gateway API's ingress gateway"), or if you just want to add a clarification banner here that the following section only applies to Gateway API.

Copy link
Contributor Author

@iRaindrop iRaindrop Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your call, I can create a new page - would it need additional content? Added the clarification for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants