[8.x] Add documentation for airgap install of the product documentation (#202912) (#203302)

# Backport This will backport the following commits from `main` to `8.x`: - [Add documentation for airgap install of the product documentation (#202912)](https://github.com/elastic/kibana/pull/202912)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Pierre Gayvallet <pierre.gayvallet@elastic.co>
2025-04-23 09:19:04 -04:00 · 2024-12-07 05:47:46 +11:00 · 2024-12-07 05:47:46 +11:00 · 32d0514264
commit 32d0514264
parent 1cf60d57ac
3 changed files with 119 additions and 0 deletions
--- a/docs/settings/ai-assistant-settings.asciidoc
+++ b/docs/settings/ai-assistant-settings.asciidoc
@ -0,0 +1,117 @@
+[role="xpack"]
+[[ai-assistant-settings-kb]]
+=== AI Assistant settings in {kib}
++++
+<titleabbrev>AI Assistant settings</titleabbrev>
++++
+
+`xpack.productDocBase.artifactRepositoryUrl`::
+Url of the repository to use to download and install the Elastic product documentation artifacts for the AI assistants.
+Defaults to `https://kibana-knowledge-base-artifacts.elastic.co`
+
+[[configuring-product-doc-for-airgap]]
+==== Configuring product documentation for air-gapped environments
+
+Installing product documentation requires network access to its artifact repository.
+For air-gapped environments, or environments where remote network traffic is blocked or filtered,
+the artifact repository must be manually deployed somewhere accessible by the Kibana deployment.
+
+Deploying a custom product documentation repository can be done in 2 ways: using a S3 bucket, or using a CDN.
+
+===== Deploying using a S3 bucket
+
+*1. Download the artifacts for your current {kib} version*
+
+The artifact names follow this pattern: `kb-product-doc-{productName}-{versionMajor}.{versionMinor}.zip`
+
+The available products are:
+- elasticsearch
+- kibana
+- observability
+- security
+
+You must download, from the source repository (`https://kibana-knowledge-base-artifacts.elastic.co/`), 
+the artifacts for your current version of Kibana. 
+
+For example, for Kibana 8.16:
+- `kb-product-doc-elasticsearch-8.16.zip`
+- `kb-product-doc-kibana-8.16.zip`
+- `kb-product-doc-observability-8.16.zip`
+- `kb-product-doc-security-8.16.zip`
+
+*2. Upload the artifacts to your local S3 bucket*
+
+Upload the artifact files to your custom S3 bucket, then make sure that they are properly listed in the bucket's index, similar to
+the bucket listing displayed when accessing `https://kibana-knowledge-base-artifacts.elastic.co/` in a browser.
+
+*3. Configure {kib} to use the custom repository*
+
+Add the following line to your {kib} configuration file:
+
+[source,yaml]
+----
+# Replace with the root of your custom bucket
+xpack.productDocBase.artifactRepositoryUrl: "https://my-custom-repository.example.com"
+----
+
+*4. Restart {kib}*
+
+You should then be able to install the product documentation feature from the AI assistant management page.
+
+===== Deploying using a CDN
+
+Deploying using a CDN is quite similar to the S3 bucket approach. The main difference will be that we will need to manually
+generate the bucket listing and set it as the CDN folder's index page.
+
+*1. Download the artifacts for your current {kib} version*
+
+Following the step from the `Deploying using a S3 bucket` section
+
+*2. Upload the artifacts to the CDN*
+
+Create a folder in your CDN, and upload the artifacts to it.
+
+*3. Create and upload the bucket listing*
+
+Generate the S3 bucket listing xml file for the folder.
+
+To do that, copy the following template, and replace the versions in the `<Key>` tags with your current version of {kib}.
+
+For example for {kib} 8.17, replace all `8.16` occurrences in the file with `8.17`. 
+
+[source,xml]
+----
+<ListBucketResult>
+    <Name>kibana-ai-assistant-kb-artifacts</Name>
+    <IsTruncated>false</IsTruncated>
+    <Contents>
+        <Key>kb-product-doc-elasticsearch-8.16.zip</Key>
+    </Contents>
+    <Contents>
+        <Key>kb-product-doc-kibana-8.16.zip</Key>
+    </Contents>
+    <Contents>
+        <Key>kb-product-doc-observability-8.16.zip</Key>
+    </Contents>
+    <Contents>
+        <Key>kb-product-doc-security-8.16.zip</Key>
+    </Contents>
+</ListBucketResult>
+----
+
+Then upload that xml file to the same CDN folder where the artifacts were uploaded, and then configure the folder to have that file
+served as the folder's index.
+
+*4. Configure {kib} to use the custom repository*
+
+Add the following line to your {kib} configuration file:
+
+[source,yaml]
+----
+# Replace with the path to the CDN folder previously configured
+xpack.productDocBase.artifactRepositoryUrl: "https://my-custom-repository.example.com"
+----
+
+*5. Restart {kib}*
+
+You should then be able to install the product documentation feature from the AI assistant management page.
--- a/docs/setup/settings.asciidoc
+++ b/docs/setup/settings.asciidoc
@ -650,6 +650,7 @@ Set this value to false to disable the Upgrade Assistant UI. *Default: true*
 Set this value to change the {kib} interface language.
 Valid locales are: `en`, `zh-CN`, `ja-JP`, `fr-FR`. *Default: `en`*

+include::{kibana-root}/docs/settings/ai-assistant-settings.asciidoc[]
 include::{kibana-root}/docs/settings/alert-action-settings.asciidoc[leveloffset=+1]
 include::{kibana-root}/docs/settings/apm-settings.asciidoc[]
 include::{kibana-root}/docs/settings/banners-settings.asciidoc[]
--- a/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker
+++ b/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker
@ -319,6 +319,7 @@ kibana_vars=(
    xpack.observability.unsafe.alertDetails.uptime.enabled
    xpack.observability.unsafe.alertDetails.observability.enabled
    xpack.observability.unsafe.thresholdRule.enabled
+    xpack.productDocBase.artifactRepositoryUrl
    xpack.reporting.capture.browser.autoDownload
    xpack.reporting.capture.browser.chromium.disableSandbox
    xpack.reporting.capture.browser.chromium.inspect