Usecase: CS Course with individual Windows instances for students

Last changed: 2024-09-24

This document describes and tries to offer a solution on how to spin up an arbitrary number of Windows Server instances. The idea is that each student is given their own pre-configured instance with a set of credentials.

Overview

In this usecase study, we will demonstrate with examples and code the entire process:

1. Install a master Windows instance, which we will later use as a template for new instances

2. Do whatever configuration changes, install software etc. that is required. All changes that should be identical on the students’ instances should be done in this step

3. Make a snapshot of the master instance. This is the template template that will be used in the next step

4. Use Terraform to spin up a number of instances for students based on the template created in the previous step

5. Use Ansible to make individual configuration on each of the student instances. I our case we add an individual user with an autogenerated password for each instance

Prerequisites

This guide assumes that you have installed and know how to use Terraform and Ansible. For more information, see

• Terraform and NREC: Part I - Basics

• Terraform and NREC: Part II - Additional resources

• Terraform and NREC: Part III - Dynamics

• Terraform and NREC: Part IV - Pairing with Ansible

You also need to have the OpenStack CLI tools installed.

Preparing the master Windows instance

For this step, consult the documentation available here:

• Create a Windows virtual machine

Step by step example

1. If you haven’t already, create an SSH key of type RSA in PEM format:

   $ ssh-keygen -t rsa -b 4096 -m PEM -a 100 -f ~/.ssh/winkey
   

   In order to utilize the key to retrieve the admin password, the key must be RSA and in PEM format. Also, if you would like to retrieve the password in the GUI, the key cannot have a passphrase.

2. Import the public key ~/.ssh/winkey.pub into openstack

3. Create a Windows instance. In this demo, we have chosen:

   • Name: in9999-master

   • Image: GOLD Windows Server 2022 Standard

   • Flavor: d1.medium

   • Network: IPv6

   • Security Groups: default and others

   • Key Pair: winkey (created above)

   You should add security groups that allow SSH and RDP from your current IP address.

4. Wait for the instance to be ready. With Windows it takes a long time, at least 10 minutes

   

   When the instance responds to SSH logins, you can proceed:

   $ ssh 2001:700:2:8201::13a7 -l Admin -i ~/.ssh/winkey
   

   Microsoft Windows [Version 10.0.20348.2655]
   (c) Microsoft Corporation. All rights reserved.
   
   admin@IN9999-MASTER C:\Users\Admin>
   

5. Retrieve the Admin password. This can be done with GUI by selecting the Retrieve Password action, or by using the nova CLI tool:

   $ openstack server show in9999-master -c id -f value
   c318ce46-845f-4254-8955-3ae910de8835
   
   $ nova get-password c318ce46-845f-4254-8955-3ae910de8835 ~/.ssh/winkey
   nova CLI is deprecated and will be a removed in a future release
   0T9uzBckWHloDVLL8QqX
   

6. Log into the master Windows instance using RDP. There are a number of ways to do this, depending on your OS and preference. In our case, we connect using xfreerdp:

   $ xfreerdp /cert:ignore /d:workgroup /u:Admin /p:0T9uzBckWHloDVLL8QqX /v:[2001:700:2:8201::13a7] /h:1050 /w:1400
   

   

7. Install software and make any changes as required. For the purposes of this demonstration, we install Visual Studio Code

   

8. Reboot the instance. This is required before running sysprep and proceeding with creating a snapshot.

Take a snapshot

The procedure for creating a snapshot is described here:

• Creating a snapshot image

Step by step example

1. Log into the master instance again via RDP:

2. Run Powershell as administrator:

   

3. In the elevated Powershell, run Sysprep with the proper arguments:

   PS C:\Users\Admin> $unattendedXmlPath = "c:\Program Files\Cloudbase Solutions\Cloudbase-Init\conf\Unattend.xml" ; ipconfig /release6 ; c:\windows\system32\sysprep\Sysprep /generalize /oobe /shutdown /unattend:"$unattendedXmlPath"
   

   This will take a few minutes, ending with the instance being shut off. If you connected via IPv6, the connection will be broken immediately, but Sysprep should do its job regardless. Proceed when the instance is properly shut down:

   $ openstack server show in9999-master -c status -f value
   SHUTOFF
   

4. Make a snapshot of the instance while it is shut off

   

   We name the snapshot «master-snap-01»:

   

We are now ready to proceed with creating student instances.

