atlassian · pbhardwaj6 · Mar 20, 2026 · Mar 2, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/docs/docs/examples/ingress/CONTROLLERS.md b/docs/docs/examples/ingress/CONTROLLERS.md
@@ -1,6 +1,21 @@
-# Provisioning an Ingress controller
-In order for the provided Ingress resource to work, your Kubernetes cluster must have an ingress controller running. The Atlassian Helm charts have been tested with the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/){.external}, however [alternatives can also be used](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/#additional-controllers){.external}. 
+# Provisioning a traffic entry controller
 
-Here is an example of how these controllers can be installed and configured for use with the Atlassian Helm charts:
+To expose an Atlassian DC product outside your Kubernetes cluster, you must run **one** of the following:
 
-* [NGINX Ingress Controller](INGRESS_NGINX.md)
+- an **Ingress controller** (to process Kubernetes `Ingress` resources), or
+- a **Gateway API controller** (to process Kubernetes Gateway API resources, such as `HTTPRoute`).
+
+The Helm charts can render either:
+
+- a Kubernetes `Ingress` when `ingress.create: true`, or
+- a Kubernetes Gateway API `HTTPRoute` when `gateway.create: true`.
+
+These options are **mutually exclusive** (you cannot enable both `ingress.create` and `gateway.create`).
+
+!!!note "Sticky sessions are required"
+    Atlassian DC products require **session stickiness** ("sticky sessions") for high availability. With NGINX Ingress this is handled via controller annotations. With Gateway API you must configure stickiness using your chosen Gateway implementation.
+
+## Example guides
+
+- [NGINX Ingress Controller (Ingress)](INGRESS_NGINX.md)
+- [Gateway API controller (Gateway API)](GATEWAY_API.md)
diff --git a/docs/docs/examples/ingress/GATEWAY_API.md b/docs/docs/examples/ingress/GATEWAY_API.md
@@ -0,0 +1,99 @@
+# Gateway API controller (HTTPRoute)
+
+The Atlassian DC Helm charts support exposing products via the **Kubernetes Gateway API** by rendering a `HTTPRoute` resource when `gateway.create: true`.
+
+To use this, your cluster must have:
+
+- Gateway API CRDs installed
+- a Gateway API controller installed (for example, Envoy Gateway, Istio, etc.)
+- a `Gateway` resource that allows routes from your product namespace
+
+!!!note "What the charts create"
+    The charts create a **`HTTPRoute`** only. You must provision the **`GatewayClass`**, **`Gateway`**, and (optionally) **TLS certificates** in your cluster.
+
+## 1. Install a Gateway API controller
+
+Follow your chosen implementation's installation instructions:
+
+- Gateway API overview: <https://gateway-api.sigs.k8s.io/>
+- Implementations: <https://gateway-api.sigs.k8s.io/implementations/>
+
+## 2. Create a Gateway
+
+Create a `Gateway` that will accept `HTTPRoute` attachments from the namespace where you install the Atlassian product.
+
+The exact `gatewayClassName`, listener configuration, and TLS configuration depend on your chosen implementation.
+
+## 3. Configure the Helm chart
+
+Disable `ingress.create` and enable `gateway.create`. Provide a **parentRef** pointing to your `Gateway` and at least one **hostname**.
+
+```yaml
+ingress:
+  create: false
+
+gateway:
+  create: true
+  hostnames:
+    - confluence.example.com
+  https: true
+  parentRefs:
+    - name: atlassian-gateway
+      namespace: gateway-system   # optional, defaults to release namespace
+      sectionName: https          # optional, target a specific Gateway listener
+```
+
+!!!info "TLS termination"
+    With Gateway API, TLS termination is configured on the `Gateway` listeners (not on the `HTTPRoute`). The `gateway.https` value controls the product's proxy/URL settings (e.g., generating HTTPS links), but it does not provision certificates by itself.
+
+## Gateway values reference
+
+The `gateway` stanza is split into two groups:
+
+**Product configuration** (always active when `gateway.hostnames` is set):
+
+| Value | Description | Default |
+|-------|-------------|---------|
+| `gateway.create` | Create an `HTTPRoute` resource | `false` |
+| `gateway.hostnames` | Hostnames to route; first entry is used as the canonical hostname for base URL and proxy settings | `[]` |
+| `gateway.https` | Whether users access the application over HTTPS | `true` |
+| `gateway.externalPort` | Port users connect on; only set for non-standard ports | `443` (https) / `80` (http) |
+| `gateway.path` | Base path; falls back to `<product>.service.contextPath` when empty | (empty) |
+
+**HTTPRoute configuration** (only applies when `gateway.create: true`):
+
+| Value | Description | Default |
+|-------|-------------|---------|
+| `gateway.parentRefs` | List of [ParentReference](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.ParentReference){.external} objects (`name`, `namespace`, `sectionName`, etc.) | `[]` (required) |
+| `gateway.pathType` | Path matching type: `PathPrefix`, `Exact`, or `RegularExpression` | `PathPrefix` |
+| `gateway.annotations` | Annotations to add to the HTTPRoute | `{}` |
+| `gateway.labels` | Labels to add to the HTTPRoute | `{}` |
+| `gateway.filters` | [HTTPRouteFilter](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilter){.external} list (header modification, redirects, URL rewrites) | `[]` |
+| `gateway.timeouts.request` | Total request timeout | `60s` |
+| `gateway.timeouts.backendRequest` | Backend request timeout | `60s` |
+| `gateway.additionalRules` | Extra [HTTPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule){.external} entries for advanced routing | `[]` |
+
+!!!note "Using gateway config without creating an HTTPRoute"
+    Setting `gateway.hostnames` activates gateway mode for the product's proxy and base-URL configuration **even when `gateway.create` is false**. This is useful when you have a pre-existing Gateway or external proxy/load balancer and only need the Helm chart to configure the product itself, without creating any Kubernetes routing resource.
+
+## 4. Timeouts
+
+The `gateway.timeouts` block replaces the Ingress-style `proxyReadTimeout` / `proxySendTimeout` settings:
+
+```yaml
+gateway:
+  timeouts:
+    request: "60s"        # total request timeout
+    backendRequest: "60s" # backend request timeout
+```
+
+!!!warning "No Gateway API equivalents"
+    There is no standard Gateway API equivalent for `proxyConnectTimeout` or `maxBodySize`. If you need those, configure them through controller-specific policies (e.g. Envoy Gateway `BackendTrafficPolicy`).
+
+
+## Configure session affinity (sticky sessions)
+
+Session affinity is **required** for Atlassian DC products and is **not** part of the standard `HTTPRoute` API.
+
+See [Session affinity with Gateway API](GATEWAY_API_SESSION_AFFINITY.md) for implementation-specific examples (cookie-based) and links for further reading.
+
diff --git a/docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md b/docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md
@@ -0,0 +1,70 @@
+# Session Affinity with Gateway API
+
+Atlassian DC products require **sticky sessions** so that a user is consistently routed to the same pod. With the NGINX Ingress controller this was handled automatically via annotations:
+
+```yaml
+nginx.ingress.kubernetes.io/affinity: "cookie"
+nginx.ingress.kubernetes.io/affinity-mode: "persistent"
+```
+
+With Gateway API, session affinity is **not** part of the standard `HTTPRoute` spec and must be configured separately.
+
+## Cookie naming
+
+Use a **dedicated routing cookie** (for example `ATLROUTE_<PRODUCT>`) rather than the application's own `JSESSIONID`. This avoids conflicts with the application's session cookie and matches the approach used by NGINX Ingress.
+
+## Options at a glance
+
+| Approach | Cookie-based | Standard channel |
+|----------|:---:|:---:|
+| Implementation policy (Option 1) | Yes | N/A (separate CRD) |
+| Experimental `sessionPersistence` (Option 2) | Yes | No (experimental) |
+
+---
+
+## Implementation-specific policies (recommended)
+
+Each Gateway API implementation provides its own policy resource for session affinity. Create the appropriate resource in the **same namespace** as your Helm release.
+
+### Envoy Gateway
+
+```yaml
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: <product>-session-affinity
+  namespace: <your-namespace>
+spec:
+  targetRefs:
+  - group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: <release-name>-<product>
+  loadBalancer:
+    type: ConsistentHash
+    consistentHash:
+      type: Cookie
+      cookie:
+        name: ATLROUTE_<PRODUCT>
+        ttl: 10h
+```
+
+**Explore further:**
+
+- Envoy Gateway load balancing & session persistence: <https://gateway.envoyproxy.io/latest/tasks/traffic/load-balancing/>
+- Envoy Gateway `BackendTrafficPolicy` API: <https://gateway.envoyproxy.io/latest/api/extension_types/#backendtrafficpolicy>
+- Istio consistent-hash via `DestinationRule`: <https://istio.io/latest/docs/reference/config/networking/destination-rule/#LoadBalancerSettings-ConsistentHashLB>
+
+---
+
+## Experimental `sessionPersistence` on HTTPRoute
+
+The Gateway API project has an **experimental** `sessionPersistence` field on HTTPRoute rules, tracked in **GEP-1619**. This field is **not** included in the standard-channel CRDs and will cause validation errors if those are installed.
+
+**Explore further:**
+
+- GEP-1619: <https://gateway-api.sigs.k8s.io/geps/gep-1619/>
+- `SessionPersistence` field reference: <https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.SessionPersistence>
+- Experimental CRDs install (pick a release): <https://github.com/kubernetes-sigs/gateway-api/releases>
+
+!!!warning "Implementation support varies"
+    Even with experimental CRDs installed, not all Gateway implementations support `sessionPersistence`. Check your implementation's conformance/support documentation.
diff --git a/docs/docs/userguide/CONFIGURATION.md b/docs/docs/userguide/CONFIGURATION.md
@@ -1,15 +1,22 @@
 # Configuration
 
 ## :material-directions-fork: Ingress
-In order to make the Atlassian product available from outside of the Kubernetes cluster, a suitable HTTP/HTTPS ingress controller needs to be installed. The standard Kubernetes Ingress resource is not flexible enough for our needs, so a third-party ingress controller and resource definition must be provided. The exact details of the Ingress will be highly site-specific. These Helm charts were tested using the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/){.external}. We also provide [example instructions](../examples/ingress/CONTROLLERS.md) on how this controller can be installed and configured.
+In order to make the Atlassian product available from outside of the Kubernetes cluster, you must provision a suitable HTTP/HTTPS traffic entry controller.
 
