docs(record-encryption): pull out key creation to the top-level of the guide.

k-wall · k-wall · commit c1a47285ceb3 · 2025-12-18T20:57:25.000Z
why: key creation is a day two operation and not really related to KMS setup
Signed-off-by: Keith Wall &lt;kwall@apache.org&gt;
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/assembly-kms-key-creation.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/assembly-kms-key-creation.adoc
@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+
+// record-encryption-guide/index.adoc
+
+[id='assembly-kms-key-creation-{context}']
+= Creating Keys
+
+[role="_abstract"]
+This section assumes that you already have a supported KMS instance up and running and have configured the Record Encryption filter.
+It describes how to create the keys in the KMS that will be used to encrypt records sent to the topics.
+
+include::hashicorp-vault/assembly-key-creation-hashicorp-vault.adoc[leveloffset=+1]
+include::aws-kms/assembly-key-creation-aws-kms.adoc[leveloffset=+1]
+include::azure-key-vault/assembly-key-creation-azure-key-vault.adoc[leveloffset=+1]
+ifdef::include-fortanix-dsm-kms[]
+include::fortanix-dsm/assembly-key-creation-fortanix-dsm.adoc[leveloffset=+1]
+endif::[]
+
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/aws-kms/assembly-key-creation-aws-kms.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/aws-kms/assembly-key-creation-aws-kms.adoc
@@ -0,0 +1,15 @@
+:_mod-docs-content-type: ASSEMBLY
+
+// file included in the following:
+//
+// assembly-kms-key-creation.adoc
+
+[id='assembly-key-creation-aws-kms-{context}']
+= Creating keys in AWS KMS
+
+[role="_abstract"]
+To create a key in AWS Key Management Service for use with the Record Encryption filter, use the following procedure.
+
+You'll need a privileged AWS user that is capable of creating keys.
+
+include::../../../_modules/record-encryption/aws-kms/proc-aws-kms-key-creation.adoc[leveloffset=+1]
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/aws-kms/assembly-preparing-aws-kms.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/aws-kms/assembly-preparing-aws-kms.adoc
@@ -2,7 +2,7 @@
 
 // file included in the following:
 //
-// assembly-record-encryption-filter.adoc
+// assembly-kms-preparing.adoc
 
 [id='assembly-preparing-aws-kms-{context}']
 = Preparing AWS KMS
@@ -11,9 +11,9 @@
 To prepare {aws}/kms/latest/developerguide/overview.html[AWS Key Management Service] for use with the Record Encryption filter, use the following setup:
 
 * Establish an AWS KMS aliasing convention for keys
-* Create AWS KMS keys
+* Create a policies giving permissions to the key aliases
+* Create a user for use by the filter and attach the policies to it.
 
 You'll need a privileged AWS user that is capable of creating users and policies to perform the set-up.
 
 include::../../../_modules/record-encryption/aws-kms/con-aws-kms-setup.adoc[leveloffset=+1]
-include::../../../_modules/record-encryption/aws-kms/proc-aws-kms-key-creation.adoc[leveloffset=+1]
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/azure-key-vault/assembly-key-creation-azure-key-vault.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/azure-key-vault/assembly-key-creation-azure-key-vault.adoc
@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+
+// file included in the following:
+//
+// assembly-kms-key-creation.adoc
+
+[id='assembly-key-creation-azure-key-vault-{context}']
+= Creating keys in Azure Key Vault
+
+[role="_abstract"]
+To create a key in Azure Key Vault for use with the Record Encryption filter, use the following procedure.
+
+You'll need a privileged Azure user that is capable of creating key resources to perform the set-up.
+
+include::../../../_modules/record-encryption/azure-key-vault/proc-azure-key-vault-key-creation.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://learn.microsoft.com/en-us/azure/key-vault/general/overview[Azure Key Vault overview^]
+* link:https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices[Azure Key Vault security best practices^]
+* link:https://learn.microsoft.com/en-us/azure/key-vault/keys/about-keys[Azure Key Vault keys^]
+* link:https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-access-policy[Azure Key Vault access control using RBAC^]
+* link:https://learn.microsoft.com/en-us/azure/role-based-access-control/scope-overview[Azure role-based access control scopes^]
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/azure-key-vault/assembly-preparing-azure-key-vault.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/azure-key-vault/assembly-preparing-azure-key-vault.adoc
@@ -2,7 +2,7 @@
 
 // file included in the following:
 //
-// assembly-record-encryption-filter.adoc
+// assembly-kms-preparing.adoc
 
 [id='assembly-preparing-azure-key-vault-{context}']
 = Preparing Azure Key Vault
