Skip to content

Commit c15ecbb

Browse files
jessesimpson36jessesimpson36
authored
Merge pull request #8008 from camunda/dup_88_gateway_api_manual
feat: gateway api implementation guide in earlier versions
2 parents c680e9e + dea718f commit c15ecbb

File tree

7 files changed

+459
-3
lines changed

7 files changed

+459
-3
lines changed

‎docs/self-managed/deployment/helm/configure/ingress/gateway-api-setup.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ The Gateway API provides a modern way to manage Ingress traffic in Kubernetes cl
1313
- Enables configuration of NGINX without relying on labels and annotations, which also helps limit permissions.
1414

1515
:::note
16-
The Ingress-NGINX controller is planned to reach end of life in March 2026 (see the Kubernetes announcement on Ingress-NGINX retirement). We recommend planning a migration to the Gateway API where it fits your use case.
16+
The Ingress-NGINX controller is planned to reach end of life in March 2026 (see [the Kubernetes announcement on Ingress-NGINX retirement](https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/)). Plan a migration to the Gateway API where it fits your use case.
1717

1818
If you decide not to adopt the Gateway API, you can migrate to a different Ingress controller and continue using the Ingress API. This remains a supported approach.
1919
:::
@@ -25,7 +25,7 @@ Ensure both are installed in your cluster.
2525
- Gateway API CRDs
2626
- A Gateway API controller
2727

28-
## Gateway controllers
28+
### Gateway controllers
2929

