[docs] Improve Secure saved objects and kibana-encryption-keys docs (#…

…132828) (#132878) (cherry picked from commit ef9e3c4) Co-authored-by: Thomas Watson <[email protected]>
elastic · May 25, 2022 · bbc68b6 · bbc68b6
1 parent 84edce8
commit bbc68b6
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 23 deletions.
diff --git a/docs/user/commands/encryption-keys/index.asciidoc b/docs/user/commands/encryption-keys/index.asciidoc
@@ -1,39 +1,35 @@
 [[kibana-encryption-keys]]
 === kibana-encryption-keys
 
-The `kibana-encryption-keys` command helps you set up encryption keys that {kib} uses
+The `kibana-encryption-keys` command helps you generate encryption keys that {kib} uses
 to protect sensitive information.
 
-[discrete]
-=== Synopsis
-
-[source,shell]
---------------------------------------------------
-bin/kibana-encryption-keys generate
-[-i, --interactive] [-q, --quiet]
-[-f, --force] [-h, --help]
---------------------------------------------------
-
-[discrete]
-=== Description
-
 {kib} uses encryption keys in several areas, ranging from encrypting data
 in {kib} associated indices to storing session information. By defining these
 encryption keys in your configuration, you'll ensure consistent operations
 across restarts.
 
 [discrete]
-[[encryption-key-parameters]]
-=== Parameters
-
-`generate`::  Randomly generates passwords to the console.
+=== Usage
 
-`-i, --interactive`:: Prompts you for which encryption keys to set and optionally
-where to save a sample configuration file.
-
-`-q, --quiet`:: Outputs the encryption keys without helper information.
+[source,shell]
+--------------------------------------------------
+bin/kibana-encryption-keys [command] [options]
+--------------------------------------------------
 
-`-f, --force`:: Shows help information.
+[discrete]
+[[encryption-key-parameters]]
+=== Commands
+
+`generate`:: Generate encryption keys.
++
+Unless interactive mode (`-i`) is used, the generated encryption keys will be output to your console only.
+From here, you should manually copy the keys into either `kibana.yml` or where else you're configurating {kib}.
++
+`-i, --interactive`::: Prompts you for which encryption keys to set and optionally where to save a sample configuration file.
+`-q, --quiet`::: Outputs the config options/encryption keys only (without helper information).
+`-f, --force`::: Generates new keys for all settings. By default, only un-configured encryption keys will be generated.
+`-h, --help`::: Shows help information.
 
 [discrete]
 === Examples

diff --git a/docs/user/security/secure-saved-objects.asciidoc b/docs/user/security/secure-saved-objects.asciidoc
@@ -19,6 +19,11 @@ xpack.encryptedSavedObjects:
 If you don't specify an encryption key, {kib} might disable features that rely on encrypted saved objects.
 ============================================================================
 
+[TIP]
+============================================================================
+For help generating the encryption key, refer to the <<kibana-encryption-keys, `kibana-encryption-keys`>> script.
+============================================================================
+
 [[encryption-key-rotation]]
 ==== Encryption key rotation
 
@@ -45,3 +50,17 @@ You might also leverage this functionality if multiple {kib} instances connected
 ============================================================================
 
 At some point, you might want to dispose of old encryption keys completely. Make sure there are no saved objects that {kib} encrypted with these encryption keys. You can use the <<saved-objects-api-rotate-encryption-key, rotate encryption key API>> to determine which existing saved objects require decryption-only keys and re-encrypt them with the primary key.
+
+[[encryption-key-docker-configuration]]
+==== Docker configuration
+
+It's also possible to configure the encryption keys using <<environment-variable-config,Docker environment variables>>.
+
+Docker environment variable examples:
+
+[source,sh]
+--------------------------------------------------------------------------------
+XPACK_ENCRYPTEDSAVEDOBJECTS_ENCRYPTIONKEY="min-32-byte-long-NEW-encryption-key"
+XPACK_ENCRYPTEDSAVEDOBJECTS_KEYROTATION_DECRYPTIONONLYKEYS[0]="min-32-byte-long-OLD#1-encryption-key"
+XPACK_ENCRYPTEDSAVEDOBJECTS_KEYROTATION_DECRYPTIONONLYKEYS[1]="min-32-byte-long-OLD#2-encryption-key"
+--------------------------------------------------------------------------------