Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for airgap install of the product documentation #202912

Merged
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions docs/settings/ai-assistant-settings.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
[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-produc-doc-for-airgap]]
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
==== Configuring the product documentation for air-gapped environments
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

The product documentation requires network access to its artifact repository to be installed and enabled.
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What you had was fine, this feels slightly less repetitive

Suggested change
the artifact repository must be manually deployed somewhere accessible by the Kibana deployment.
the artifact repository must be manually deployed somewhere accessible by the {kib} installation.


Deploying a custom product documentation repository can be done in 2 ways: using a s3 bucket, or using a CDN.
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

===== Deploying using a s3 bucket
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

*1. Download the artifacts for your current Kibana version*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

The artifact names are following this pattern: `kb-product-doc-{productName}-{versionMajor}.{versionMinor}.zip`
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

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*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

Upload the artifact files to you custom s3 bucket, then make sure that they are properly listed in the bucket's index, similar to
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
the bucket listing displayed when accessing `https://kibana-knowledge-base-artifacts.elastic.co/` in a browser.

*3. Configure Kibana to use the custom repository*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

Add the following line to your Kibana configuration file:
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

[source,yaml]
----
xpack.productDocBase.artifactRepositoryUrl: "{url-to-my-bucket-root}"
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
----

*4. Restart Kibana*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

You should then be able to install the product documentation feature from the AI assistant management page.

===== Deploying using a CDN
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section uses "we", where the rest of the document uses "you". I think this document should be consistent and use "you"-style language everywhere.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I guess my temperature was different between yesterday and this morning


Deploying using a CDN is quite similar to the s3 bucket approach. The main difference will be that we will need to manually
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
generate the bucket listing and set it as the CDN folder's index page.

*1. Download the artifacts for your current Kibana version*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

Following the step from the `Deploying using a s3 bucket` section
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

*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*

We need to generate the s3 bucket listing xml file for the folder.
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

To do that, copy the following template, and replace the versions in the `<Key>` tags with your current version of Kibana.

pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
For example for Kibana 8.17, replace all `8.16` occurrences in the file with `8.17`.
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

[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 Kibana to use the custom repository*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

Add the following line to your Kibana configuration file:
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

[source,yaml]
----
xpack.productDocBase.artifactRepositoryUrl: "{url-to-my-bucket-root}"
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved
----

*5. Restart Kibana*
pgayvallet marked this conversation as resolved.
Show resolved Hide resolved

You should then be able to install the product documentation feature from the AI assistant management page.
1 change: 1 addition & 0 deletions docs/setup/settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -669,3 +669,4 @@ include::{kibana-root}/docs/settings/spaces-settings.asciidoc[]
include::{kibana-root}/docs/settings/task-manager-settings.asciidoc[]
include::{kibana-root}/docs/settings/telemetry-settings.asciidoc[]
include::{kibana-root}/docs/settings/url-drilldown-settings.asciidoc[]
include::{kibana-root}/docs/settings/ai-assistant-settings.asciidoc[]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list appears to be sorted alphabetically. Should this be moved up to the top?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no idea, but I assume you're right, so moved!