docs(helm): Document 6.46.0 default service-account name change (#21832)

docs/sources/setup/upgrade/_index.md

@@ -100,6 +100,36 @@ If you prefixed the sidecar container with a private registry (`sidecar.image.re
 For most images used in the helm chart, a `.digest` is available to pin an image to a specific hash. The sidecar images diverges from this convention by introducing a `.tag`.
 Starting with Helm chart 6.46.1, the `.tag` is deprecated and `.digest` should be used.
 
+### Helm Chart 6.46.0 - Default service account name change
+
+{{< admonition type="warning" >}}
+Helm chart version 6.46.0 introduces a **breaking change** that affects users who rely on the default service account name to bind external identity, such as AWS EKS Pod Identity, IAM Roles for Service Accounts (IRSA), GCP Workload Identity, or Azure Workload Identity.
+{{< /admonition >}}
+
+Starting with Helm chart 6.46.0 ([#19590](https://github.com/grafana/loki/pull/19590)), when `serviceAccount.create` is `true` and `serviceAccount.name` is not set, the default service account name is now derived from the chart's *fullname* template instead of the chart *name*. For example:
+
+| Deployment | Default service account name before 6.46.0 | Default service account name in 6.46.0 and later |
+|---|---|---|
+| Grafana Enterprise Logs (GEL) | `enterprise-logs` | `<release-name>-enterprise-logs` |
+| Open source Loki | `loki` | `<release-name>-loki` |
+
+If an external identity, such as an AWS IAM role through EKS Pod Identity or IRSA, is bound to the previous service account name, your pods lose access to that identity after the upgrade. For object-storage backends, this typically results in an outage because Loki components can no longer read or write to the bucket.
+
+**Recommended action**:
+
+To preserve the previous behavior and avoid the rename, set the service account name explicitly in your `values.yaml`:
+
+```yaml
+serviceAccount:
+  name: enterprise-logs   # use "loki" for open source deployments
+```
+
+Setting `serviceAccount.name` explicitly is forward-compatible and works on both pre- and post-6.46.0 chart versions, so it is also the recommended setting going forward if you want the service account name to be independent of the Helm release name.
+
+If you have already upgraded and your pods have lost cloud-provider IAM access, you have two options:
+- Set `serviceAccount.name` to the previous default (for example, `enterprise-logs`) and run `helm upgrade` again. The previously bound external identity will resume working.
+- Update the external identity binding (for example, the EKS Pod Identity association or the IRSA trust policy) to reference the new service account name.
+
 ### Helm Chart 6.34.0 - Zone-aware Ingester Breaking Change
 
 {{< admonition type="warning" >}}

production/helm/loki/CHANGELOG.md

@@ -95,7 +95,7 @@ Entries should include a reference to the pull request that introduced the chang
 
 ## 6.46.0
 
-- [CHANGE] `nameOverride` now passed through Helm template function. [#19590](https://github.com/grafana/loki/pull/19590)
+- [BREAKING] `nameOverride` now passed through Helm template function. [#19590](https://github.com/grafana/loki/pull/19590) This PR also changed the default service account name from the chart *name* (`enterprise-logs` / `loki`) to the chart *fullname* (`<release>-enterprise-logs` / `<release>-loki`) when `serviceAccount.create: true` and `serviceAccount.name` is unset. This breaks external identity bindings (for example, AWS EKS Pod Identity, IRSA, GCP Workload Identity, Azure Workload Identity) that reference the previous default name. To preserve the previous behavior, set `serviceAccount.name` explicitly. See the [upgrade guide](https://grafana.com/docs/loki/latest/setup/upgrade/#helm-chart-6460---default-service-account-name-change) for details.
 - [FEATURE] Add configurable `singleBinary.topologySpreadConstraints`. [#19534](https://github.com/grafana/loki/pull/19534)
 - [FEATURE] Add load balancer port to query-frontend service. [#19462](https://github.com/grafana/loki/pull/19462)
 - [FEATURE] Make loki-canary readinessProbe configurable via values.yaml. [#19328](https://github.com/grafana/loki/pull/19328)