Add known issue for PGP key access problem (#470) (#472)

* Add known issue for PGP key access problem

* Add link to repos docs

(cherry picked from commit 42ff6b2)

Co-authored-by: David Kilfoyle <[email protected]>

Author: mergify[bot]

docs/en/ingest-management/release-notes/release-notes-8.9.asciidoc

@@ -91,6 +91,76 @@ Review important information about the {fleet} and {agent} 8.9.0 release.
 {fleet-server}::
 * Use a verified base image for building Fleet Server binaries. {fleet-server-pull}2339[#2339]
 
+
+
+
+
+
+
+[discrete]
+[[known-issues-8.9.0]]
+=== Known issues
+
+[[known-issue-3375]]
+.PGP key download fails in an air-gapped environment
+[%collapsible]
+====
+
+*Details*
+
+Starting from version 8.9.0, when {agent} tries to perform an upgrade, it first verifies the binary signature with the key bundled in the agent.
+This process has a backup mechanism that will use the key coming from `https://artifacts.elastic.co/GPG-KEY-elastic-agent` instead of the one it already has.
+
+In an air-gapped environment, the Agent won't be able to download the remote key and therefore cannot be upgraded.
+
+*Impact* +
+
+As a workaround,  the agent needs to download the remote key from a server accessible from the air-gapped environment.
+As this URL is not customizable, we have to "trick" the system by pointing `https://artifacts.elastic.co/` to another host that will have the file.
+
+The following examples require a server in your air-gapped environment that will expose the key you will have downloaded from `https://artifacts.elastic.co/GPG-KEY-elastic-agent``.
+
+*Example 1: Manual*
+
+Edit the {agent} server hosts file to add the following content:
+
+[source,sh]
+----
+<YOUR_HOST_IP> artifacts.elastic.co
+----
+
+The Linux hosts file path is `/etc/hosts`.
+
+Windows hosts file path is `C:\Windows\System32\drivers\etc\hosts`.
+
+*Example 2: Puppet*
+
+[source,yaml]
+----
+host { 'elastic-artifacts':
+  ensure       => 'present'
+  comment      => 'Workaround for PGP check'
+  ip           => '<YOUR_HOST_IP>'
+}
+----
+
+*Example 3: Ansible*
+
+[source,yaml]
+----
+- name  : 'elastic-artifacts'
+  hosts : 'all'
+  become: 'yes'  
+
+  tasks:
+    - name: 'Add entry to /etc/hosts'
+      lineinfile:
+        path: '/etc/hosts'
+        line: '<YOUR_HOST_IP> artifacts.elastic.co'
+----
+
+====
+
 [discrete]
 [[breaking-changes-8.9.0]]
 === Breaking changes

docs/en/ingest-management/troubleshooting/troubleshooting.asciidoc

@@ -648,3 +648,10 @@ curl -u elastic:<password> --request POST \
   --header 'Content-Type: application/json' \
   --header 'kbn-xsrf: xyz' \
 ----
+
+[discrete]
+[[php-key-download-fail]]
+== Air-gapped {agent} upgrade can fail due to an inaccessible PGP key
+
+In versions 8.9 and above, an {agent} upgrade may fail when the upgrader can't access a PGP key required to verify the binary signature. For details and a workaround, refer to the <<known-issue-3375,PGP key download fails in an air-gapped environment>> known issue in the version 8.9.0 Release Notes or to the link:https://github.com/elastic/elastic-agent/blob/main/docs/pgp-workaround.md[workaround documentation] in the elastic-agent GitHub repository.
+