Skip to content

Commit c6262ef

Browse files
jldohmannjldohmann
committed
OSDOCS-13509: add assembly, topic map, and concept
1 parent 467a51a commit c6262ef

File tree

4 files changed

+206
-0
lines changed

4 files changed

+206
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1672,6 +1672,9 @@ Topics:
16721672
- Name: Patching existing ingress objects
16731673
File: configuring-ingress-cluster-patch-fields
16741674
Distros: openshift-enterprise,openshift-origin
1675+
- Name: Gateway API with OpenShift Container Platform Networking
1676+
File: ingress-gateway-api
1677+
Distros: openshift-enterprise
16751678
# Kubernetes NMState (TECHNOLOGY PREVIEW)
16761679
- Name: Kubernetes NMState
16771680
Dir: k8s_nmstate

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

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
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+
= {product-title}'s Gateway API implementation
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 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.
12+
13+
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.
14+
15+
[IMPORTANT]
16+
====
17+
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.
18+
====
19+
20+
[id="nw-ingress-gateway-api-deployment_{context}"]
21+
== Deployment topologies
22+
23+
Gateway API is designed to accomodate two topologies: shared gateways or dedicated gateways. Each topology hastheir advantages and comes with different security implications.
24+
25+
Dedicated gateway:: routes and any load balancers or proxies are served from the same namespace. The `Gateway`
26+
object restricts routes to a particular application namespace. This is the default topology for Gateway API in {product-title}.
27+
28+
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.
29+
30+
[id="dedicated-gateway-example_{context}"]
31+
=== Dedicated gateway example
32+
An example of a `Gateway` resource, `fin-gateway`:
33+
+
34+
.Example dedicated `Gateway` resource
35+
[source,yaml]
36+
----
37+
apiVersion: gateway.networking.k8s.io/v1
38+
kind: Gateway
39+
metadata:
40+
name: fin-gateway
41+
namespace: openshift-ingress
42+
spec:
43+
listeners:
44+
- name: http
45+
protocol: HTTP
46+
port: 8080
47+
----
48+
49+
An example of the associated `HTTPRoute` resource, `sales-db`, that attaches to the dedicated `Gateway` object:
50+
+
51+
.Example `HTTPRoute` resource
52+
[source,yaml]
53+
----
54+
apiVersion: gateway.networking.k8s.io/v1
55+
kind: HTTPRoute
56+
metadata:
57+
name: sales-db
58+
namespace: openshift-ingress
59+
spec:
60+
parentRefs:
61+
- name: fin-gateway
62+
rules:
63+
- backendRefs:
64+
- name: sales-db
65+
port: 8080
66+
----
67+
68+
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.
69+
70+
[id="shared-gateway-example_{context}"]
71+
=== Shared gateway example
72+
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"`:
73+
+
74+
.Example shared `Gateway` resource
75+
[source,yaml]
76+
----
77+
apiVersion: gateway.networking.k8s.io/v1
78+
kind: Gateway
79+
metadata:
80+
name: devops-gateway
81+
namespace: openshift-ingress
82+
listeners:
83+
- name: https
84+
protocol: HTTPS
85+
hostname: "example.com"
86+
allowedRoutes:
87+
namespaces:
88+
from: Selector
89+
selector:
90+
matchLabels:
91+
shared-gateway-access: "true"
92+
tls:
93+
certificateRefs:
94+
- name: example-com
95+
----
96+
97+
Examples of the allowed namespaces for the `devops-gateway` resource:
98+
+
99+
.Example `Namespace` resources
100+
[source,yaml]
101+
----
102+
apiVersion: v1
103+
kind: Namespace
104+
metadata:
105+
name: dev
106+
labels:
107+
shared-gateway-access: "true"
108+
---
109+
apiVersion: v1
110+
kind: Namespace
111+
metadata:
112+
name: ops
113+
labels:
114+
shared-gateway-access: "true"
115+
----
116+
117+
An example of two `HTTPRoute` resources, `dev-portal` and `ops-home`, that sit in different namespaces but are attached to the shared gateway:
118+
+
119+
[source,yaml]
120+
----
121+
apiVersion: v1
122+
kind: HTTPRoute
123+
metadata:
124+
name: dev-portal
125+
namespace: dev
126+
spec:
127+
parentRefs:
128+
- name: devops-gateway
129+
namespace: openshift-ingress-operator
130+
rules:
131+
- backendRefs:
132+
- name: dev-portal
133+
port: 8080
134+
---
135+
apiVersion: v1
136+
kind: HTTPRoute
137+
metadata:
138+
name: ops-home
139+
namespace: ops
140+
spec:
141+
parentRefs:
142+
- name: devops-gateway
143+
namespace: openshift-ingress-operator
144+
rules:
145+
- backendRefs:
146+
- name: ops-home
147+
port: 8080
148+
----
149+
150+
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 xref:../networking/configuring-ingress-cluster-traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingress-sharding-concept[Ingress Controller sharding].
151+

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
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 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].
10+
11+
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.
12+
13+
The Gateway API extends the functionality of the Ingress Operator to handle more granular cluster traffic and routing configurations. These capabilities let you define custom resource definitions (CRDs) using one of Gateway APIs resources. For {product-title} clusters, these resources include:
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 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.
17+
HTTPRoute:: This resource specifies routing behavior of of HTTP requests from a Gateway to a service, and is especially useful for multiplexing HTTP or terminated HTTPS connections.
18+
19+
{product-title}'s implementation of the Gateway API is based on `gateway.networking.k8s.io/v1` and all fields in this version are supported.
20+
21+
[id="gateway-api-benefits_{context}"]
22+
== Benefits of the Gateway API
23+
The Gateway API provides the following benefits:
24+
25+
* Portability: While {product-title} uses HAProxy to improve Ingress performance, Gateway API does not rely on vendor-specific annotations to provide certain behavior.
26+
* 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.
27+
* Extensibility: Additional functionality is developed as a standardized CRD.
28+
29+
[id="gateway-api-limitations_{context}"]
30+
== Limitations of the Gateway API
31+
The Gateway API has the following limitations:
32+
33+
* 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.
34+
* 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: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
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 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]

0 commit comments

Comments
 (0)