Document manual steps for reconfiguring role mappings after upgrading…

… to ECK 8.15.3 (#8112)

This documents the manual steps for reconfiguring role mappings after upgrading to ECK 8.15.3:
- introduce a new section in the doc to outline manual steps required after upgrading from 8.14.x or 8.15.x
- update 'role_mappings_warning' to reference the new section for clarity

docs/eck-attributes.asciidoc

@@ -4,4 +4,4 @@
 :eck_github: https://github.com/elastic/cloud-on-k8s
 :eck_resources_list: Elasticsearch, Kibana, APM Server, Enterprise Search, Beats, Elastic Agent, Elastic Maps Server, and Logstash
 
-:role_mappings_warning: We have identified an issue with Elasticsearch 8.15 that prevents security role mappings configured via Stack configuration policies to work correctly. The only workaround is to specify the security role mappings via the link:https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html[Elasticsearch REST API]. After an upgrade from a previous Elasticsearch version to 8.15 role mappings will be preserved but will not receive future updates from the Stack configuration policy. We are working on a fix to restore the functionality in a future Elasticsearch release.
+:role_mappings_warning: We have identified an issue with Elasticsearch 8.15.1 and 8.15.2 that prevents security role mappings configured via Stack configuration policies to work correctly. The only workaround is to specify the security role mappings via the link:https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html[Elasticsearch REST API]. After upgrading to these versions role mappings will be preserved but will not receive future updates from the Stack configuration policy. Follow the instructions to <<{p}-common-problems-815-reconfigure-role-mappings, reconfigure role mappings after upgrading to 8.15.3>>.

docs/operating-eck/troubleshooting/common-problems.asciidoc

@@ -260,3 +260,66 @@ If you accidentally upgrade one of your Elasticsearch clusters to a version that
 The reason for this validation is that ECK will not allow downgrades as this is not supported by Elasticsearch and once the data directory of Elasticsearch has been upgraded there is no way back to the old version without a link:https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html[snapshot restore].
 
 These two upgrading scenarios, however, are exceptions because Elasticsearch never started up successfully. If you annotate the Elasticsearch resource with `eck.k8s.elastic.co/disable-downgrade-validation=true` ECK allows you to go back to the old version at your own risk. If you also attempted an upgrade of other related Elastic Stack applications at the same time you can use the same annotation to go back. Remove the annotation afterwards to prevent accidental downgrades and reduced availability.
+
+[id="{p}-{page_id}-815-reconfigure-role-mappings"]
+== Reconfigure stack config policy based role mappings after an upgrade to 8.15.3 from 8.14.x or 8.15.x
+
+You have role mappings defined in a StackConfigPolicy, and you upgraded from 8.14.x or 8.15.x, to 8.15.3.
+
+Examples:
+
+- 8.14.2 -> 8.15.2 -> 8.15.3
+- 8.14.2 -> 8.15.3
+- 8.15.2 -> 8.15.3
+
+You have to perform two manual steps in order to correctly reconfigure role mappings because due to a bug the role mappings were duplicated.
+
+. Force reload the StackConfigPolicy configuration
+
+Force reload the StackConfigPolicy configuration containing the role mappings definition, by adding metadata to any of the mappings:
+
+[source,yaml]
+----
+apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1
+kind: StackConfigPolicy
+spec:
+  elasticsearch:
+    securityRoleMappings:
+      <roleName>:
+        metadata:
+          force_reload: anything # add a dummy metadata to force reload the config
+----
+
+Check that the role mapping is now in the cluster state:
+
+[source,sh]
+----
+GET /_cluster/state/metadata?filter_path=metadata.role_mappings.role_mappings
+{"metadata":{"role_mappings":{"role_mappings":[{"enabled":true,"roles":["superuser"],"rules":{"all":[{"field":{"realm.name":"oidc1"}},{"field":{"username":"*"}}]},"metadata":{"force_reload":"dummy"}}]}}}
+----
+
+. Remove duplicated role mappings exposed via the API
+
+Start by listing all the role mappings defined in your StackConfigPolicy:
+
+[source,sh]
+----
+kubectl get scp <scpName> -o json | jq '.spec.elasticsearch.securityRoleMappings | to_entries[].key' -r
+<roleName>
+----
+
+Delete each role:
+
+[source,sh]
+----
+DELETE /_security/role_mapping/<roleName>
+{"found": true}
+----
+
+Check that the role mapping was deleted:
+
+[source,sh]
+----
+GET /_security/role_mapping/<roleName>
+{}
+----