Create student instances

This next step uses Terraform to create a number of instances for students. First, create an empty directory and cd into it, e.g.:

$ mkdir ~/in9999-h2024
$ cd ~/in9999-h2024

Copy the following files info this directory:

• main.tf

• secgroup.tf

• variables.tf

• terraform.tfvars

These files are from Terraform and NREC: Part IV - Pairing with Ansible, but with adjustments for this usecase. Edit these files to suit your needs. You should most likely want a lot of changes in variables.tf and terraform.tfvars.

Run terraform init:

$ terraform init
(...output omitted...)
Terraform has been successfully initialized!

Run terraform plan:

$ terraform plan
(...output omitted...)
Plan: 29 to add, 0 to change, 0 to destroy.

Fix any errors from the plan command, then run terraform apply:

$ terraform apply
(...output omitted...)
Apply complete! Resources: 29 added, 0 changed, 0 destroyed.

The instances are now created, we are ready to make the final configuration with Ansible. The end result is:

$ openstack server list --name in9999 --sort-column Name -c Name -c Status -c Image
+--------------------+---------+-----------------------------------+
| Name               | Status  | Image                             |
+--------------------+---------+-----------------------------------+
| in9999-h2024-lab-0 | ACTIVE  | master-snap-01                    |
| in9999-h2024-lab-1 | ACTIVE  | master-snap-01                    |
| in9999-h2024-lab-2 | ACTIVE  | master-snap-01                    |
| in9999-h2024-lab-3 | ACTIVE  | master-snap-01                    |
| in9999-h2024-lab-4 | ACTIVE  | master-snap-01                    |
| in9999-master      | SHUTOFF | GOLD Windows Server 2022 Standard |
+--------------------+---------+-----------------------------------+

Configure student instances

Download the following files into the same directory as the Terraform files:

• terraform.yaml

• add-labuser.yaml

Edit these files as necessary. At minimum you need to edit the terraform.yaml file.

Test that ansible works:

$ ansible -i terraform.yaml all -m win_ping
[WARNING]: Collection cloud.terraform does not support Ansible version 2.14.14
[WARNING]: Invalid characters were found in group names but not replaced, use -vvvv to see details
in9999-h2024-lab-1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
in9999-h2024-lab-0 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
in9999-h2024-lab-2 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
in9999-h2024-lab-4 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
in9999-h2024-lab-3 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

Run the add-labuser.yaml playbook:

$ ansible-playbook -i terraform.yaml add-labuser.yaml
(...output omitted...)

The credentials are saved in a file called labusers.csv, which is located in the same directory as the playbook. Example contents:

HOST,IPADDR,USERNAME,PASSWORD
in9999-h2024-lab-0,2001:700:2:8201::100e,labuser,Msho!nLKCCo)yIAvB$UC
in9999-h2024-lab-1,2001:700:2:8201::1270,labuser,cXhm_q%xvwvBmLM6rPF6
in9999-h2024-lab-2,2001:700:2:8201::1485,labuser,sGecTMBp0u11x0.OpEGn

Adding or removing instances

In order to to increase or decrease the number of instances, change the number in variables.tf:

variables.tf

# Mapping between role and number of instances (count)
variable "role_count" {
  type = map(string)
  default = {
    "students" = 5
  }
}

Then run:

terraform plan
terraform apply

Create users as before with:

ansible-playbook -i terraform.yaml add-labuser.yaml

The credentials file labusers.csv will be updated to reflect the changes. Note that the passwords are randomly generated but idempotent, thus changing the number of instances will not change passwords for existing instances.

---

File listing

A complete listing of the example files used in this document is provided below.

terraform.yaml

plugin: cloud.terraform.terraform_provider
project_path: /path/to/project
# Terraform binary (available in the $PATH) or full path to the binary.
binary_path: terraform

main.tf

# Define required providers
terraform {
  required_version = ">= 1.0"
  required_providers {
    openstack = {
      source  = "terraform-provider-openstack/openstack"
    }
    ansible = {
      version = "~> 1.3.0"
      source  = "ansible/ansible"
    }
  }
}
provider "openstack" {}

# SSH key
resource "openstack_compute_keypair_v2" "keypair" {
  region     = var.region
  name       = "${var.name}-key"
  public_key = file(var.ssh_public_key)
}

