From fd65467297bd2c62d9e85bdad6af6b5addbc712c Mon Sep 17 00:00:00 2001
From: Nikolas Grottendieck <git@nikolasgrottendieck.com>
Date: Sat, 1 Apr 2023 21:02:44 +0200
Subject: [PATCH] provisioning/vmware: simplify example, provide authentication
 tip

As discussed in coreos/fedora-coreos-tracker#1158 the examples for VMware
vSphere now:

- tell users about alternative authentication methods
- give simpler instructions for a hello-world run
  - reuse of library items is relegated to an optional section
---
 modules/ROOT/pages/provisioning-vmware.adoc | 56 +++++++++++++--------
 1 file changed, 35 insertions(+), 21 deletions(-)

diff --git a/modules/ROOT/pages/provisioning-vmware.adoc b/modules/ROOT/pages/provisioning-vmware.adoc
index 58c7091c..0f33eb57 100644
--- a/modules/ROOT/pages/provisioning-vmware.adoc
+++ b/modules/ROOT/pages/provisioning-vmware.adoc
@@ -92,9 +92,40 @@ ssh core@<ip address>
 
 This section shows how to use vSphere facilities to configure and run VMs from the command-line. Similar steps can be performed via the graphical UI too.
 
-=== Importing the OVA
+TIP: While the examples below use `govc session.login` to authenticate, you can also use environment variables to provide credentials. Check the https://github.com/vmware/govmomi/tree/main/govc#usage[official documentation] for details.
+
+=== Setting up a new VM
+
+You can now deploy a new VM, starting from the OVA and the encoded Ignition configuration:
+
+[source, bash]
+----
+FCOS_OVA='./ova-templates/fedora-coreos-31.20200210.3.0-vmware.x86_64.ova'
+VM_NAME='fcos-node01'
+govc session.login -u 'user:password@host'
+govc import.ova -name ${VM_NAME} ${FCOS_OVA}
+govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data.encoding=${CONFIG_ENCODING}"
+govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data=${CONFIG_ENCODED}"
+----
+
+A new `fcos-node01` VM is now available for booting. Its hardware configuration can be further customized at this point, and then powered-up:
+
+[source, bash]
+----
+govc vm.info -e "${VM_NAME}"
+govc vm.power -on "${VM_NAME}"
+----
+
+If you set up an xref:authentication.adoc[SSH key] for the default `core` user, you can SSH into the VM and explore the OS:
 
-The downloaded OVA has to be first imported into vSphere library:
+[source, bash]
+----
+ssh core@<ip address>
+----
+
+=== Using the OVA from the vSphere library
+
+In case you want to spawn multiple, different VMs based on the same base image you can import it into the vSphere library for easy reuse:
 
 [source, bash]
 ----
@@ -106,9 +137,7 @@ govc library.create "${LIBRARY}"
 govc library.import -n "${TEMPLATE_NAME}" "${LIBRARY}" "${FCOS_OVA}"
 ----
 
-=== Setting up a new VM
-
-You can now deploy a new VM, starting from the template in the library and the encoded Ignition configuration:
+Creating a new instance can now be done using the `govc library.deploy` command:
 
 [source, bash]
 ----
@@ -118,7 +147,7 @@ govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data.encoding=${CO
 govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data=${CONFIG_ENCODED}"
 ----
 
-Note: If the vcenter has multiple datacenters and datastores, you must specify them explicitly:
+Note: If the vCenter has multiple datacenters and datastores, you must specify them explicitly:
 [source, bash]
 ----
 # Get resource pool using `$ govc find / -type ResourcePool`
@@ -127,21 +156,6 @@ DATASTORE="datastore-129"
 govc library.deploy -pool=${RESOURCE_POOL} -ds=${DATASTORE} "${LIBRARY}/${TEMPLATE_NAME}" "${VM_NAME}"
 ----
 
-A new `fcos-node01` VM is now available for booting. Its hardware configuration can be further customized at this point, and then powered-up:
-
-[source, bash]
-----
-govc vm.info -e "${VM_NAME}"
-govc vm.power -on "${VM_NAME}"
-----
-
-If you set up an xref:authentication.adoc[SSH key] for the default `core` user, you can SSH into the VM and explore the OS:
-
-[source, bash]
-----
-ssh core@<ip address>
-----
-
 === First-boot networking and Ignition
 
 Ignition supports referencing remote content in configuration and fetching it at provisioning time.