feat: add an example of building machine via terraform

Provide a very basic example of building machines via terraform.

examples/tf-multi-node-build/.gitignore

@@ -0,0 +1,43 @@
+# Local .terraform directories
+**/.terraform/*
+
+# .tfstate files
+*.tfstate
+*.tfstate.*
+
+# Crash log files
+crash.log
+crash.*.log
+
+# Exclude all .tfvars files, which are likely to contain sensitive data, such as
+# password, private keys, and other secrets. These should not be part of version
+# control as they are data points which are potentially sensitive and subject
+# to change depending on the environment.
+*.tfvars
+*.tfvars.json
+
+# Ignore override files as they are usually used to override resources locally and so
+# are not checked in
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+
+# Ignore transient lock info files created by terraform apply
+.terraform.tfstate.lock.info
+
+# Include override files you do wish to add to version control using negated pattern
+# !example_override.tf
+
+# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
+# example: *tfplan*
+
+# Ignore CLI configuration files
+.terraformrc
+terraform.rc
+
+# Ignore SSH keys
+id_*
+
+# This is an example repo so skip the lock
+.terraform.lock.hcl

examples/tf-multi-node-build/README.md

@@ -0,0 +1,47 @@
+# terraform multi node example
+
+In this example we will build multiple servers (default 2) connected
+to a network that is created. Certain things can be customized via
+terraform variables, check the `variables.tf` for details.
+
+## pre-reqs
+
+1. You must have a project and be able to authenticate to it. Please see
+   the [User Guide](https://rackerlabs.github.io/understack/user-guide/)
+   to get your CLI setup.
+2. You must have the `terraform` CLI installed.
+
+## credentials
+
+Terraform does not support the SSO authentication that is used by UnderStack
+so you must create an [Application Credential](https://docs.openstack.org/keystone/latest/user/application_credentials.html)
+for Terraform to use.
+
+You can follow the following to generate it assuming your `openstack` is
+able to authenticate to your project.
+
+```sh
+# creates an application credential called "terraform-cred"
+openstack application credential create terraform-cred
+# terraform will read these environment variables
+export OS_APPLICATION_CREDENTIAL_ID=${FROM_ABOVE}
+export OS_APPLICATION_CREDENTIAL_SECRET=${FROM_ABOVE}
+```
+
+## Executing the example
+
+You must have `terraform` install the OpenStack provider. To do so
+run the following:
+
+```sh
+terraform init
+```
+
+This is non-destructive and can be run multiple times.
+
+
+Now you can create the resources with the following:
+
+```sh
+terraform apply
+```

examples/tf-multi-node-build/main.tf

@@ -0,0 +1,64 @@
+# generate an SSH key
+resource "tls_private_key" "ssh_key" {
+  algorithm = "ED25519"
+}
+
+# save the private key to a local file
+resource "local_file" "private_key" {
+  content         = tls_private_key.ssh_key.private_key_pem
+  filename        = "${path.module}/id_ed25519"
+  file_permission = "0600"
+}
+
+# save the public key to a local file
+resource "local_file" "public_key" {
+  content  = tls_private_key.ssh_key.public_key_openssh
+  filename = "${path.module}/id_ed25519.pub"
+}
+
+resource "random_pet" "name" {
+  keepers = {
+    private_key_hash = sha256(tls_private_key.ssh_key.private_key_pem)
+  }
+  length = 1
+}
+
+resource "openstack_compute_keypair_v2" "ssh_keypair" {
+  name       = random_pet.name.id
+  public_key = tls_private_key.ssh_key.public_key_openssh
+}
+
+resource "openstack_networking_network_v2" "tenant_net" {
+  name           = random_pet.name.id
+  admin_state_up = "true"
+}
+
+resource "openstack_networking_subnet_v2" "tenant_subnet" {
+  name       = random_pet.name.id
+  network_id = openstack_networking_network_v2.tenant_net.id
+  cidr       = var.network_subnet
+  ip_version = 4
+  # not currently enabled for understack
+  enable_dhcp = false
+}
+
+data "openstack_compute_flavor_v2" "test_flavor" {
+  name = var.server_flavor
+}
+
+data "openstack_images_image_v2" "test_image" {
+  name        = var.server_image
+  most_recent = true
+}
+
+resource "openstack_compute_instance_v2" "tenant_server" {
+  count     = var.server_count
+  name      = format("%s-%02d", random_pet.name.id, count.index + 1)
+  image_id  = data.openstack_images_image_v2.test_image.id
+  flavor_id = data.openstack_compute_flavor_v2.test_flavor.id
+  key_pair  = openstack_compute_keypair_v2.ssh_keypair.name
+
+  network {
+    uuid = openstack_networking_network_v2.tenant_net.id
+  }
+}

examples/tf-multi-node-build/variables.tf

@@ -0,0 +1,23 @@
+variable "server_count" {
+  description = "How many servers to build"
+  type        = number
+  default     = 2
+}
+
+variable "server_image" {
+  description = "The OS image to use for the servers"
+  type        = string
+  default     = "Ubuntu-24.04"
+}
+
+variable "server_flavor" {
+  description = "Hardware flavor for the servers"
+  type        = string
+  default     = "gp2.small"
+}
+
+variable "network_subnet" {
+  description = "Subnet to use for the network"
+  type        = string
+  default     = "192.168.0.0/24"
+}

examples/tf-multi-node-build/versions.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_providers {
+    local = {
+      source = "hashicorp/local"
+    }
+    openstack = {
+      source  = "terraform-provider-openstack/openstack"
+      version = "~> 2.1.0"
+    }
+    random = {
+      source = "hashicorp/random"
+    }
+  }
+}