# Student servers
resource "openstack_compute_instance_v2" "student_instance" {
  region      = var.region
  count       = lookup(var.role_count, "students", 0)
  name        = "${var.name}-lab-${count.index}"
  image_name  = lookup(var.role_image, "snapshot", "unknown")
  flavor_name = lookup(var.role_flavor, "flavor", "unknown")

  key_pair = "${var.name}-key"
  security_groups = [
    "${var.name}-icmp",
    "${var.name}-ssh",
    "${var.name}-rdp",
  ]

  network {
    name = "${var.network}"
  }

  lifecycle {
    ignore_changes = [image_name,image_id]
  }

  depends_on = [
    openstack_networking_secgroup_v2.instance_icmp_access,
    openstack_networking_secgroup_v2.instance_ssh_access,
    openstack_networking_secgroup_v2.instance_rdp_access,
  ]
}

# Ansible student hosts
resource "ansible_host" "student_instance" {
  count  = lookup(var.role_count, "students", 0)
  name   = "${var.name}-lab-${count.index}"
  groups = ["${var.name}"] # Groups this host is part of

  variables = {
    ansible_host = trim(openstack_compute_instance_v2.student_instance[count.index].access_ip_v6, "[]")
  }
}

# Ansible student group
resource "ansible_group" "student_instances_group" {
  name     = "student_instances"
  children = ["${var.name}"]
  variables = {
    ansible_user = "Admin"
    ansible_connection = "ssh"
    remote_tmp = "C:\\Users\\Admin\\Tmp"
    become_method = "runas"
    ansible_shell_type = "cmd"
    shell_type = "cmd"
  }
}

secgroup.tf

# Security group ICMP
resource "openstack_networking_secgroup_v2" "instance_icmp_access" {
  region      = var.region
  name        = "${var.name}-icmp"
  description = "Security group for allowing ICMP access"
}

# Security group SSH
resource "openstack_networking_secgroup_v2" "instance_ssh_access" {
  region      = var.region
  name        = "${var.name}-ssh"
  description = "Security group for allowing SSH access"
}

# Security group RDP
resource "openstack_networking_secgroup_v2" "instance_rdp_access" {
  region      = var.region
  name        = "${var.name}-rdp"
  description = "Security group for allowing RDP access"
}

# Allow ssh from IPv4 net
resource "openstack_networking_secgroup_rule_v2" "rule_ssh_access_ipv4" {
  region            = var.region
  count             = length(var.allow_ssh_from_v4)
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 22
  port_range_max    = 22
  remote_ip_prefix  = var.allow_ssh_from_v4[count.index]
  security_group_id = openstack_networking_secgroup_v2.instance_ssh_access.id
}

# Allow ssh from IPv6 net
resource "openstack_networking_secgroup_rule_v2" "rule_ssh_access_ipv6" {
  region            = var.region
  count             = length(var.allow_ssh_from_v6)
  direction         = "ingress"
  ethertype         = "IPv6"
  protocol          = "tcp"
  port_range_min    = 22
  port_range_max    = 22
  remote_ip_prefix  = var.allow_ssh_from_v6[count.index]
  security_group_id = openstack_networking_secgroup_v2.instance_ssh_access.id
}

# Allow icmp from IPv4 net
resource "openstack_networking_secgroup_rule_v2" "rule_icmp_access_ipv4" {
  region            = var.region
  count             = length(var.allow_icmp_from_v4)
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "icmp"
  remote_ip_prefix  = var.allow_icmp_from_v4[count.index]
  security_group_id = openstack_networking_secgroup_v2.instance_icmp_access.id
}

# Allow icmp from IPv6 net
resource "openstack_networking_secgroup_rule_v2" "rule_icmp_access_ipv6" {
  region            = var.region
  count             = length(var.allow_icmp_from_v6)
  direction         = "ingress"
  ethertype         = "IPv6"
  protocol          = "ipv6-icmp"
  remote_ip_prefix  = var.allow_icmp_from_v6[count.index]
  security_group_id = openstack_networking_secgroup_v2.instance_icmp_access.id
}

# Allow RDP from IPv4 net
resource "openstack_networking_secgroup_rule_v2" "rule_rdp_access_ipv4" {
  region            = var.region
  count             = length(var.allow_rdp_from_v4)
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 3389
  port_range_max    = 3389
  remote_ip_prefix  = var.allow_rdp_from_v4[count.index]
  security_group_id = openstack_networking_secgroup_v2.instance_rdp_access.id
}

