CNV- 10120: dynamic SSH keys

Signed-off-by: Avital Pinnick <[email protected]>

Author: apinnick

modules/virt-about-static-and-dynamic-ssh-keys.adoc

@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virt-accessing-vm-ssh.adoc
+
+:_content-type: REFERENCE
+[id="virt-about-static-and-dynamic-ssh-keys_{context}"]
+= About static and dynamic SSH key management
+
+You can add public SSH keys to virtual machines (VMs) statically at first boot or dynamically at runtime.
+
+[NOTE]
+====
+Only {op-system-base-full} 9 supports dynamic key injection.
+====
+
+[discrete]
+[id="static-key-management_{context}"]
+== Static SSH key management
+
+You can add a statically managed SSH key to a VM with a guest operating system that supports configuration by using a cloud-init data source. The key is added to the virtual machine (VM) at first boot.
+
+You can add the key by using one of the following methods:
+
+* Add a key to a single VM when you create it by using the web console or the command line.
+* Add a key to a project by using the web console. Afterwards, the key is automatically added to the VMs that you create in this project.
+
+.Use cases
+
+* As a VM owner, you can provision all your newly created VMs with a single key.
+
+[discrete]
+[id="dynamic-key-management_{context}"]
+== Dynamic SSH key management
+
+You can enable dynamic SSH key management for a VM with {op-system-base-full} 9 installed. Afterwards, you can update the key during runtime. The key is added by the QEMU guest agent, which is installed with Red Hat boot sources.
+
+You can disable dynamic key management for security reasons. Then, the VM inherits the key management setting of the image from which it was created.
+
+.Use cases
+
+* Granting or revoking access to VMs: As a cluster administrator, you can grant or revoke remote VM access by adding or removing the keys of individual users from a `Secret` object that is applied to all VMs in a namespace.
+* User access: You can add your access credentials to all VMs that you create and manage.
+
+* Ansible provisioning:
+
+** As an operations team member, you can create a single secret that contains all the keys used for Ansible provisioning.
+** As a VM owner, you can create a VM and attach the keys used for Ansible provisioning.
+
+* Key rotation:
+
+** As a cluster administrator, you can rotate the Ansible provisioner keys used by VMs in a namespace.
+** As a workload owner, you can rotate the key for the VMs that you manage.

modules/virt-access-configuration-considerations.adoc

@@ -16,6 +16,7 @@ If the internal cluster network cannot handle the traffic load, you can configur
 * Simple to configure.
 * Recommended for troubleshooting VMs.
 * `virtctl port-forwarding` recommended for automated configuration of VMs with Ansible.
+* Dynamic public SSH keys can be used to provision VMs with Ansible.
 * Not recommended for high-traffic applications like Rsync or Remote Desktop Protocol because of the burden on the API server.
 * The API server must be able to handle the traffic load.
 * The clients must be able to access the API server.
@@ -38,4 +39,3 @@ Secondary network::
 * Allows a flexible approach to network topology.
 * Guest operating system must be configured with appropriate security because the VM is exposed directly to the secondary network. If a VM is compromised, an intruder could gain access to the secondary network.
 
-

modules/virt-adding-key-creating-vm-template.adoc

@@ -0,0 +1,77 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virt-accessing-vm-ssh.adoc
+
+ifeval::["{context}" == "static-key"]
+:static-key:
+:title: Adding a key
+endif::[]
+ifeval::["{context}" == "dynamic-key"]
+:dynamic-key:
+:title: Enabling dynamic key injection
+endif::[]
+
+:_content-type: PROCEDURE
+[id="virt-adding-key-creating-vm-template_{context}"]
+= {title} when creating a VM from a template
+
+ifdef::static-key[]
+You can add a statically managed public SSH key when you create a virtual machine (VM) by using the {product-title} web console. The key is added to the VM as a cloud-init data source at first boot. This method does not affect cloud-init user data.
+
+Optional: You can add a key to a project. Afterwards, this key is added automatically to VMs that you create in the project.
+endif::[]
+ifdef::dynamic-key[]
+You can enable dynamic public SSH key injection when you create a virtual machine (VM) from a template by using the {product-title} web console. Then, you can update the key at runtime.
+
+[NOTE]
+====
+Only {op-system-base-full} 9 supports dynamic key injection.
+====
+
+The key is added to the VM by the QEMU guest agent, which is installed with {op-system-base} 9.
+endif::[]
+
+.Prerequisites
+
+* You generated an SSH key pair by running the `ssh-keygen` command.
+
+.Procedure
+
+. Navigate to *Virtualization* -> *Catalog* in the web console.
+ifdef::dynamic-key[]
+. Click the *Red Hat Enterprise Linux 9 VM* tile.
+endif::[]
+ifdef::static-key[]
+. Click a template tile.
++
+The guest operating system must support configuration from a cloud-init data source.
+endif::[]
+. Click *Customize VirtualMachine*.
+. Click *Next*.
+. Click the *Scripts* tab.
+. If you have not already added a public SSH key to your project, click the edit icon beside *Authorized SSH key* and select one of the following options:
+
+* *Use existing*: Select a secret from the secrets list.
+* *Add new*:
+.. Browse to the SSH key file or paste the file in the key field.
+.. Enter the secret name.
+.. Optional: Select *Automatically apply this key to any new VirtualMachine you create in this project*.
+ifdef::dynamic-key[]
+. Set *Dynamic SSH key injection* to on.
+endif::[]
+. Click *Save*.
+. Click *Create VirtualMachine*.
++
+The *VirtualMachine details* page displays the progress of the VM creation.
+
+.Verification
+. Click the *Scripts* tab on the *Configuration* tab.
++
+The secret name is displayed in the *Authorized SSH key* section.
+
+ifeval::["{context}" == "static-key"]
+:!static-key:
+endif::[]
+ifeval::["{context}" == "dynamic-key"]
+:!dynamic-key:
+endif::[]

