From 8ea2068bb5effb9d759ccb6c9e50cd1183ea8630 Mon Sep 17 00:00:00 2001 From: David Yu Date: Fri, 24 Jul 2026 13:33:04 -0700 Subject: [PATCH 1/2] docs: document Gateway API HTTPRoute exposure for Redpanda Console Add an 'Expose Redpanda Console with the Gateway API' section to the Console Kubernetes deploy page (operator PR #1329): Gateway API CRD + controller + Gateway prerequisites, Operator CRD and Helm tabs for the gateway block, route verification (Accepted/ResolvedRefs, allowedRoutes gotcha), and switching between Ingress and Gateway API. Both Ingress callouts now point at the new section, and the operator v26.2.x what's-new gains an entry. Co-Authored-By: Claude Fable 5 --- .../pages/console/kubernetes/deploy.adoc | 174 +++++++++++++++++- .../pages/release-notes/operator.adoc | 6 + 2 files changed, 178 insertions(+), 2 deletions(-) diff --git a/modules/deploy/pages/console/kubernetes/deploy.adoc b/modules/deploy/pages/console/kubernetes/deploy.adoc index 83cce815bb..24490c92f7 100644 --- a/modules/deploy/pages/console/kubernetes/deploy.adoc +++ b/modules/deploy/pages/console/kubernetes/deploy.adoc @@ -88,7 +88,7 @@ spec: <2> For production, run at least two replicas for high availability and rolling upgrades. <3> Adjust resource requests and limits based on your expected workload and available node resources. <4> Use `LoadBalancer` for cloud environments or when you want Redpanda Console to be accessible from outside the cluster. Use `ClusterIP` for internal-only access. -<5> Enable and configure Ingress if you want to expose Redpanda Console using a domain name and use TLS/HTTPS. Make sure your cluster has an Ingress controller installed. +<5> Enable and configure Ingress if you want to expose Redpanda Console using a domain name and use TLS/HTTPS. Make sure your cluster has an Ingress controller installed. To use the Kubernetes Gateway API instead of Ingress, see <>. . Apply the Console CR: + @@ -174,7 +174,7 @@ Look for services named like `redpanda-0`, `redpanda-1`, etc. The port is typica <2> Adjust resource requests and limits based on your expected workload and available node resources. <3> For production, run at least two replicas for high availability and rolling upgrades. <4> Use `LoadBalancer` for cloud environments or when you want Redpanda Console to be accessible from outside the cluster. Use `ClusterIP` for internal-only access. -<5> Enable and configure Ingress if you want to expose Redpanda Console using a domain name and use TLS/HTTPS. Make sure your cluster has an Ingress controller installed. +<5> Enable and configure Ingress if you want to expose Redpanda Console using a domain name and use TLS/HTTPS. Make sure your cluster has an Ingress controller installed. To use the Kubernetes Gateway API instead of Ingress, see <>. . Install the chart: + @@ -300,6 +300,176 @@ Redpanda Console now connects securely to your Redpanda cluster using TLS. For p -- ====== +[[expose-console-gateway-api]] +== Expose Redpanda Console with the Gateway API + +As an alternative to Ingress, you can expose Redpanda Console through a Kubernetes https://gateway-api.sigs.k8s.io/[Gateway API^] HTTPRoute. The Gateway API separates infrastructure from application routing: a cluster operator manages a shared Gateway, which is the entry point that terminates TLS, and Redpanda Console attaches to that Gateway with an HTTPRoute that the Helm chart or the Redpanda Operator renders and manages for you. + +Choose the Gateway API over Ingress when your cluster already routes traffic through a Gateway controller, such as Envoy Gateway, Istio, Cilium, or NGINX Gateway Fabric, or when you want typed, role-based routing configuration instead of controller-specific Ingress annotations. + +Ingress and the Gateway API are mutually exclusive for Redpanda Console: enabling both fails validation with `ingress and gateway cannot both be enabled; use one or the other`. + +NOTE: With an HTTPRoute, TLS terminates at the Gateway's listener, so the certificate is configured on the Gateway resource rather than in the Redpanda Console configuration. + +=== Prerequisites + +The Gateway API resources are not bundled with Redpanda Console or the Redpanda Operator: + +. Install the https://gateway-api.sigs.k8s.io/guides/[Gateway API CRDs^]: ++ +[,bash] +---- +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml +---- + +. Install a Gateway API-compatible controller, such as https://gateway.envoyproxy.io/[Envoy Gateway^], https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/[Istio^], https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/[Cilium^], or https://github.com/nginx/nginx-gateway-fabric[NGINX Gateway Fabric^]. + +. Create a Gateway for the HTTPRoute to attach to, or identify an existing one: ++ +.`gateway.yaml` +[,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: my-gateway + namespace: gateway-system +spec: + gatewayClassName: eg <1> + listeners: + - name: https + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - name: console-tls <2> + allowedRoutes: + namespaces: + from: All <3> +---- ++ +<1> The GatewayClass name depends on your controller. For example, Envoy Gateway installs `eg`. +<2> A Secret in the Gateway's namespace that contains the TLS certificate for your Redpanda Console hostname. +<3> The listener must allow routes from the namespace where Redpanda Console runs. `from: All` accepts routes from any namespace. Use `from: Selector` to restrict which namespaces can attach. + +=== Enable the HTTPRoute + +Configure the `gateway` block instead of the `ingress` block: + +[tabs] +====== +Operator:: ++ +-- + +. Add a `gateway` block to the Console resource: ++ +.`console.yaml` +[,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: Console +metadata: + name: redpanda-console + namespace: redpanda +spec: + cluster: + clusterRef: + name: redpanda + gateway: + enabled: true + parentRefs: <1> + - name: my-gateway + namespace: gateway-system + sectionName: https + hostnames: <2> + - console.example.com + path: / <3> + pathType: PathPrefix +---- ++ +<1> References the Gateway that the HTTPRoute attaches to. `sectionName` optionally pins the route to one listener on that Gateway. Without `parentRefs`, the HTTPRoute is created but does not attach to any Gateway. +<2> The hostnames that the route matches. Point DNS for these hostnames at the Gateway's address. +<3> The path to match. `pathType` is one of `PathPrefix`, `Exact`, or `RegularExpression`. + +. Apply the resource: ++ +[,bash] +---- +kubectl apply -f console.yaml --namespace redpanda +---- + +The operator creates the HTTPRoute and keeps it in sync with the Console resource. + +-- +Helm:: ++ +-- + +. Add a `gateway` block to your values file: ++ +.`console-values.yaml` +[,yaml] +---- +gateway: <1> + enabled: true + parentRefs: + - name: my-gateway + namespace: gateway-system + sectionName: https + hostnames: + - console.example.com + path: / + pathType: PathPrefix +---- ++ +<1> The fields have the same meaning as in the Console resource: `parentRefs` selects the Gateway (and optionally one listener through `sectionName`), `hostnames` lists the hostnames to match, and `pathType` is one of `PathPrefix`, `Exact`, or `RegularExpression`. + +. Upgrade the release: ++ +[,bash] +---- +helm upgrade --install redpanda-console redpanda/console \ + --namespace redpanda \ + --values console-values.yaml +---- + +-- +====== + +=== Verify the route + +. Check that the HTTPRoute exists and was accepted by the Gateway: ++ +[,bash] +---- +kubectl get httproute --namespace redpanda +kubectl describe httproute redpanda-console --namespace redpanda +---- ++ +In the route's status, the `Accepted` and `ResolvedRefs` conditions should both be `True` for the referenced Gateway. If `Accepted` is `False` with reason `NotAllowedByListeners`, update the Gateway listener's `allowedRoutes` to include the Redpanda Console namespace. + +. Get the Gateway's external address and point DNS for your Redpanda Console hostname at it: ++ +[,bash] +---- +kubectl get gateway my-gateway --namespace gateway-system +---- + +. Confirm that Redpanda Console responds through the Gateway. Until DNS is in place, resolve the hostname to the Gateway address explicitly: ++ +[,bash] +---- +curl --resolve console.example.com:443: https://console.example.com -I +---- + +=== Switch between Ingress and the Gateway API + +To move an existing Redpanda Console deployment from Ingress to the Gateway API, remove or disable the `ingress` block and add the `gateway` block in the same update. The operator or chart deletes the Ingress and creates the HTTPRoute. Switching back works the same way in reverse: remove the `gateway` block, add the `ingress` block, and the HTTPRoute is removed and an Ingress created. + +TIP: To expose the Redpanda cluster itself through the Gateway API, see xref:manage:kubernetes/networking/external/k-gateway-api.adoc[]. + == Deploy Redpanda Console as standalone service with YAML manifests If you prefer to deploy using YAML manifests, you can create the following resources: diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index 86663b4b77..e900c09df3 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -22,6 +22,12 @@ The release also adds the xref:reference:rpk/rpk-k8s/rpk-k8s.adoc[`rpk k8s` plug For deployment steps, see xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. +=== Gateway API support for Redpanda Console + +The Console custom resource and the Redpanda Console Helm chart can expose Redpanda Console through a Kubernetes Gateway API HTTPRoute as an alternative to Ingress. You reference an existing Gateway in `gateway.parentRefs`, and the operator or chart renders and manages the HTTPRoute for you. Only one of `gateway` or `ingress` can be enabled at a time. + +See xref:deploy:console/kubernetes/deploy.adoc#expose-console-gateway-api[Expose Redpanda Console with the Gateway API]. + === Safer rolling restarts with per-broker health probes In Redpanda Operator v26.2.1 or later, the operator gates each step of a rolling restart with Redpanda's per-broker restart probes instead of a single cluster-wide health check. Before restarting a broker, the operator confirms that the restart cannot lose data acknowledged with `acks=1`, make partitions unavailable, or block `acks=all` produce requests. After each restart, the operator waits until the broker reports that it has fully resynced before restarting the next one, because a Pod can pass its readiness probe while the broker is still replaying partition state. From 7e5f1f1fa8841429290c131ab1494fc9b42eace0 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 27 Jul 2026 12:34:46 +0100 Subject: [PATCH 2/2] docs: apply standards review fixes - Add the missing kubectl apply step and listener acceptance check for the example Gateway - State the minimum Operator and chart versions, and mark the feature beta consistent with the Gateway API TLSRoute page and the release note - Link the canonical Gateway API prerequisites instead of duplicating the CRD and controller install steps with a pinned version, and note that HTTPRoute ships in the standard channel - Active voice throughout the new section, 'are both True' instead of 'should', explain the gateway-address placeholder, avoid overloading 'operator' for the person role, explicit link text on the closing TIP, and align code-block title ordering across the page --- .../pages/console/kubernetes/deploy.adoc | 45 ++++++++++--------- .../pages/release-notes/operator.adoc | 4 +- 2 files changed, 27 insertions(+), 22 deletions(-) diff --git a/modules/deploy/pages/console/kubernetes/deploy.adoc b/modules/deploy/pages/console/kubernetes/deploy.adoc index 24490c92f7..57849797b7 100644 --- a/modules/deploy/pages/console/kubernetes/deploy.adoc +++ b/modules/deploy/pages/console/kubernetes/deploy.adoc @@ -303,31 +303,24 @@ Redpanda Console now connects securely to your Redpanda cluster using TLS. For p [[expose-console-gateway-api]] == Expose Redpanda Console with the Gateway API -As an alternative to Ingress, you can expose Redpanda Console through a Kubernetes https://gateway-api.sigs.k8s.io/[Gateway API^] HTTPRoute. The Gateway API separates infrastructure from application routing: a cluster operator manages a shared Gateway, which is the entry point that terminates TLS, and Redpanda Console attaches to that Gateway with an HTTPRoute that the Helm chart or the Redpanda Operator renders and manages for you. +As an alternative to Ingress, you can expose Redpanda Console through a Kubernetes https://gateway-api.sigs.k8s.io/[Gateway API^] HTTPRoute. This feature is in beta and requires Redpanda Operator 26.2 or later, or Redpanda Helm chart 26.2.0 or later. Beta features are not recommended for production environments. The Gateway API separates infrastructure from application routing: your platform team manages a shared Gateway, which is the entry point that terminates TLS, and Redpanda Console attaches to that Gateway with an HTTPRoute that the Redpanda Operator or Helm chart renders and manages for you. Choose the Gateway API over Ingress when your cluster already routes traffic through a Gateway controller, such as Envoy Gateway, Istio, Cilium, or NGINX Gateway Fabric, or when you want typed, role-based routing configuration instead of controller-specific Ingress annotations. Ingress and the Gateway API are mutually exclusive for Redpanda Console: enabling both fails validation with `ingress and gateway cannot both be enabled; use one or the other`. -NOTE: With an HTTPRoute, TLS terminates at the Gateway's listener, so the certificate is configured on the Gateway resource rather than in the Redpanda Console configuration. +NOTE: With an HTTPRoute, TLS terminates at the Gateway's listener, so you configure the certificate on the Gateway resource instead of in the Redpanda Console configuration. === Prerequisites -The Gateway API resources are not bundled with Redpanda Console or the Redpanda Operator: +Redpanda Console and the Redpanda Operator don't bundle Gateway API resources: -. Install the https://gateway-api.sigs.k8s.io/guides/[Gateway API CRDs^]: -+ -[,bash] ----- -kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml ----- - -. Install a Gateway API-compatible controller, such as https://gateway.envoyproxy.io/[Envoy Gateway^], https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/[Istio^], https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/[Cilium^], or https://github.com/nginx/nginx-gateway-fabric[NGINX Gateway Fabric^]. +. Install the Gateway API CRDs and a compatible controller, such as https://gateway.envoyproxy.io/[Envoy Gateway^], https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/[Istio^], https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/[Cilium^], or https://github.com/nginx/nginx-gateway-fabric[NGINX Gateway Fabric^]. For versions and installation steps, see the prerequisites in xref:manage:kubernetes/networking/external/k-gateway-api.adoc#prerequisites[Configure External Access through Gateway API]. HTTPRoute ships in the standard channel, so either release channel works for this feature. . Create a Gateway for the HTTPRoute to attach to, or identify an existing one: + -.`gateway.yaml` [,yaml] +.`gateway.yaml` ---- apiVersion: gateway.networking.k8s.io/v1 kind: Gateway @@ -353,6 +346,18 @@ spec: <2> A Secret in the Gateway's namespace that contains the TLS certificate for your Redpanda Console hostname. <3> The listener must allow routes from the namespace where Redpanda Console runs. `from: All` accepts routes from any namespace. Use `from: Selector` to restrict which namespaces can attach. +. Apply the manifest and verify that the controller accepts the listener: ++ +[,bash] +---- +kubectl apply -f gateway.yaml + +kubectl get gateway my-gateway --namespace gateway-system \ + -o jsonpath='{range .status.listeners[*]}{.name}: {range .conditions[*]}{.type}={.status} {end}{"\n"}{end}' +---- ++ +The listener reports `Accepted=True` and `Programmed=True`. + === Enable the HTTPRoute Configure the `gateway` block instead of the `ingress` block: @@ -365,8 +370,8 @@ Operator:: . Add a `gateway` block to the Console resource: + -.`console.yaml` [,yaml] +.`console.yaml` ---- apiVersion: cluster.redpanda.com/v1alpha2 kind: Console @@ -389,7 +394,7 @@ spec: pathType: PathPrefix ---- + -<1> References the Gateway that the HTTPRoute attaches to. `sectionName` optionally pins the route to one listener on that Gateway. Without `parentRefs`, the HTTPRoute is created but does not attach to any Gateway. +<1> References the Gateway that the HTTPRoute attaches to. `sectionName` optionally pins the route to one listener on that Gateway. Without `parentRefs`, Redpanda creates the HTTPRoute but it doesn't attach to any Gateway. <2> The hostnames that the route matches. Point DNS for these hostnames at the Gateway's address. <3> The path to match. `pathType` is one of `PathPrefix`, `Exact`, or `RegularExpression`. @@ -409,8 +414,8 @@ Helm:: . Add a `gateway` block to your values file: + -.`console-values.yaml` [,yaml] +.`console-values.yaml` ---- gateway: <1> enabled: true @@ -440,7 +445,7 @@ helm upgrade --install redpanda-console redpanda/console \ === Verify the route -. Check that the HTTPRoute exists and was accepted by the Gateway: +. Check that the HTTPRoute exists and that the Gateway accepted it: + [,bash] ---- @@ -448,7 +453,7 @@ kubectl get httproute --namespace redpanda kubectl describe httproute redpanda-console --namespace redpanda ---- + -In the route's status, the `Accepted` and `ResolvedRefs` conditions should both be `True` for the referenced Gateway. If `Accepted` is `False` with reason `NotAllowedByListeners`, update the Gateway listener's `allowedRoutes` to include the Redpanda Console namespace. +In the route's status, the `Accepted` and `ResolvedRefs` conditions are both `True` for the referenced Gateway. If `Accepted` is `False` with reason `NotAllowedByListeners`, update the Gateway listener's `allowedRoutes` to include the Redpanda Console namespace. . Get the Gateway's external address and point DNS for your Redpanda Console hostname at it: + @@ -461,14 +466,14 @@ kubectl get gateway my-gateway --namespace gateway-system + [,bash] ---- -curl --resolve console.example.com:443: https://console.example.com -I +curl --resolve console.example.com:443: https://console.example.com -I # Replace with the address from the previous step. ---- === Switch between Ingress and the Gateway API -To move an existing Redpanda Console deployment from Ingress to the Gateway API, remove or disable the `ingress` block and add the `gateway` block in the same update. The operator or chart deletes the Ingress and creates the HTTPRoute. Switching back works the same way in reverse: remove the `gateway` block, add the `ingress` block, and the HTTPRoute is removed and an Ingress created. +To move an existing Redpanda Console deployment from Ingress to the Gateway API, remove or disable the `ingress` block and add the `gateway` block in the same update. The operator or chart deletes the Ingress and creates the HTTPRoute. Switching back works the same way in reverse: remove the `gateway` block, add the `ingress` block, and the operator or chart removes the HTTPRoute and creates an Ingress. -TIP: To expose the Redpanda cluster itself through the Gateway API, see xref:manage:kubernetes/networking/external/k-gateway-api.adoc[]. +TIP: To expose the Redpanda cluster itself through the Gateway API, see xref:manage:kubernetes/networking/external/k-gateway-api.adoc[Configure External Access through Gateway API]. == Deploy Redpanda Console as standalone service with YAML manifests diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index e900c09df3..03e72a7cf7 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -22,9 +22,9 @@ The release also adds the xref:reference:rpk/rpk-k8s/rpk-k8s.adoc[`rpk k8s` plug For deployment steps, see xref:deploy:redpanda/kubernetes/k-stretch-clusters.adoc[]. -=== Gateway API support for Redpanda Console +=== Gateway API support for Redpanda Console (beta) -The Console custom resource and the Redpanda Console Helm chart can expose Redpanda Console through a Kubernetes Gateway API HTTPRoute as an alternative to Ingress. You reference an existing Gateway in `gateway.parentRefs`, and the operator or chart renders and manages the HTTPRoute for you. Only one of `gateway` or `ingress` can be enabled at a time. +The Console custom resource and the Redpanda Console Helm chart can expose Redpanda Console through a Kubernetes Gateway API HTTPRoute as an alternative to Ingress. You reference an existing Gateway in `gateway.parentRefs`, and the operator or chart renders and manages the HTTPRoute for you. You can enable only one of `gateway` or `ingress` at a time. See xref:deploy:console/kubernetes/deploy.adoc#expose-console-gateway-api[Expose Redpanda Console with the Gateway API].