Skip to content

Commit 67c120b

Browse files
jldohmannjldohmann
authored
Merge pull request #92976 from jldohmann/OSDOCS-13509
OSDOCS-13509: add assembly, topic map, and concept
2 parents 43656ab + 92e7b48 commit 67c120b

File tree

5 files changed

+219
-0
lines changed

5 files changed

+219
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1709,6 +1709,9 @@ Topics:
17091709
- Name: Allocating load balancers to specific subnets
17101710
File: allocating-load-balancers
17111711
Distros: openshift-enterprise,openshift-origin
1712+
- Name: Gateway API with OpenShift Container Platform networking
1713+
File: ingress-gateway-api
1714+
Distros: openshift-enterprise
17121715
# Kubernetes NMState (TECHNOLOGY PREVIEW)
17131716
- Name: Kubernetes NMState
17141717
Dir: k8s_nmstate

‎modules/nw-ingress-gateway-api-deployment-topologies.adoc

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
// Modules included in the following assemblies:
2+
//
3+
// * networking/gateway-api.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="nw-ingress-gateway-api-deployment_{context}"]
7+
= Gateway API deployment topologies
8+
9+
Gateway API is designed to accomodate two topologies: shared gateways or dedicated gateways. Each topology has its own advantages and different security implications.
10+
11+
Dedicated gateway:: Routes and any load balancers or proxies are served from the same namespace. The `Gateway`
12+
object restricts routes to a particular application namespace. This is the default topology when deploying a Gateway API resource in {product-title}.
13+
14+
Shared gateway:: Routes are served from multiple namespaces or with multiple hostnames. The `Gateway` object filters allow routes from application namespaces by using the `spec.listeners.allowedRoutes.namespaces` field.
15+
16+
[id="dedicated-gateway-example_{context}"]
17+
== Dedicated gateway example
18+
The following example shows a dedicated `Gateway` resource, `fin-gateway`:
19+
20+
.Example dedicated `Gateway` resource
21+
[source,yaml]
22+
----
23+
apiVersion: gateway.networking.k8s.io/v1
24+
kind: Gateway
25+
metadata:
26+
name: fin-gateway
27+
namespace: openshift-ingress
28+
spec:
29+
listeners: <1>
30+
- name: http
31+
protocol: HTTP
32+
port: 8080
33+
hostname: "example.com"
34+
----
35+
<1> Creating a `Gateway` resource without setting `spec.listeners[].allowedRoutes` results in implicitly setting the `namespaces.from` field to have the value `Same`.
36+
37+
The following example shows the associated `HTTPRoute` resource, `sales-db`, which attaches to the dedicated `Gateway` object:
38+
39+
.Example `HTTPRoute` resource
40+
[source,yaml]
41+
----
42+
apiVersion: gateway.networking.k8s.io/v1
43+
kind: HTTPRoute
44+
metadata:
45+
name: sales-db
46+
namespace: openshift-ingress
47+
spec:
48+
parentRefs:
49+
- name: fin-gateway
50+
hostnames:
51+
- sales-db.example.com
52+
rules:
53+
- backendRefs:
54+
- name: sales-db
55+
¦ port: 8080
56+
----
57+
58+
The `HTTPRoute` resource must have the name of the `Gateway` object 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.
59+
60+
[id="shared-gateway-example_{context}"]
61+
== Shared gateway example
62+
The following example shows a `Gateway` resource, `devops-gateway`, that has a `spec.listeners.allowedRoutes.namespaces` label selector set to match any namespaces containing `shared-gateway-access: "true"`:
63+
64+
.Example shared `Gateway` resource
65+
[source,yaml]
66+
----
67+
apiVersion: gateway.networking.k8s.io/v1
68+
kind: Gateway
69+
metadata:
70+
name: devops-gateway
71+
namespace: openshift-ingress
72+
listeners:
73+
- name: https
74+
protocol: HTTPS
75+
hostname: "example.com"
76+
allowedRoutes:
77+
namespaces:
78+
from: Selector
79+
selector:
80+
¦ matchLabels:
81+
¦ shared-gateway-access: "true"
82+
----
83+
84+
The following examples show the allowed namespaces for the `devops-gateway` resource:
85+
86+
.Example `Namespace` resources
87+
[source,yaml]
88+
----
89+
apiVersion: v1
90+
kind: Namespace
91+
metadata:
92+
name: dev
93+
labels:
94+
shared-gateway-access: "true"
95+
---
96+
apiVersion: v1
97+
kind: Namespace
98+
metadata:
99+
name: ops
100+
labels:
101+
shared-gateway-access: "true"
102+
----
103+
104+
In this example, two `HTTPRoute` resources, `dev-portal` and `ops-home`, are in different namespaces but are attached to the shared gateway:
105+
106+
[source,yaml]
107+
----
108+
apiVersion: v1
109+
kind: HTTPRoute
110+
metadata:
111+
name: dev-portal
112+
namespace: dev
113+
spec:
114+
parentRefs:
115+
- name: devops-gateway
116+
namespace: openshift-ingress
117+
rules:
118+
- backendRefs:
119+
- name: dev-portal
120+
port: 8080
121+
---
122+
apiVersion: v1
123+
kind: HTTPRoute
124+
metadata:
125+
name: ops-home
126+
namespace: ops
127+
spec:
128+
parentRefs:
129+
- name: devops-gateway
130+
namespace: openshift-ingress
131+
rules:
132+
- backendRefs:
133+
- name: ops-home
134+
port: 8080
135+
----
136+
137+
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 topology becomes conceptually similar to Ingress Controller sharding.
138+