modules/virt-adding-static-public-key-cli.adoc renamed to modules/virt-adding-public-key-cli.adoc

@@ -2,13 +2,34 @@
 //
 // * virt/virtual_machines/virt-accessing-vm-ssh.adoc
 
+ifeval::["{context}" == "static-key"]
+:static-key:
+:header: Adding a key when creating a VM
+endif::[]
+ifeval::["{context}" == "dynamic-key"]
+:dynamic-key:
+:header: Enabling dynamic key injection
+endif::[]
+
 :_content-type: PROCEDURE
-[id="virt-adding-static-public-key-cli_{context}"]
-= Adding an SSH key when creating a virtual machine by using the command line
+[id="virt-adding-public-key-cli_{context}"]
+= {header} by using the command line
+
+ifdef::static-key[]
+You can add a statically managed public SSH key when you create a virtual machine (VM) by using the command line. The key is added to the VM at first boot.
+
+The key is added to the VM as a cloud-init data source. This method separates the access credentials from the application data in the cloud-init user data. This method does not affect cloud-init user data.
+endif::[]
+ifdef::dynamic-key[]
+You can enable dynamic key injection for a virtual machine (VM) by using the command line. Then, you can update the public SSH key at runtime.
 
-You can add a _static_ public SSH key when you create a virtual machine (VM) by using the command line. The key is added to the VM at startup.
+[NOTE]
+====
+Only {op-system-base-full} 9 supports dynamic key injection.
+====
 
-The SSH key is added to the VM as generated cloud-init metadata, by using a cloud-init configuration disk. This method separates the access credentials from the application data in the cloud-init user data. This method does not affect cloud-init user data.
+The key is added to the VM by the QEMU guest agent, which is installed automatically with {op-system-base} 9.
+endif::[]
 
 .Prerequisites
 
@@ -80,32 +101,45 @@ spec:
       - dataVolume:
           name: example-volume
         name: example-vm-disk
-        - cloudInitConfigDrive: <1>
+        - cloudInitConfigDrive: <.>
             userData: |-
               #cloud-config
               user: cloud-user
               password: <password>
               chpasswd: { expire: False }
+ifdef::dynamic-key[]
+              runcmd:
+                - [ setsebool, -P, virt_qemu_ga_manage_ssh, on ]
+endif::[]
           name: cloudinitdisk
       accessCredentials:
         - sshPublicKey:
             propagationMethod:
+ifdef::static-key[]
               configDrive: {}
+endif::[]
+ifdef::dynamic-key[]
+              qemuGuestAgent:
+                users: ["user1","user2","fedora"] <.>
+endif::[]
             source:
               secret:
-                secretName: authorized-keys <2>
+                secretName: authorized-keys <.>
 ---
 apiVersion: v1
 kind: Secret
 metadata:
   name: authorized-keys
 data:
   key:  |
-      MIIEpQIBAAKCAQEAulqb/Y... <3>
+      MIIEpQIBAAKCAQEAulqb/Y... <.>
 ----
-<1> Specify `cloudInitConfigDrive` to create a configuration drive.
-<2> Specify the `Secret` object name.
-<3> Paste the public SSH key.
+<.> Specify `cloudInitConfigDrive` to create a configuration drive.
+ifdef::dynamic-key[]
+<.> Specify the user names.
+endif::[]
+<.> Specify the `Secret` object name.
+<.> Paste the public SSH key.
 
 . Create the `VirtualMachine` and `Secret` objects:
 +
@@ -143,9 +177,21 @@ spec:
       accessCredentials:
         - sshPublicKey:
             propagationMethod:
+ifdef::static-key[]
               configDrive: {}
+endif::[]
+ifdef::dynamic-key[]
+              qemuGuestAgent:
+                users: ["user1","user2","fedora"]
+endif::[]
             source:
               secret:
                 secretName: authorized-keys
 ----
 
+ifeval::["{context}" == "static-key"]
+:!static-key:
+endif::[]
+ifeval::["{context}" == "dynamic-key"]
+:!dynamic-key:
+endif::[]

modules/virt-adding-static-public-key-project-web.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: PROCEDURE
 [id="virt-connecting-secondary-network-ssh_{context}"]
-= Connecting to a virtual machine attached to a secondary network by using SSH
+= Connecting to a VM attached to a secondary network by using SSH
 
 You can connect to a virtual machine (VM) attached to a secondary network by using SSH.
 

modules/virt-adding-static-public-key-vm-web.adoc

@@ -5,13 +5,13 @@
 
 :_content-type: PROCEDURE
 [id="virt-connecting-service-ssh_{context}"]
-= Connecting to a virtual machine by using SSH and a service
+= Connecting to a VM exposed by a service by using SSH
 
-You can connect to a virtual machine (VM) by using SSH and a service.
+You can connect to a virtual machine (VM) that is exposed by a service by using SSH.
 
 .Prerequisites
 
-* You created a service to expose a VM.
+* You created a service to expose the VM.
 * You have an SSH client installed.
 * You are logged in to the cluster.
 

modules/virt-connecting-secondary-network-ssh.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: PROCEDURE
 [id="virt-creating-service-web_{context}"]
-= Creating a node port or load balancer service by using the web console
+= Creating a service by using the web console
 
 You can create a node port or load balancer service for a virtual machine (VM) by using the {product-title} web console.