-The charts themselves provide a template for Ingress resource rules to be utilised by the provisioned controller. These include all required annotations and optional TLS configuration for the NGINX Ingress Controller.
+The Helm charts support exposing products using either:
+
+- Kubernetes **Ingress** resources (via an Ingress controller), or
+- Kubernetes **Gateway API** resources (via a Gateway API controller), by creating a `HTTPRoute`.
+
+The exact details will be highly site-specific. These Helm charts were tested using the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/){.external}. We also provide [example instructions](../examples/ingress/CONTROLLERS.md) on how controllers can be installed and configured.
+
+The charts themselves provide templates for either `Ingress` or `HTTPRoute` resources (depending on configuration). These include the required knobs for configuring hostnames, paths, timeouts, and (for NGINX Ingress) annotations.
 
 Some key considerations to note when configuring the controller are:
 
 !!!Ingress requirements
     * At a minimum, the ingress needs the ability to support long request timeouts, as well as session affinity (aka "sticky sessions").
-    * The Ingress Resource provided as part of the Helm charts is geared toward the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/){.external} and can be configured via the `ingress` stanza in the appropriate `values.yaml`. Some key aspects that can be configured include:
+    * The `Ingress` template provided as part of the Helm charts is geared toward the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/){.external} and can be configured via the `ingress` stanza in the appropriate `values.yaml`. Some key aspects that can be configured include:
 
          * Usage of the NGINX Ingress Controller
          * Ingress Controller annotations
