-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Create Configure Knative Networking page #6518
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
Create file - table test
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Formatting test
More writing
Snippet testing
snippet testing
Snippet name fix
Formatting tests
Formatting fix
Formmating
Typo fix
Formatting
Updates
Snippet formatting
Misc edits
Link issue fix
Minor edit to rebuild
Mermaid fixes
Mermaid adjustments
|
|
||
| # 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. |
There was a problem hiding this comment.
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) |
There was a problem hiding this comment.
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
tab test again
Formatting tasks
evankanderson
left a comment
There was a problem hiding this 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.
| 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/ | ||
| ``` |
There was a problem hiding this comment.
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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: |
| labels: | ||
| app.kubernetes.io/component: net-gateway-api | ||
| app.kubernetes.io/name: knative-serving |
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
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"] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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"] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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" %} |
There was a problem hiding this comment.
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:
| {% include "netadapter-kourier.md" %} | |
| {% filter indent(width=4) %} | |
| {% include "netadapter-kourier.md" %} | |
| {% endfilter %} |
Misc fixes and edits
testing...
| {% filter indent(width=4) %} | ||
| {% include "netadapter-kourier.md" %} | ||
| {% include "netadapter-contour.md" %} | ||
| {% include "netadapter-istio.md" %} | ||
| {% include "netadapter-gatewayapi.md" %} | ||
| {% endfilter %} |
There was a problem hiding this comment.
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.
| {% include "netadapter-kourier.md" %} | ||
| {% filter indent(width=4) %} | ||
| {% include "netadapter-contour.md" %} | ||
| {% include "netadapter-istio.md" %} | ||
| {% include "netadapter-gatewayapi.md" %} | ||
| {% endfilter %} |
There was a problem hiding this comment.
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...
There was a problem hiding this comment.
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!
Indentation formatting, wordsmithing
minor edit to rebuld
Misc edits
minor edit
Edit to rebuild
Steps rearrangement
evankanderson
left a comment
There was a problem hiding this 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:
-
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. -
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.
-
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. |
There was a problem hiding this comment.
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).
| 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 |
There was a problem hiding this comment.
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.devIngress 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: |
There was a problem hiding this comment.
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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"] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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).
| envoy["Envoy deployment<br>kourier-system namespace"] | ||
| kourier["net-kourier<br>controller"] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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. |
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
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