diff --git a/docs/docs/examples/ingress/CONTROLLERS.md b/docs/docs/examples/ingress/CONTROLLERS.md index 67ef8c8c9..700754c7c 100644 --- 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 new file mode 100644 index 000000000..8cf10a5eb --- /dev/null +++ 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: +- 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 `.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 new file mode 100644 index 000000000..0a3af5c05 --- /dev/null +++ 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_`) 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: -session-affinity + namespace: +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: - + loadBalancer: + type: ConsistentHash + consistentHash: + type: Cookie + cookie: + name: ATLROUTE_ + ttl: 10h +``` + +**Explore further:** + +- Envoy Gateway load balancing & session persistence: +- Envoy Gateway `BackendTrafficPolicy` API: +- Istio consistent-hash via `DestinationRule`: + +--- + +## 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: +- `SessionPersistence` field reference: +- Experimental CRDs install (pick a release): + +!!!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 index f18c06f3d..cd1628ac7 100644 --- 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 index 4a33a754c..79a35e0ce 100644 --- 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: ``` +Alternatively, to use Gateway API: + +```yaml +ingress: + create: false + +gateway: + create: true # Creates an HTTPRoute resource + hostnames: + - + https: true + parentRefs: + - name: + 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 diff --git a/docs/docs/userguide/PREREQUISITES.md b/docs/docs/userguide/PREREQUISITES.md index 34df1105b..a583e86cf 100644 --- a/docs/docs/userguide/PREREQUISITES.md +++ b/docs/docs/userguide/PREREQUISITES.md @@ -12,7 +12,7 @@ In order to deploy Atlassian’s Data Center products, the following is required Before installing the Data Center Helm charts you need to set up your environment: 1. [Create and connect to the Kubernetes cluster](#create-and-connect-to-the-kubernetes-cluster) -2. [Provision an Ingress Controller](#provision-an-ingress-controller) +2. [Provision an Ingress or Gateway API controller](#provision-an-ingress-or-gateway-api-controller) 3. [Provision a database](#provision-a-database) 4. [Configure a shared-home volume](#configure-a-shared-home-volume) 5. [Configure a local-home volume](#configure-local-home-volume) @@ -30,16 +30,22 @@ Before installing the Data Center Helm charts you need to set up your environmen !!!example "" See examples of [provisioning Kubernetes clusters on cloud-based providers](../examples/cluster/CLOUD_PROVIDERS.md). -### :material-directions-fork: Provision an Ingress Controller + +### :material-directions-fork: Provision an Ingress or Gateway API controller * This step is necessary in order to make your Atlassian product available from outside of the Kubernetes cluster after deployment. -* The Kubernetes project supports and maintains ingress controllers for the major cloud providers including; [AWS](https://github.com/kubernetes-sigs/aws-load-balancer-controller#readme){.external}, [GCE](https://github.com/kubernetes/ingress-gce/blob/master/README.md#readme){.external} and [nginx](https://github.com/kubernetes/ingress-nginx/blob/master/README.md#readme){.external}. There are also a number of open-source [third-party projects available](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/){.external}. -* Because different Kubernetes clusters use different ingress configurations/controllers, the Helm charts provide [Ingress Object](https://kubernetes.io/docs/concepts/services-networking/ingress/){.external} templates only. -* 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` (an alternative controller can be used). -* For more information about the Ingress controller go to the [Ingress section of the configuration guide](CONFIGURATION.md#ingress). +* You can expose the product using either: + * the Kubernetes **Ingress** API (requires an Ingress controller), or + * the Kubernetes **Gateway API** (requires a Gateway API controller). +* For Ingress, the Kubernetes project supports and maintains ingress controllers for the major cloud providers including; [AWS](https://github.com/kubernetes-sigs/aws-load-balancer-controller#readme){.external}, [GCE](https://github.com/kubernetes/ingress-gce/blob/master/README.md#readme){.external} and [nginx](https://github.com/kubernetes/ingress-nginx/blob/master/README.md#readme){.external}. There are also a number of open-source [third-party projects available](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/){.external}. +* For Gateway API, see the Gateway API project docs and the list of implementations: + * Gateway API overview: + * Implementations: +* The Helm charts can create either an `Ingress` (`ingress.create: true`) or an `HTTPRoute` (`gateway.create: true`) resource. These options are mutually exclusive. +* For more information about exposure options and required configuration, see the [Ingress section of the configuration guide](CONFIGURATION.md#ingress). !!!example "" - See an example of [provisioning an NGINX Ingress Controller](../examples/ingress/CONTROLLERS.md). + See examples of [provisioning an NGINX Ingress Controller](../examples/ingress/INGRESS_NGINX.md) and [Gateway API setup](../examples/ingress/GATEWAY_API.md). For an overview, see [Provisioning a traffic entry controller](../examples/ingress/CONTROLLERS.md). ### :material-database: Provision a database diff --git a/docs/gateway-api-session-affinity.md b/docs/gateway-api-session-affinity.md deleted file mode 100644 index 6b855ef0a..000000000 --- a/docs/gateway-api-session-affinity.md +++ /dev/null @@ -1,160 +0,0 @@ -# Session Affinity with Gateway API - -Atlassian DC products (Jira, Confluence, Bitbucket, Bamboo, Crowd) 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** per product (e.g. `ATLROUTE_JIRA`) rather than the application's own `JSESSIONID`. All Atlassian DC products run on Tomcat, which sets `JSESSIONID` to track the user's HTTP session. If the load balancer also uses `JSESSIONID` for routing, the first request creates a race condition: both Envoy and Tomcat emit `Set-Cookie: JSESSIONID` with different values, and on the next request the hash may route to a different pod -- breaking the session. A separate cookie avoids this entirely and mirrors how NGINX Ingress used its own `route` cookie. - -Recommended cookie names: - -| Product | Cookie | -|---|---| -| Jira | `ATLROUTE_JIRA` | -| Confluence | `ATLROUTE_CONFLUENCE` | -| Bitbucket | `ATLROUTE_BITBUCKET` | -| Bamboo | `ATLROUTE_BAMBOO` | -| Crowd | `ATLROUTE_CROWD` | - -## Options at a glance - -| Approach | Cookie-based | Standard channel | Production-ready | -|----------|:---:|:---:|:---:| -| Implementation policy (Option 1) | Yes | N/A (separate CRD) | Yes | -| Experimental `sessionPersistence` (Option 2) | Yes | No (experimental) | Depends on implementation | -| Service `sessionAffinity: ClientIP` (Option 3) | No (IP-based) | Yes | Limited | - ---- - -## Option 1 -- 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. Replace `` with your actual Helm release name. - -### Envoy Gateway - -```yaml -apiVersion: gateway.envoyproxy.io/v1alpha1 -kind: BackendTrafficPolicy -metadata: - name: -session-affinity - namespace: -spec: - targetRefs: - - group: gateway.networking.k8s.io - kind: HTTPRoute - name: - - loadBalancer: - type: ConsistentHash - consistentHash: - type: Cookie - cookie: - name: ATLROUTE_ # e.g. ATLROUTE_JIRA -- see cookie naming above - ttl: 10h -``` - -**Prerequisite:** The Envoy Gateway policy CRDs must be installed. They are included when installing Envoy Gateway via its Helm chart (`gateway-helm`). If you installed Gateway API CRDs separately, you may need to ensure the Envoy Gateway CRDs are also present: - -```bash -kubectl get crd backendtrafficpolicies.gateway.envoyproxy.io -``` - -**References:** -- [Envoy Gateway BackendTrafficPolicy](https://gateway.envoyproxy.io/latest/api/extension_types/#backendtrafficpolicy) -- [Envoy Gateway session persistence task](https://gateway.envoyproxy.io/latest/tasks/traffic/load-balancing/) - -### Istio - -```yaml -apiVersion: networking.istio.io/v1 -kind: DestinationRule -metadata: - name: -session-affinity - namespace: -spec: - host: - - trafficPolicy: - loadBalancer: - consistentHash: - httpCookie: - name: ATLROUTE_ # e.g. ATLROUTE_CONFLUENCE -- see cookie naming above - ttl: 36000s -``` - -> For Istio versions older than 1.22, use `apiVersion: networking.istio.io/v1beta1`. - -**Reference:** [Istio DestinationRule -- ConsistentHashLB](https://istio.io/latest/docs/reference/config/networking/destination-rule/#LoadBalancerSettings-ConsistentHashLB) - -### NGINX Gateway Fabric - -NGINX Gateway Fabric does not currently expose cookie-based session affinity through a policy resource. Use Kubernetes Service-level affinity (Option 3) as a fallback, or check the [NGINX Gateway Fabric documentation](https://docs.nginx.com/nginx-gateway-fabric/) for updates. - ---- - -## Option 2 -- Experimental `sessionPersistence` on HTTPRoute - -The Gateway API project has an **experimental** `sessionPersistence` field on HTTPRoute rules, tracked in [GEP-1619](https://gateway-api.sigs.k8s.io/geps/gep-1619/). This field is **not** included in the standard-channel CRDs and will cause validation errors if those are installed. - -### Step 1: Install experimental-channel CRDs - -```bash -# Replace the version with the Gateway API release you want -kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/experimental-install.yaml -``` - -Check available versions at . - -### Step 2: Add `sessionPersistence` to HTTPRoute rules - -Use the `gateway.additionalRules` value in your Helm values to inject a rule with session persistence: - -```yaml -gateway: - create: true - additionalRules: - - matches: - - path: - type: PathPrefix - value: / - sessionPersistence: - sessionName: ATLROUTE_ # use a dedicated cookie, not JSESSIONID - type: Cookie - absoluteTimeout: 10h - idleTimeout: 1h - backendRefs: - - name: - - port: 80 -``` - -> Not all Gateway implementations support this field yet even with experimental CRDs installed. Check your implementation's conformance report. - -**References:** -- [GEP-1619 -- Session Persistence](https://gateway-api.sigs.k8s.io/geps/gep-1619/) -- [SessionPersistence spec](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.SessionPersistence) - ---- - -## Option 3 -- Kubernetes Service-level affinity (fallback) - -All charts already support `sessionAffinity` on the Kubernetes Service. Set this in your Helm values: - -```yaml -jira: - service: - sessionAffinity: ClientIP - sessionAffinityConfig: - clientIP: - timeoutSeconds: 10800 -``` - -Replace `jira` with the product you are deploying (`confluence`, `bitbucket`, `bamboo`, `crowd`). - -This uses **IP-based** affinity, not cookies. It will not work correctly when multiple users share the same source IP (corporate NAT, proxies, cloud load balancers). - -**Reference:** [Kubernetes Service session affinity](https://kubernetes.io/docs/reference/networking/virtual-ips/#session-affinity) diff --git a/src/main/charts/bamboo/values.yaml b/src/main/charts/bamboo/values.yaml index e7dcc4c80..f702f1a13 100644 --- a/src/main/charts/bamboo/values.yaml +++ b/src/main/charts/bamboo/values.yaml @@ -562,7 +562,7 @@ gateway: # -- Session affinity (sticky sessions) is required for Atlassian DC products but # is not part of the standard Gateway API HTTPRoute spec. It must be configured # separately through your Gateway implementation's own policy resources. - # See docs/gateway-api-session-affinity.md for working examples. + # See docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md for working examples. # -- Timeout configuration for HTTPRoute rules. # Note: when migrating from Ingress, these replace proxyReadTimeout and diff --git a/src/main/charts/bitbucket/values.yaml b/src/main/charts/bitbucket/values.yaml index 3db011d19..cc738b2b2 100644 --- a/src/main/charts/bitbucket/values.yaml +++ b/src/main/charts/bitbucket/values.yaml @@ -639,7 +639,7 @@ gateway: # -- Session affinity (sticky sessions) is required for Atlassian DC products but # is not part of the standard Gateway API HTTPRoute spec. It must be configured # separately through your Gateway implementation's own policy resources. - # See docs/gateway-api-session-affinity.md for working examples. + # See docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md for working examples. # -- Timeout configuration for HTTPRoute rules. # Note: when migrating from Ingress, these replace proxyReadTimeout and diff --git a/src/main/charts/confluence/values.yaml b/src/main/charts/confluence/values.yaml index 027d1aa01..6f80f3184 100644 --- a/src/main/charts/confluence/values.yaml +++ b/src/main/charts/confluence/values.yaml @@ -684,7 +684,7 @@ gateway: # -- Session affinity (sticky sessions) is required for Atlassian DC products but # is not part of the standard Gateway API HTTPRoute spec. It must be configured # separately through your Gateway implementation's own policy resources. - # See docs/gateway-api-session-affinity.md for working examples. + # See docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md for working examples. # -- Timeout configuration for HTTPRoute rules. # Note: when migrating from Ingress, these replace proxyReadTimeout and diff --git a/src/main/charts/crowd/values.yaml b/src/main/charts/crowd/values.yaml index 48f13d495..caede1952 100644 --- a/src/main/charts/crowd/values.yaml +++ b/src/main/charts/crowd/values.yaml @@ -711,7 +711,7 @@ gateway: # -- Session affinity (sticky sessions) is required for Atlassian DC products but # is not part of the standard Gateway API HTTPRoute spec. It must be configured # separately through your Gateway implementation's own policy resources. - # See docs/gateway-api-session-affinity.md for working examples. + # See docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md for working examples. # -- Timeout configuration for HTTPRoute rules. # Note: when migrating from Ingress, these replace proxyReadTimeout and diff --git a/src/main/charts/jira/values.yaml b/src/main/charts/jira/values.yaml index 59eb81713..903371656 100644 --- a/src/main/charts/jira/values.yaml +++ b/src/main/charts/jira/values.yaml @@ -573,7 +573,7 @@ gateway: # -- Session affinity (sticky sessions) is required for Atlassian DC products but # is not part of the standard Gateway API HTTPRoute spec. It must be configured # separately through your Gateway implementation's own policy resources. - # See docs/gateway-api-session-affinity.md for working examples. + # See docs/docs/examples/ingress/GATEWAY_API_SESSION_AFFINITY.md for working examples. # -- Timeout configuration for HTTPRoute rules. # Note: when migrating from Ingress, these replace proxyReadTimeout and