‎modules/nw-ingress-gateway-api-implementation.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Modules included in the following assemblies:
2+
//
3+
// * networking/gateway-api.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="nw-ingress-gateway-api-implementation_{context}"]
7+
= Gateway API implementation for {product-title}
8+
9+
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.
10+
11+
In some situations, the Gateway API provides one or more fields that a 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 disrupted 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.
12+
13+
Any CRDs created within an {product-title} {product-version} cluster are compatibly versioned and maintained by the Ingress Operator. If CRDs are already present but were not previously managed by the Ingress Operator, the Ingress Operator checks whether these configurations are compatible with the Gateway API version supported by {product-title}, and creates an admin-gate that requires your acknowledgment of CRD succession.
14+
15+
[IMPORTANT]
16+
====
17+
If you are updating your cluster from a previous {product-title} version that contains Gateway API CRDs change those resources so that they exactly match the version supported by {product-title}. Otherwise, you cannot update your cluster because those CRDs were not managed by {product-title}, and could contain functionality that is unsupported by Red{nbsp}Hat.
18+
====
19+

‎modules/nw-ingress-gateway-api-overview.adoc

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Modules included in the following assemblies:
2+
//
3+
// * networking/gateway-api.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="nw-ingress-gateway-api-overview_{context}"]
7+
= Overview of the Gateway API
8+
9+
The Gateway API is an open source, community-managed, Kubernetes networking mechanism. It focuses on routing within the transport layer, L4, and the application layer, L7, for clusters. A variety of vendors offer many link:https://gateway-api.sigs.k8s.io/implementations/[implementations of Gateway API].
10+
11+
The project is an effort to provide a standardized 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.
12+
13+
The Gateway API extends the functionality of the Ingress Operator to handle more granular cluster traffic and routing configurations. With these capabilities, you can create instances of Gateway APIs custom resource definitions (CRDs). For {product-title} clusters, the Ingress Operator creates the following resources:
14+
15+
Gateway:: This resource describes how traffic can be translated to services within the cluster. For example, a specific load balancer configuration.
16+
GatewayClass:: This resource defines a set of `Gateway` objects that share a common configuration and behavior. For example, two separate `GatewayClass` objects might be created to distinguish a set of `Gateway` resources used for public or private applications.
17+
HTTPRoute:: This resource specifies the routing behavior of HTTP requests from a Gateway to a service, and is especially useful for multiplexing HTTP or terminated HTTPS connections.
18+
GRPCRoute:: This resource specifies the routing behavior of gRPC requests.
19+
ReferenceGrant:: This resource enables cross-namespace references. For example, it enables routes to forward traffic to backends that are in a different namespace.
20+
21+
In {product-title}, the implementation of the Gateway API is based on `gateway.networking.k8s.io/v1`, and all fields in this version are supported.
22+
23+
[id="gateway-api-benefits_{context}"]
24+
== Benefits of the Gateway API
25+
The Gateway API provides the following benefits:
26+
27+
* Portability: While {product-title} uses HAProxy to improve Ingress performance, Gateway API does not rely on vendor-specific annotations to provide certain behavior. To get comparable performance as HAProxy, the `Gateway` objects need to be horizontally scaled or their associated nodes need to be vertically scaled.
28+
* Separation of concerns: Gateway API uses a role-based approach to its resources, and more neatly fits into how a large organization structures its responsibilities and teams. 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.
29+
* Extensibility: Additional functionality is developed as a standardized CRD.
30+
31+
[id="gateway-api-limitations_{context}"]
32+
== Limitations of the Gateway API
33+
The Gateway API has the following limitations:
34+
35+
* 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.
36+
* 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.

‎networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="ingress-gateway-api"]
3+
= Gateway API with {product-title} Networking
4+
include::_attributes/common-attributes.adoc[]
5+
:context: ingress-gateway-api
6+
7+
toc::[]
8+
9+
{product-title} provides additional ways of configuring network traffic by using Gateway API with the Ingress Operator.
10+
11+
[IMPORTANT]
12+
====
13+
Gateway API does not support user-defined networks (UDN).
14+
====
15+
16+
include::modules/nw-ingress-gateway-api-overview.adoc[leveloffset=+1]
17+
18+
include::modules/nw-ingress-gateway-api-implementation.adoc[leveloffset=+1]
19+
20+
include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]
21+
22+
.Additional resources
23+
* xref:configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingress-sharding-concept_configuring-ingress-cluster-traffic-ingress-controller[Ingress Controller sharding].

0 commit comments

Comments
 (0)