3030
Just like Ingress Controllers, Gateway controllers need to be installed before a cluster can use the Gateway API. [See the list of Gateway API implementations](https://gateway-api.sigs.k8s.io/implementations/) for details.
3131

‎versioned_docs/version-8.6/self-managed/setup/guides/gateway-api-setup.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
id: gateway-api-setup
3+
sidebar_label: With Gateway API
4+
title: Configure the Helm chart with Gateway API
5+
description: Configure the Camunda 8 Self-Managed Helm chart to use the Kubernetes Gateway API.
6+
---
7+
8+
Configure the Camunda 8 Self-Managed Helm chart to use the Kubernetes Gateway API instead of a traditional Ingress controller for modern, secure traffic routing in Kubernetes clusters.
9+
10+
## About
11+
12+
The Gateway API provides a modern way to manage Ingress traffic in Kubernetes clusters. It improves on the Ingress API in the following ways:
13+
14+
- Separates cluster operators, who manage Gateway resources, from application developers, who manage HTTPRoute resources.
15+
- Enables configuration of NGINX without relying on labels and annotations, which also helps limit permissions.
16+
17+
:::important
18+
The Ingress-NGINX controller is planned to reach end of life in March 2026 (see [the Kubernetes announcement on Ingress-NGINX retirement](https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/)). Plan a migration to the Gateway API where it fits your use case.
19+
20+
If you decide not to adopt the Gateway API, you can migrate to a different Ingress controller and continue using the Ingress API. This remains a supported approach.
21+
:::
22+
23+
## Prerequisites
24+
25+
Ensure the following are installed in your cluster:
26+
27+
- Gateway API CRDs.
28+
- A Gateway API controller.
29+
30+
### Gateway controllers
31+
32+
Just like Ingress controllers, Gateway controllers must be installed before a cluster can use the Gateway API. See [Gateway API implementations](https://gateway-api.sigs.k8s.io/implementations/) for details.
33+
34+
In testing, Camunda uses the [NGINX Gateway Fabric](https://github.com/nginx/nginx-gateway-fabric).
35+
36+
## Implement
37+
38+
Get started by running the `helm template` command against version 8.9 or later of the Helm chart to generate the resources, then modify them as needed. See the following command example:
39+
40+
```bash
41+
helm template camunda camunda/camunda-platform \
42+
--version 14.0.0 \
43+
--set global.host=example.com \
44+
--set global.gateway.enabled=true \
45+
--set global.gateway.createGatewayResource=true \
46+
--set orchestration.data.secondaryStorage.type=elasticsearch \
47+
--show-only templates/orchestration/httproute.yaml \
48+
--show-only templates/orchestration/grpcroute.yaml \
49+
--show-only templates/common/referencegrant.yaml \
50+
--show-only templates/common/gateway.yaml
51+
```
52+
53+
### `Gateway`
54+
55+
Gateway resources are intended to be created by cluster operators to define how traffic enters the cluster and which controllers are responsible for managing it.
56+
They reference a `GatewayClass` resource, which defines which controller will manage the gateway and `HTTPRoute` resources.
57+
58+
Here's an example:
59+
60+
```yaml
61+
apiVersion: gateway.networking.k8s.io/v1
62+
kind: Gateway
63+
metadata:
64+
name: camunda-camunda-platform
65+
annotations:
66+
spec:
67+
gatewayClassName: nginx
68+
listeners:
69+
- name: http
70+
port: 80
71+
protocol: HTTP
72+
hostname: example.com
73+
- name: grpc
74+
port: 80
75+
protocol: HTTP
76+
hostname: grpc-example.com
77+
```
78+
79+
See [Kubernetes Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) for more details.
80+
81+
### `ReferenceGrants`
82+
83+
`ReferenceGrants` allow the gateway controller to reference service resources in the application namespace.
84+
This Gateway API security feature limits which resources the gateway and `HTTPRoute` resources can reference.
85+
86+
Here's an example:
87+
88+
```yaml
89+
kind: ReferenceGrant
90+
apiVersion: gateway.networking.k8s.io/v1beta1
91+
metadata:
92+
name: camunda-camunda-platform
93+
spec:
94+
from:
95+
- group: gateway.networking.k8s.io
96+
kind: HTTPRoute
97+
namespace: NAMESPACE
98+
to:
99+
- group: ""
100+
kind: Service
101+
```
102+
103+
See [Kubernetes `ReferenceGrant`](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) for more details.
104+
105+
### `HTTPRoute` and `GRPCRoute`
106+
107+
These routes are intended to be created by application developers to expose endpoints and route them to specific services.
108+
109+
Here's an example:
110+
111+
```yaml
112+
---
113+
apiVersion: gateway.networking.k8s.io/v1
114+
kind: HTTPRoute
115+
metadata:
116+
name: orchestration
117+
annotations:
118+
spec:
119+
parentRefs:
120+
- name: camunda-camunda-platform
121+
sectionName: http
122+
hostnames:
123+
- "example.com"
124+
rules:
125+
- matches:
126+
- path:
127+
type: PathPrefix
128+
value: /orchestration
129+
backendRefs:
130+
- name: camunda-zeebe-gateway
131+
namespace: NAMESPACE
132+
port: 8080
133+
---
134+
apiVersion: gateway.networking.k8s.io/v1
135+
kind: GRPCRoute
136+
metadata:
137+
name: camunda-camunda-platform-grpc
138+
annotations:
139+
spec:
140+
parentRefs:
141+
- name: camunda-camunda-platform
142+
hostnames:
143+
- "grpc-example.com"
144+
rules:
145+
- backendRefs:
146+
- name: camunda-zeebe-gateway
147+
namespace: NAMESPACE
148+
port: 26500
149+
```
150+
151+
See [Kubernetes `HTTPRoute`](https://gateway-api.sigs.k8s.io/api-types/httproute/) and [Kubernetes `GRPCRoute`](https://gateway-api.sigs.k8s.io/api-types/grpcroute/) for more details.

‎versioned_docs/version-8.7/self-managed/setup/guides/gateway-api-setup.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
id: gateway-api-setup
3+
sidebar_label: With Gateway API
4+
title: Configure the Helm chart with Gateway API
5+
description: Configure the Camunda 8 Self-Managed Helm chart to use the Kubernetes Gateway API.
6+
---
7+
8+
Configure the Camunda 8 Self-Managed Helm chart to use the Kubernetes Gateway API instead of a traditional Ingress controller for modern, secure traffic routing in Kubernetes clusters.
9+
10+
## About
11+
12+
The Gateway API provides a modern way to manage Ingress traffic in Kubernetes clusters. It improves on the Ingress API in the following ways:
13+
14+
- Separates cluster operators, who manage Gateway resources, from application developers, who manage HTTPRoute resources.
15+
- Enables configuration of NGINX without relying on labels and annotations, which also helps limit permissions.
16+
17+
:::important
18+
The Ingress-NGINX controller is planned to reach end of life in March 2026 (see [the Kubernetes announcement on Ingress-NGINX retirement](https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/)). Plan a migration to the Gateway API where it fits your use case.
19+
20+
If you decide not to adopt the Gateway API, you can migrate to a different Ingress controller and continue using the Ingress API. This remains a supported approach.
21+
:::
22+
23+
## Prerequisites
24+
25+
Ensure the following are installed in your cluster:
26+
27+
- Gateway API CRDs.
28+
- A Gateway API controller.
29+
30+
### Gateway controllers
31+
32+
Just like Ingress controllers, Gateway controllers must be installed before a cluster can use the Gateway API. See [Gateway API implementations](https://gateway-api.sigs.k8s.io/implementations/) for details.
33+
34+
In testing, Camunda uses the [NGINX Gateway Fabric](https://github.com/nginx/nginx-gateway-fabric).
35+
36+
## Implement
37+
38+
Get started by running the `helm template` command against version 8.9 or later of the Helm chart to generate the resources, then modify them as needed. See the following command example:
39+
40+
```bash
41+
helm template camunda camunda/camunda-platform \
42+
--version 14.0.0 \
43+
--set global.host=example.com \
44+
--set global.gateway.enabled=true \
45+
--set global.gateway.createGatewayResource=true \
46+
--set orchestration.data.secondaryStorage.type=elasticsearch \
47+
--show-only templates/orchestration/httproute.yaml \
48+
--show-only templates/orchestration/grpcroute.yaml \
49+
--show-only templates/common/referencegrant.yaml \
50+
--show-only templates/common/gateway.yaml
51+
```
52+
53+
### `Gateway`
54+
55+
Gateway resources are intended to be created by cluster operators to define how traffic enters the cluster and which controllers are responsible for managing it.
56+
They reference a `GatewayClass` resource, which defines which controller will manage the gateway and `HTTPRoute` resources.
57+
58+
Here's an example:
59+
60+
```yaml
61+
apiVersion: gateway.networking.k8s.io/v1
62+
kind: Gateway
63+
metadata:
64+
name: camunda-camunda-platform
65+
annotations:
66+
spec:
67+
gatewayClassName: nginx
68+
listeners:
69+
- name: http
70+
port: 80
71+
protocol: HTTP
72+
hostname: example.com
73+
- name: grpc
74+
port: 80
75+
protocol: HTTP
76+
hostname: grpc-example.com
77+
```
78+
79+
See [Kubernetes Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) for more details.
80+
81+
### `ReferenceGrants`
82+
83+
`ReferenceGrants` allow the gateway controller to reference service resources in the application namespace.
84+
This Gateway API security feature limits which resources the gateway and `HTTPRoute` resources can reference.
85+
86+
Here's an example:
87+
88+
```yaml
89+
kind: ReferenceGrant
90+
apiVersion: gateway.networking.k8s.io/v1beta1
91+
metadata:
92+
name: camunda-camunda-platform
93+
spec:
94+
from:
95+
- group: gateway.networking.k8s.io
96+
kind: HTTPRoute
97+
namespace: NAMESPACE
98+
to:
99+
- group: ""
100+
kind: Service
101+
```
102+
103+
See [Kubernetes `ReferenceGrant`](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) for more details.
104+
105+
### `HTTPRoute` and `GRPCRoute`
106+
107+
These routes are intended to be created by application developers to expose endpoints and route them to specific services.
108+
109+
Here's an example:
110+
111+
```yaml
112+
---
113+
apiVersion: gateway.networking.k8s.io/v1
114+
kind: HTTPRoute
115+
metadata:
116+
name: orchestration
117+
annotations:
118+
spec:
119+
parentRefs:
120+
- name: camunda-camunda-platform
121+
sectionName: http
122+
hostnames:
123+
- "example.com"
124+
rules:
125+
- matches:
126+
- path:
127+
type: PathPrefix
128+
value: /orchestration
129+
backendRefs:
130+
- name: camunda-zeebe-gateway
131+
namespace: NAMESPACE
132+
port: 8080
133+
---
134+
apiVersion: gateway.networking.k8s.io/v1
135+
kind: GRPCRoute
136+
metadata:
137+
name: camunda-camunda-platform-grpc
138+
annotations:
139+
spec:
140+
parentRefs:
141+
- name: camunda-camunda-platform
142+
hostnames:
143+
- "grpc-example.com"
144+
rules:
145+
- backendRefs:
146+
- name: camunda-zeebe-gateway
147+
namespace: NAMESPACE
148+
port: 26500
149+
```
150+
151+
See [Kubernetes `HTTPRoute`](https://gateway-api.sigs.k8s.io/api-types/httproute/) and [Kubernetes `GRPCRoute`](https://gateway-api.sigs.k8s.io/api-types/grpcroute/) for more details.

0 commit comments

Comments
 (0)