From 5ffe26cbf3e0ef0764a7c296634cd0ed1214b7f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mike=20C=C3=B4t=C3=A9?= <mikecote@users.noreply.github.com>
Date: Tue, 22 Jun 2021 12:30:40 -0400
Subject: [PATCH] Add "Unable to decrypt attribute apiKey" to the alerting
 troubleshooting docs (#101315)

* Initial commit

* PR feedback

* PR feedback pt 2

* PR feedback pt 3
---
 .../alerting-troubleshooting.asciidoc         | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/user/alerting/alerting-troubleshooting.asciidoc b/docs/user/alerting/alerting-troubleshooting.asciidoc
index b7b0c749dfe1..08655508b3cb 100644
--- a/docs/user/alerting/alerting-troubleshooting.asciidoc
+++ b/docs/user/alerting/alerting-troubleshooting.asciidoc
@@ -12,6 +12,32 @@ If your problem isn’t described here, please review open issues in the followi
 
 Have a question? Contact us in the https://discuss.elastic.co/[discuss forum].
 
+[float]
+[[rule-cannot-decrypt-api-key]]
+=== Rule cannot decrypt apiKey
+
+*Problem*:
+
+The rule fails to execute and has an `Unable to decrypt attribute "apiKey"` error.
+
+*Solution*:
+
+This error happens when the `xpack.encryptedSavedObjects.encryptionKey` value used to create the rule does not match the value used during rule execution. Depending on the scenario, there are different ways to solve this problem:
+
+[cols="2*<"]
+|===
+
+| If the value in `xpack.encryptedSavedObjects.encryptionKey` was manually changed, and the previous encryption key is still known.
+| Ensure any previous encryption key is included in the keys used for <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, decryption only>>.
+
+| If another {kib} instance with a different encryption key connects to the cluster.
+| The other {kib} instance might be trying to run the rule using a different encryption key than what the rule was created with. Ensure the encryption keys among all the {kib} instances are the same, and setting <<xpack-encryptedSavedObjects-keyRotation-decryptionOnlyKeys, decryption only keys>> for previously used encryption keys.
+
+| If other scenarios don't apply.
+| Generate a new API key for the rule by disabling then enabling the rule.
+
+|===
+
 [float]
 [[rules-small-check-interval-run-late]]
 === Rules with small check intervals run late
@@ -29,7 +55,6 @@ Either tweak the <<task-manager-settings,{kib} Task Manager settings>> or increa
 
 For more details, see <<task-manager-health-scheduled-tasks-small-schedule-interval-run-late>>.
 
-
 [float]
 [[scheduled-rules-run-late]]
 === Rules run late