# Allow RDP from IPv6 net
resource "openstack_networking_secgroup_rule_v2" "rule_rdp_access_ipv6" {
  region            = var.region
  count             = length(var.allow_rdp_from_v6)
  direction         = "ingress"
  ethertype         = "IPv6"
  protocol          = "tcp"
  port_range_min    = 3389
  port_range_max    = 3389
  remote_ip_prefix  = var.allow_rdp_from_v6[count.index]
  security_group_id = openstack_networking_secgroup_v2.instance_rdp_access.id
}

variables.tf

# Variables
variable "region" {
}

variable "name" {
  default = "in9999-h2024"
}

variable "ssh_public_key" {
  default = "~/.ssh/id_ed25519.pub"
}

variable "network" {
  default = "IPv6"
}

# Security group defaults
variable "allow_icmp_from_v6" {
  type    = list(string)
  default = []
}

variable "allow_icmp_from_v4" {
  type    = list(string)
  default = []
}

variable "allow_ssh_from_v6" {
  type    = list(string)
  default = []
}

variable "allow_ssh_from_v4" {
  type    = list(string)
  default = []
}

variable "allow_rdp_from_v6" {
  type    = list(string)
  default = []
}

variable "allow_rdp_from_v4" {
  type    = list(string)
  default = []
}

# Mapping between role and image
variable "role_image" {
  type = map(string)
  default = {
    "snapshot" = "master-snap-01"
  }
}

# Mapping between role and flavor
variable "role_flavor" {
  type = map(string)
  default = {
    "flavor" = "d1.medium"
  }
}

# Mapping between role and number of instances (count)
variable "role_count" {
  type = map(string)
  default = {
    "students" = 5
  }
}

terraform.tfvars

# Region
region = "osl"

# This is needed for ICMP access
allow_icmp_from_v6 = [
  "2001:700:100::/48"
]
allow_icmp_from_v4 = [
  "129.240.0.0/16"
]

# This is needed to access the instance over ssh
allow_ssh_from_v6 = [
  "2001:700:100:8070::/64",
  "2001:700:100:8071::/64",
]
allow_ssh_from_v4 = [
  "129.240.114.32/28",
  "129.240.114.48/28",
]

# This is needed to access the instance over RDP
allow_rdp_from_v6 = [
  "2001:700:100::/48"
]
allow_rdp_from_v4 = [
  "129.240.0.0/16"
]

add-labuser.yaml

- hosts: "{{ myhosts | default('all') }}"
  gather_facts: no

  vars:
    csvfile: "{{ playbook_dir }}/labusers.csv"
    username: "labuser"

  tasks:
    - name: Create random but idempotent password
      ansible.builtin.set_fact:
        password: "{{ lookup('ansible.builtin.password', '/dev/null',
                              seed=inventory_hostname+ansible_host,
                              chars=['ascii_letters', 'digits', '().@%!-_']) }}"

    - name: Ensure lab user is present
      ansible.windows.win_user:
        name: "{{ username }}"
        password: "{{ password }}"
        state: present
        groups:
          - Users
          - Administrators
          - Remote Desktop Users
      register: labuser

    - name: Print credentials if new/changed
      ansible.builtin.debug:
        msg: "NEW credential: {{ username }}:{{ password }}"
      when: labuser.changed

    - name: Create temporary directory
      ansible.builtin.tempfile:
        state: directory
      register: tmpdir
      delegate_to: localhost
      run_once: true
    
    - name: Create CSV header
      ansible.builtin.lineinfile:
        line: "HOST,IPADDR,USERNAME,PASSWORD"
        path: "{{ tmpdir.path }}/000.csv"
        create: yes
      delegate_to: localhost
      run_once: true

    - name: Save credentials in individual files
      ansible.builtin.lineinfile:
        line: "{{ inventory_hostname }},{{ ansible_host }},{{ username }},{{ password }}"
        path: "{{ tmpdir.path }}/{{ inventory_hostname }}.csv"
        create: yes
      delegate_to: localhost

    - name: Assemble CSV file from fragments
      ansible.builtin.assemble:
        src: "{{ tmpdir.path }}"
        dest: "{{ csvfile }}"
      delegate_to: localhost
      run_once: true

    - name: Remove temporary dir
      ansible.builtin.file:
        path: "{{ tmpdir.path }}"
        state: absent
      when: tmpdir.path is defined
      delegate_to: localhost
      run_once: true