@@ -12,12 +12,10 @@ To prepare Azure Key Vault for use with the Record Encryption filter, use the fo
 
 * Setup Azure resources
 * Establish a naming convention for keys
-* Create Azure Key Vault keys
 
 You'll need a privileged Azure user that is capable of creating users and resources to perform the set-up.
 
 include::../../../_modules/record-encryption/azure-key-vault/proc-azure-key-vault-setup.adoc[leveloffset=+1]
-include::../../../_modules/record-encryption/azure-key-vault/proc-azure-key-vault-key-creation.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/fortanix-dsm/assembly-key-creation-fortanix-dsm.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/fortanix-dsm/assembly-key-creation-fortanix-dsm.adoc
@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+
+// file included in the following:
+//
+// assembly-kms-key-creation.adoc
+
+[id='assembly-key-creation-fortanix-dsm-{context}']
+= Creating keys in Fortanix Data Security Manager (DSM)
+
+[role="_abstract"]
+To create a key in Fortanix Data Security Manager (DSM) for use with the Record Encryption filter, use the following procedure.
+
+include::../../../_modules/record-encryption/fortanix-dsm/proc-fortanix-dsm-key-creation.adoc[leveloffset=+1]
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/fortanix-dsm/assembly-preparing-fortanix-dsm.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/fortanix-dsm/assembly-preparing-fortanix-dsm.adoc
@@ -2,7 +2,7 @@
 
 // file included in the following:
 //
-// assembly-record-encryption-filter.adoc
+// assembly-kms-preparing.adoc
 
 [id='assembly-preparing-fortanix-dsm-{context}']
 = Preparing Fortanix Data Security Manager (DSM)
@@ -12,7 +12,5 @@ To prepare Fortanix Data Security Manager (DSM) for use with the Record Encrypti
 
 * Establish a naming convention for keys and choose a Fortanix group where the keys will reside.
 * Create an application identity, with an API key, for the Record Encryption filter.
-* Create Fortanix DSM keys.
 
 include::../../../_modules/record-encryption/fortanix-dsm/con-fortanix-dsm-setup.adoc[leveloffset=+1]
-include::../../../_modules/record-encryption/fortanix-dsm/proc-fortanix-dsm-key-creation.adoc[leveloffset=+1]
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/hashicorp-vault/assembly-key-creation-hashicorp-vault.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/hashicorp-vault/assembly-key-creation-hashicorp-vault.adoc
@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+
+// file included in the following:
+//
+// assembly-kms-key-creation.adoc
+
+[id='assembly-key-creation-hashicorp-vault-{context}']
+= Creating keys in HashiCorp Vault
+
+[role="_abstract"]
+To create a key in HashiCorp Vault for use with the Record Encryption filter, use the following procedure.
+
+include::../../../_modules/record-encryption/hashicorp-vault/proc-vault-key-creation.adoc[leveloffset=+1]
diff --git a/kroxylicious-docs/docs/_assemblies/record-encryption/hashicorp-vault/assembly-preparing-hashicorp-vault.adoc b/kroxylicious-docs/docs/_assemblies/record-encryption/hashicorp-vault/assembly-preparing-hashicorp-vault.adoc
@@ -2,7 +2,7 @@
 
 // file included in the following:
 //
-// assembly-record-encryption-filter.adoc
+// assembly-kms-preparing.adoc
 
 [id='assembly-preparing-hashicorp-vault-{context}']
 = Preparing HashiCorp Vault
@@ -15,5 +15,3 @@ To use HashiCorp Vault with the Record Encryption filter, use the following setu
 * Obtain a Vault token that includes the filter policy.
 
 include::../../../_modules/record-encryption/hashicorp-vault/con-vault-setup.adoc[leveloffset=+1]
-
-include::../../../_modules/record-encryption/hashicorp-vault/proc-vault-key-creation.adoc[leveloffset=+1]
diff --git a/kroxylicious-docs/docs/record-encryption-guide/index.adoc b/kroxylicious-docs/docs/record-encryption-guide/index.adoc
@@ -43,6 +43,9 @@ include::_assemblies/record-encryption/assembly-kms-preparing.adoc[leveloffset=+
 //configuring the record encryption filter
 include::_assemblies/record-encryption/assembly-configuring-record-encryption-filter.adoc[leveloffset=+1]
 
+// key creation (might be done by a KMS key manager)
+include::_assemblies/record-encryption/assembly-kms-key-creation.adoc[leveloffset=+1]
+
 //monitoring the record encryption filter
 include::_assemblies/record-encryption/assembly-monitoring-record-encryption-filter.adoc[leveloffset=+1]
 
