Skip to content

OSDOCS-13509: add assembly, topic map, and concept #92976

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

OSDOCS-13509: add assembly, topic map, and concept #92976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1705,6 +1705,9 @@ Topics:
- Name: Allocating load balancers to specific subnets
File: allocating-load-balancers
Distros: openshift-enterprise,openshift-origin
- Name: Gateway API with OpenShift Container Platform Networking
File: ingress-gateway-api
Distros: openshift-enterprise
# Kubernetes NMState (TECHNOLOGY PREVIEW)
- Name: Kubernetes NMState
Dir: k8s_nmstate
Expand Down
135 changes: 135 additions & 0 deletions modules/nw-ingress-gateway-api-deployment-topologies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
// Modules included in the following assemblies:
//
// * networking/gateway-api.adoc

:_mod-docs-content-type: CONCEPT
[id="nw-ingress-gateway-api-deployment_{context}"]
= Gateway API Deployment topologies

Gateway API is designed to accomodate two topologies: shared gateways or dedicated gateways. Each topology has their own advantages and as well as different security implications.

Dedicated gateway:: Routes and any load balancers or proxies are served from the same namespace. The `Gateway`
object restricts routes to a particular application namespace. This is the default topology for Gateway API in {product-title}.

Shared gateway:: Routes are served from multiple namespaces or with multiple hostnames. The `Gateway` object filters allow routes from application namespaces using the `spec.listeners.allowedRoutes.namespaces` field.

[id="dedicated-gateway-example_{context}"]
== Dedicated gateway example
An example of a `Gateway` resource, `fin-gateway`:

.Example dedicated `Gateway` resource
[source,yaml]
----
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: fin-gateway
namespace: openshift-ingress
spec:
listeners:
- name: http
protocol: HTTP
port: 8080
hostname: "example.com"
----

An example of the associated `HTTPRoute` resource, `sales-db`, that attaches to the dedicated `Gateway` object:

.Example `HTTPRoute` resource
[source,yaml]
----
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: sales-db
namespace: openshift-ingress
spec:
parentRefs:
- name: fin-gateway
rules:
- backendRefs:
- name: sales-db
¦ port: 8080
Copy link
Contributor

Choose a reason for hiding this comment

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

What ¦ is for?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

seems to be an indentation artifact when editing yaml, it doesn't show up in the published version though

Copy link
Contributor

Choose a reason for hiding this comment

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

I can see it in the preview:
image

Copy link
Contributor

Choose a reason for hiding this comment

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

And here too:
image

Copy link
Contributor Author

Choose a reason for hiding this comment

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

it is present in the preview yeah

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 preview is not really reflective style-wise to the d.r.c. published documentation. even with d.o.c, the preview contained some artifacts that get stripped out during the publishing process

----

The `HTTPRoute` resource must have the `Gateway` object's name as the value for its `parentRefs` field in order to attach to the gateway. Implicitly, the route is assumed to be in the same namespace as the `Gateway` object.

[id="shared-gateway-example_{context}"]
== Shared gateway example
An example of a `Gateway` resource, `devops-gateway`, that has a label selector `spec.listeners.allowedRoutes.namespaces` set to match any namespaces containing `shared-gateway-access: "true"`:

.Example shared `Gateway` resource
[source,yaml]
----
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: devops-gateway
namespace: openshift-ingress
listeners:
- name: https
protocol: HTTPS
hostname: "example.com"
allowedRoutes:
namespaces:
from: Selector
selector:
¦ matchLabels:
¦ shared-gateway-access: "true"
----

Examples of the allowed namespaces for the `devops-gateway` resource:

.Example `Namespace` resources
[source,yaml]
----
apiVersion: v1
kind: Namespace
metadata:
name: dev
labels:
shared-gateway-access: "true"
---
apiVersion: v1
kind: Namespace
metadata:
name: ops
labels:
shared-gateway-access: "true"
----

An example of two `HTTPRoute` resources, `dev-portal` and `ops-home`, that sit in different namespaces but are attached to the shared gateway:

[source,yaml]
----
apiVersion: v1
kind: HTTPRoute
metadata:
name: dev-portal
namespace: dev
spec:
parentRefs:
- name: devops-gateway
namespace: openshift-ingress
rules:
- backendRefs:
- name: dev-portal
port: 8080
---
apiVersion: v1
kind: HTTPRoute
metadata:
name: ops-home
namespace: ops
spec:
parentRefs:
- name: devops-gateway
namespace: openshift-ingress
rules:
- backendRefs:
- name: ops-home
port: 8080
----

With a shared gateway topology, the routes must specify the namespace of the `Gateway` object it wants to attach to. Multiple `Gateway` objects can be deployed and shared across namespaces. When there are multiple shared gateways this becomes conceptually similar to Ingress Controller sharding.

19 changes: 19 additions & 0 deletions modules/nw-ingress-gateway-api-implementation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
// Modules included in the following assemblies:
//
// * networking/gateway-api.adoc

:_mod-docs-content-type: CONCEPT
[id="nw-ingress-gateway-api-implementation_{context}"]
= {product-title}'s Gateway API implementation
Comment on lines +6 to +7
Copy link
Contributor

Choose a reason for hiding this comment

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

This chapter only mentions the CRD management part of the implementation. Do we want to hightlight the fact that OSSM (OpenShift Service Mesh) operator will be installed behind the scene? And how to trigger this installation (GatewayClass example)?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

its a good question, i wonder that myself. @ahardin-rh what do you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

