helm-docs: add migration guides around PodSecurityPolicy and chart 5.0

Describe how to migrate to Kubernetes 1.25 with the helm chart.
Describe how to migrate from helm chart 4.x to 5.0.

Related to: #5357

Signed-off-by: György Krajcsovits <[email protected]>

docs/sources/helm-charts/mimir-distributed/migration-guides/migrate-helm-chart-4.x-to-5.0.md

@@ -0,0 +1,30 @@
+---
+description: "Migrate the Helm chart from version 4.x to 5.0"
+title: "Migrate the Helm chart from version 4.x to 5.0"
+menuTitle: "Migrate Helm chart 4.x to 5.0"
+weight: 110
+---
+
+# Migrate the Helm chart from version 4.x to 5.0
+
+Grafan Mimir Helm chart version 5.0 and later does not install [PodSecurityPolicy](https://kubernetes.io/docs/concepts/security/pod-security-policy/) objects on Kubernetes version 1.24 by default to prepare for upgrade to Kubernetes version 1.25.
+
+## Prerequisite
+
+- This procedure is only applicable if `rbac.create` is `true` and `rbac.type` is `psp` in your current Helm values. This was the case by default before Helm chart version 5.0.
+
+## Procedure
+
+1. If `rbac.create` is `false` or `rbac.type` is `scc`, then there is nothing to do, skip the whole procedure.
+1. Choose between the following options:
+
+   1. If you are on Kubernetes version 1.24 and want to keep using PodSecurityPolicy, then merge the following setting into your custom values file:
+
+      ```yaml
+      rbac:
+        forcePSPOnKubernetes124: true
+      ```
+
+      > **Note**: Warning: this value prevents you from upgrading to Kubernetes version 1.25! Follow the other option before upgrading to Kubernetes 1.25.
+
+   1. If you have Kubernetes version 1.22 or later and want to upgrade to Kubernetes version 1.25 after this procedure then follow the [Migrate to Kubernetes version 1.25]({{< relref "./migrate-to-kubernetes-version-1.25.md" >}}) guide.

docs/sources/helm-charts/mimir-distributed/migration-guides/migrate-to-kubernetes-version-1.25.md

@@ -0,0 +1,31 @@
+---
+title: "Migrate to Kubernetes version 1.25"
+menuTitle: "Migrate to Kubernetes 1.25"
+description: "Learn how to migrate the Helm chart to Kubernetes version 1.25"
+weight: 10
+---
+
+# Migrate to Kubernetes version 1.25
+
+This procedure describes how to prepare a Grafana Mimir Helm chart deployment for an upgrade to Kubernetes 1.25.
+
+## Background
+
+Kubernetes version 1.25 removes the support for the deprecated [PodSecurityPolicy](https://kubernetes.io/docs/concepts/security/pod-security-policy/) object. You can learn more about this topic by visiting [PodSecurityPolicy Deprecation: Past, Present, and Future](https://kubernetes.io/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).
+
+Due to how Helm [works](https://helm.sh/docs/topics/kubernetes_apis/), PodSecurityPolicy objects must already be removed from the deployment on Kubernetes version 1.24. If you are using PodSecurityPolicy on Kubernetes 1.24, this is a breakind change. Grafana Mimir helm chart versions before 5.0 used PodSecurityPolicy by default.
+
+## Prerequisite
+
+- You have Kubernetes version 1.22, 1.23 or 1.24.
+- This procedure is only applicable if `rbac.create` is `true` and `rbac.type` is `psp` in your current Helm values. This was the case by default before Helm chart version 5.0.
+
+## Procedure
+
+1. If `rbac.create` is `false` or `rbac.type` is `scc`, then there is nothing to do, skip the whole procedure.
+1. Optionally follow the Kubernetes [Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller](https://kubernetes.io/docs/tasks/configure-pod-container/migrate-from-psp/) guide to replace PodSecurityPolicy.
+   > **Note**: Grafana Mimir does not require any special permissions on the hosts that it
+      runs on. Because of this, you can deploy it in environments that enforce the
+      Kubernetes [Restricted security policy](https://kubernetes.io/docs/concepts/security/pod-security-standards/).
+1. Set the `rbac.create` value to `false`.
+1. Upgrade the deployment. The chart will not install PodSecurityPolicy objects anymore.