@@ -78,6 +85,41 @@ curl -I https://bitbucket.example.com/status
 | Requests routing to different pods | Check if clustering is enabled |
 | Session cookies not working | Ensure ingress controller supports session affinity |
 
+### Gateway API (HTTPRoute)
+
+The charts can create a Gateway API `HTTPRoute` instead of an `Ingress` resource.
+
+```yaml
+ingress:
+  create: false
+
+gateway:
+  create: true
+  hostnames:
+    - bitbucket.example.com
+  https: true
+  parentRefs:
+    - name: atlassian-gateway
+      namespace: gateway-system  # optional
+```
+
+The `gateway` stanza supports additional options for fine-tuning the `HTTPRoute`:
+
+- **`parentRefs`** – list of [ParentReference](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.ParentReference){.external} objects pointing to your `Gateway` resource (supports `name`, `namespace`, `sectionName`, etc.)
+- **`externalPort`** – non-standard port that users connect on (defaults to `443`/`80`)
+- **`timeouts`** – `request` and `backendRequest` timeouts (replaces Ingress `proxyReadTimeout`/`proxySendTimeout`)
+- **`filters`** – [HTTPRouteFilter](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilter){.external} list for header modification, redirects, or URL rewrites
+- **`additionalRules`** – extra [HTTPRouteRule](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule){.external} entries for advanced routing (traffic splitting, header-based routing)
+- **`annotations`** / **`labels`** – metadata applied to the HTTPRoute resource
+
+!!!note "Gateway mode without creating an HTTPRoute"
+    Setting `gateway.hostnames` activates gateway mode for the product's proxy and base-URL configuration even when `gateway.create` is false. This allows use with a pre-existing Gateway or external proxy/load balancer.
+
+For the full list of values and usage examples, see the [Gateway API guide](../examples/ingress/GATEWAY_API.md).
+
+!!!important "Sticky sessions with Gateway API"
+    Session affinity is **not** part of the standard Gateway API `HTTPRoute` spec. You must configure it using your Gateway implementation (for example, Envoy Gateway policy resources or Istio traffic policy). See [Session affinity with Gateway API](../examples/ingress/GATEWAY_API_SESSION_AFFINITY.md) for working examples and fallbacks.
+
 ### Other Ingress Controllers
 
 For other ingress controllers ([AWS ALB](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/){.external}, [Google Cloud Load Balancer](https://cloud.google.com/load-balancing){.external}, [Azure Application Gateway](https://azure.microsoft.com/en-us/products/application-gateway){.external}), refer to your controller's documentation for session stickiness configuration.

diff --git a/docs/docs/userguide/INSTALLATION.md b/docs/docs/userguide/INSTALLATION.md
@@ -68,7 +68,12 @@ database:
     Read about [Kubernetes secrets](https://kubernetes.io/docs/concepts/configuration/secret/){.external}.
 
 ## 4. Configure Ingress
-Using the `values.yaml` file obtained in [step 2](#2-obtain-valuesyaml), configure the [Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/){.external} provisioned as part of the [Prerequisites](PREREQUISITES.md). The values you provide here will be used to provision an Ingress resource for the controller. Refer to the associated comments within the `values.yaml` file for additional details on how to configure the Ingress resource:
+Using the `values.yaml` file obtained in [step 2](#2-obtain-valuesyaml), configure how the product will be exposed outside the cluster. You can use either:
+
+- a Kubernetes **Ingress** (requires an [Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/){.external}), or
+- a Kubernetes Gateway API **HTTPRoute** (requires a Gateway API controller and a `Gateway`).
+
+The values you provide here will be used to provision either an `Ingress` or an `HTTPRoute` resource for your chosen controller. Refer to the associated comments within the `values.yaml` file for additional details.
 
 ```yaml
 ingress:
@@ -83,10 +88,29 @@ ingress:
   tlsSecretName: <tls_certificate_name>
 ```
 
+Alternatively, to use Gateway API:
+
+```yaml
+ingress:
+  create: false
+
+gateway:
+  create: true  # Creates an HTTPRoute resource
+  hostnames:
+    - <dns_host_name>
+  https: true
+  parentRefs:
+    - name: <gateway_name>
+      namespace: <gateway_namespace>  # optional, defaults to release namespace
+```
+
 !!!info "Ingress configuration"
     For additional details on Ingress controllers see [the Ingress section of the configuration guide](CONFIGURATION.md#ingress). 
 
-    See an example of [how to set up a controller](../examples/ingress/CONTROLLERS.md).
+    See an example of [how to set up an NGINX Ingress Controller](../examples/ingress/INGRESS_NGINX.md) and an overview of [controller options](../examples/ingress/CONTROLLERS.md).
+
+!!!info "Gateway API configuration"
+    For Gateway API exposure, start with the [Gateway API controller guide](../examples/ingress/GATEWAY_API.md) and then configure [session affinity](../examples/ingress/GATEWAY_API_SESSION_AFFINITY.md). The Gateway API guide includes a full values reference and examples for timeouts, filters, and advanced routing.
 
 ## 5. Configure persistent storage