From e6af3b49299d745db4c7c4d2e881139bfb552bd4 Mon Sep 17 00:00:00 2001
From: David Kilfoyle <david.kilfoyle@elastic.co>
Date: Wed, 14 Feb 2024 11:05:02 -0500
Subject: [PATCH] Fix known issue for stuck upgrade in 8.12.1 release notes

---
 .../release-notes/release-notes-8.12.asciidoc | 60 ++++++++++++++-----
 1 file changed, 45 insertions(+), 15 deletions(-)

diff --git a/docs/en/ingest-management/release-notes/release-notes-8.12.asciidoc b/docs/en/ingest-management/release-notes/release-notes-8.12.asciidoc
index 79806d67e..3e62a8c22 100644
--- a/docs/en/ingest-management/release-notes/release-notes-8.12.asciidoc
+++ b/docs/en/ingest-management/release-notes/release-notes-8.12.asciidoc
@@ -147,32 +147,60 @@ An issue discovered in {fleet-server} prevents {agents} that have been upgraded
 
 *Impact* +
 
-As a workaround, we recommend you to use the {kib} {fleet} API to upgrade these agents using the `force` flag.
+As a workaround, we recommend you to use the {kib} {fleet} API to update any documents in which `upgrade_details` is either `null` or not defined. Note that these steps must be run as a superuser.
 
-To upgrade a single {agent}:
+[source,"shell"]
+----
+ POST _security/role/fleet_superuser
+ {
+    "indices": [
+        {
+            "names": [".fleet*",".kibana*"],
+            "privileges": ["all"],
+            "allow_restricted_indices": true
+        }
+    ]
+  }
+----
 
 [source,"shell"]
 ----
-POST kbn:/api/fleet/agents/<agent_id>/upgrade
-{
-  "version": "8.12.1",
-  "force": true
-}
+POST _security/user/fleet_superuser 
+ {
+    "password": "password",
+    "roles": ["superuser", "fleet_superuser"]
+ }
 ----
 
-To bulk upgrade a set of {agents}:
+[source,"shell"]
+----
+curl -sk -XPOST --user fleet_superuser:password -H 'content-type:application/json' \
+  -H'x-elastic-product-origin:fleet' \
+  http://localhost:9200/.fleet-agents/_update_by_query \
+  -d '{
+  "script": {
+    "source": "ctx._source.remove(\"upgrade_details\")",
+    "lang": "painless"
+  },
+  "query": {
+    "bool": {
+        "must_not": {
+          "exists": {
+            "field": "upgrade_details"
+          }
+        }
+      }
+    }
+}'
+----
 
 [source,"shell"]
 ----
-POST kbn:/api/fleet/agents/bulk_upgrade
-  {
-    "agents": "agent.version:8.12.0",
-    "version": "8.12.1",
-    "force": true
-  }
+DELETE _security/user/fleet_superuser
+DELETE _security/role/fleet_superuser
 ----
 
-This issue is planned to be fixed in versions 8.12.2 and 8.13.0.
+After running these API requests, wait at least 10 minutes, and then the agents should be upgradeable again.
 
 ====
 
@@ -514,6 +542,8 @@ curl -sk -XPOST --user fleet_superuser:password -H 'content-type:application/jso
 DELETE _security/user/fleet_superuser
 DELETE _security/role/fleet_superuser
 ----
+
+After running these API requests, wait at least 10 minutes, and then the agents should be upgradeable again.
 ====
 
 [discrete]