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

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)