i remember @Miciah mentioned here that maybe we don't want to do that. has this changed?


The Ingress Operator manages the lifecycle of Gateway API CRDs in a way that enables other vendor implementations to make use of CRDs defined in an {product-title} cluster.

In some situations, the Gateway API provides one or more fields that an given vendor implementation does not support, but that implementation is otherwise compatible in schema with the rest of the fields. These "dead fields" can result in disruption of Ingress workloads, improperly provisioned applications and services, and security related issues. Because {product-title} uses a specific version of Gateway API CRDs, any use of third-party implementations of Gateway API must conform to the {product-title} implementation to ensure that all fields work as expected.

Any CRDs created within an {product-title} {product-version} cluster will be compatibly versioned and maintained by the Ingress Operator. In the case that CRDs are already present but were not previously managed by the Ingress Operator, the Ingress Operator will check if these configurations are compatible with the Gateway API version supported by {product-title}, and create an admin-gate that requires your acknowledgment of CRD succession.

[IMPORTANT]
====
If you are updating your cluster from a previous {product-title} version that contains Gateway API CRDs, you must make changes to these resources such that it exactly matches the version supported by {product-title}. Otherwise, you will not be able to update your cluster. This is because those CRDs were not managed by {product-title}, and could contain functionality that is unsupported by Red{nbsp}Hat.
====

36 changes: 36 additions & 0 deletions modules/nw-ingress-gateway-api-overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
// Modules included in the following assemblies:
//
// * networking/gateway-api.adoc

:_mod-docs-content-type: CONCEPT
[id="nw-ingress-gateway-api-overview_{context}"]
= Overview of the Gateway API

The Gateway API is an open source, community-managed, Kubernetes networking mechanism that focuses on routing within the transport layer, L4, and the application layer, L7, for clusters. There are many implementations of Gateway API by a link:https://gateway-api.sigs.k8s.io/implementations/[variety of vendors].

The project is an effort to provide a standardized, vender-neutral, ecosystem by using a portable API with broad community support. By integrating Gateway API functionality into the Ingress Operator, it enables a networking solution that aligns with existing community and upstream development efforts.

The Gateway API extends the functionality of the Ingress Operator to handle more granular cluster traffic and routing configurations. These capabilities let you create instances of Gateway APIs custom resource definitions (CRDs). For {product-title} clusters, these resources include:

GatewayClass:: This resource defines a set of Gateways that share a common configuration and behavior. For example, two separate GatewayClasses might be created to distinguish Gateways used for public or private applications.
Gateway:: This resource describes how traffic can be translated to services within the cluster. For example, a specific load balancer configuration.
HTTPRoute:: This resource specifies routing behavior of HTTP requests from a Gateway to a service, and is especially useful for multiplexing HTTP or terminated HTTPS connections.
GRPCRoute:: This resource specific routing behavior of gRPC requests and is created by the Ingress Operator for the cluster.
ReferenceGrant:: This resource enables cross-namespace references. For example, it lets routes forward traffic to backends located in a different namespace. This resource is created by the Ingress Operator for the cluster.

Copy link
Contributor

Choose a reason for hiding this comment

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

There is also GRPCRoute and ReferenceGrant which the cluster ingress operator creates in the cluster.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

thanks, ive updated the definition list to include these

Copy link
Contributor

Choose a reason for hiding this comment

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

This resource is created by the Ingress Operator for the cluster.

All of these CRDs are created by the ingress operator. I don't know whether it's worth mentioning this for some (or maybe even for all of them). It seems to me that the idea here is to present what the CRD is for.

{product-title}'s implementation of the Gateway API is based on `gateway.networking.k8s.io/v1` and all fields in this version are supported.

[id="gateway-api-benefits_{context}"]
== Benefits of the Gateway API
The Gateway API provides the following benefits:

* Portability: While {product-title} uses HAProxy to improve Ingress performance, Gateway API does not rely on vendor-specific annotations to provide certain behavior.
* Separation of concerns: Gateway API uses a role-based approach to its resources, and more neatly fits into how a large organization has their responsibilities and teams structured. Platform engineers might focus on `GatewayClass` resources, cluster admins might focus on configuring `Gateway` resources, and application developers might focus on routing their services with `HTTPRoute` resources.
* Extensibility: Additional functionality is developed as a standardized CRD.

[id="gateway-api-limitations_{context}"]
== Limitations of the Gateway API
The Gateway API has the following limitations:

* Version incompatibilites: The Gateway API ecosystem changes rapidly, and some implementations do not work with others because their featureset is based on differing versions of Gateway API.
* Resource overhead: While more flexible, Gateway API uses multiple resource types to achieve an outcome. For smaller applications, the simplicity of traditional Ingress might be a better fit.
23 changes: 23 additions & 0 deletions networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
:_mod-docs-content-type: ASSEMBLY
[id="ingress-gateway-api"]
= Gateway API with {product-title} Networking
include::_attributes/common-attributes.adoc[]
:context: ingress-gateway-api

toc::[]

{product-title} provides additional ways of configuring network traffic using Gateway API with the Ingress Operator.

[IMPORTANT]
====
Gateway API does not support user-defined networks (UDN).
====

include::modules/nw-ingress-gateway-api-overview.adoc[leveloffset=+1]

include::modules/nw-ingress-gateway-api-implementation.adoc[leveloffset=+1]

include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]

.Additional resources
xref:configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingress-sharding-concept_configuring-ingress-cluster-traffic-ingress-controller[Ingress Controller sharding].