fix(README): Document prerequisites and common variables for deployment

This PR documents prerequisites in the libvirt backend, since that is the most likely backend for the deployment. It also provides links to further backend documentation, and documents variables common for all deployments.

README.md

@@ -11,7 +11,13 @@
 
 **Libvirt provider version**: 0.6.3
 
-openSUSE and SUSE Linux Enterprise Server:
+NOTE: to deploy development versions of SUSE Manager you will have to have [SUSE's internal CA certificates](http://ca.suse.de/) installed on your system.
+
+You will need to edit HCL ([HashiCorp Configuration Language](https://github.com/hashicorp/hcl)) files. Syntax highlighting is available in major text editors like [atom](https://atom.io/packages/language-hcl).
+
+### Prerequisites for openSUSE and SUSE Linux Enterprise Server
+
+Execute the following on openSUSE and SUSE Linux Enterprise Server:
 
 ```bash
 # Uncomment one of the following lines depending on your distro
@@ -27,7 +33,9 @@ sudo zypper install --from systemsmanagement_sumaform terraform terraform-provid
 git clone https://github.com/uyuni-project/sumaform.git
 ```
 
-Ubuntu and Debian:
+### Prerequisites for Ubuntu and Debian
+
+Execute the following commands:
 
 ```bash
 sudo apt install alien
@@ -38,10 +46,6 @@ sudo alien -i terraform-provider-libvirt.rpm
 git clone https://github.com/uyuni-project/sumaform.git
 ```
 
-NOTE: to deploy development versions of SUSE Manager you will have to have [SUSE's internal CA certificates](http://ca.suse.de/) installed on your system.
-
-You will need to edit HCL ([HashiCorp Configuration Language](https://github.com/hashicorp/hcl)) files. Syntax highlighting is available in major text editors like [atom](https://atom.io/packages/language-hcl).
-
 ## Backend choice
 
 `sumaform` can deploy virtual machines to:
@@ -53,6 +57,22 @@ You will need to edit HCL ([HashiCorp Configuration Language](https://github.com
 The simplest, recommended setup is to use libvirt on your local host. That needs at least 8 GB of RAM in your machine.
 If you need a lot of VMs or lack hardware you probably want to use an external libvirt host with bridged networking.
 
+If you use the libvirt provider, install and enable libvirt before you attempt to run the terraform deployment.
+The `virt-manager` package is recommended because it configures default resources that the terraform deployment uses, e.g. the `default` virtual network.
+
+```bash
+# Download and install libvirt and virt-manager, for example:
+sudo zypper install libvirt virt-manager
+# On Ubuntu/Debian:
+sudo apt install virt-manager qemu-kvm libvirt-daemon-system
+
+# Start libvirt
+sudo systemctl start libvirtd
+
+# Optionally, enable libvirt so that it starts at boot time
+sudo systemctl enable libvirtd
+```
+
 The Amazon Web Services backend is currently under maintenance and is not immediately usable as-is. We plan to restore it soon.
 
 The null backend can be useful in a wide variety of scenarios, for example:
@@ -61,6 +81,9 @@ The null backend can be useful in a wide variety of scenarios, for example:
 - Cases in which the virtual infrastructure is outside of the Terraform user's control
 - Cover architectures that will maybe never be covered by any other Terraform plugin
 
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for more information about configuring the backend.
+Each backend has a README file with further configuration instructions.
+
 ## Basic `main.tf` configuration
 
 In `sumaform` you define a set of virtual machines in a `main.tf` configuration file, then run Terraform to have them deployed. Contents of the file vary slightly depending on the backend you choose.
@@ -86,6 +109,37 @@ terraform validate # check if the configuration is valid
 terraform apply # prepare and apply a plan to create your systems (after manual confirmation)
 ```
 
+### Common Variables
+
+**cc_username/cc_password**: Credentials for the [SUSE Customer Center](https://scc.suse.com/).
+Set the credentials if you are deploying SUMA, or synchronizing SUMA repositories.
+
+**images**: In the `base` module, the `images` variable specifies the images that you want to download and use in your installation, for example:
+
+```bash
+# main.tf file contents
+module "base" {
+  source = "./modules/base"
+
+  ssh_key_path = "/home/user/.ssh/id_ed25519.pub"
+
+  cc_username = "..."
+  cc_password = "..."
+  images = [
+    "centos7o",
+    "almalinux8o",
+    "opensuse154o",
+    "opensuse155o",
+    "sles15sp4o",
+    "sles15sp5o",
+    "sles12sp5o",
+    "ubuntu2004o",
+    "ubuntu2204o"
+  ]
+# ...
+}
+```
+
 ## Advanced use
 
 - To run the Cucumber testsuite for Uyuni or SUSE Manager, see [README_TESTING.md](README_TESTING.md)