Skip to content

Commit 506f6a6

Browse files
jldohmannjldohmann
committed
OSDOCS-13509: add assembly, topic map, and concept
1 parent 339835a commit 506f6a6

File tree

5 files changed

+216
-0
lines changed

5 files changed

+216
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1705,6 +1705,9 @@ Topics:
17051705
- Name: Allocating load balancers to specific subnets
17061706
File: allocating-load-balancers
17071707
Distros: openshift-enterprise,openshift-origin
1708+
- Name: Gateway API with OpenShift Container Platform Networking
1709+
File: ingress-gateway-api
1710+
Distros: openshift-enterprise
17081711
# Kubernetes NMState (TECHNOLOGY PREVIEW)
17091712
- Name: Kubernetes NMState
17101713
Dir: k8s_nmstate

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
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 their own advantages and as well as 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 for Gateway API 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 using the `spec.listeners.allowedRoutes.namespaces` field.
15+
16+
[id="dedicated-gateway-example_{context}"]
17+
== Dedicated gateway example
18+
An example of a `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:
30+
- name: http
31+
protocol: HTTP
32+
port: 8080
33+
hostname: "example.com"
34+
----
35+
36+
An example of the associated `HTTPRoute` resource, `sales-db`, that attaches to the dedicated `Gateway` object:
37+
38+
.Example `HTTPRoute` resource
39+
[source,yaml]
40+
----
41+
apiVersion: gateway.networking.k8s.io/v1
42+
kind: HTTPRoute
43+
metadata:
44+
name: sales-db
45+
namespace: openshift-ingress
46+
spec:
47+
parentRefs:
48+
- name: fin-gateway
49+
rules:
50+
- backendRefs:
51+
- name: sales-db
52+
¦ port: 8080
53+
----
54+
55+
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.
56+
57+
[id="shared-gateway-example_{context}"]
58+
== Shared gateway example
59+
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"`:
60+
61+
.Example shared `Gateway` resource
62+
[source,yaml]
63+
----
64+
apiVersion: gateway.networking.k8s.io/v1
65+
kind: Gateway
66+
metadata:
67+
name: devops-gateway
68+
namespace: openshift-ingress
69+
listeners:
70+
- name: https
71+
protocol: HTTPS
72+
hostname: "example.com"
73+
allowedRoutes:
74+
namespaces:
75+
from: Selector
76+
selector:
77+
¦ matchLabels:
78+
¦ shared-gateway-access: "true"
79+
----
80+
81+
Examples of the allowed namespaces for the `devops-gateway` resource:
82+
83+
.Example `Namespace` resources
84+
[source,yaml]
85+
----
86+
apiVersion: v1
87+
kind: Namespace
88+
metadata:
89+
name: dev
90+
labels:
91+
shared-gateway-access: "true"
92+
---
93+
apiVersion: v1
94+
kind: Namespace
95+
metadata:
96+
name: ops
97+
labels:
98+
shared-gateway-access: "true"
99+
----
100+
101+
An example of two `HTTPRoute` resources, `dev-portal` and `ops-home`, that sit in different namespaces but are attached to the shared gateway:
102+
103+
[source,yaml]
104+
----
105+
apiVersion: v1
106+
kind: HTTPRoute
107+
metadata:
108+
name: dev-portal
109+
namespace: dev
110+
spec:
111+
parentRefs:
112+
- name: devops-gateway
113+
namespace: openshift-ingress
114+
rules:
115+
- backendRefs:
116+
- name: dev-portal
117+
port: 8080
118+
---
119+
apiVersion: v1
120+
kind: HTTPRoute
121+
metadata:
122+
name: ops-home
123+
namespace: ops
124+
spec:
125+
parentRefs:
126+
- name: devops-gateway
127+
namespace: openshift-ingress
128+
rules:
129+
- backendRefs:
130+
- name: ops-home
131+
port: 8080
132+
----
133+
134+
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.
135+

‎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+
= {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+

‎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 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 create instances of Gateway APIs custom resource definitions (CRDs). For {product-title} clusters, these resources include:
14+
15+
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.
16+
Gateway:: This resource describes how traffic can be translated to services within the cluster. For example, a specific load balancer configuration.
17+
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.
18+
GRPCRoute:: This resource specific routing behavior of gRPC requests and is created by the Ingress Operator for the cluster.
19+
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.
20+
21+
{product-title}'s 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.
28+
* 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.
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 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:../networking/configuring-ingress-cluster-traffic/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)