CloudStack User Guide

This is a user's guide on using CloudStack provided by Research Computing Services.

Introduction

Apache CloudStack is an Infrastructure as a Service (IaaS) platform that allows users to quickly spin up Linux/Non-Windows based virtual machines. RCS is providing this service to help researchers quickly set up and prototype research related software on premises. It is ideal for short-term projects that involve level 1 and level 2 data. Please refer to our CloudStack End User Agreement for acceptable uses and requirements.

Service limitations

Please be aware and understand each of the following limitations with CloudStack.

• CloudStack is not appropriate for Windows based workloads.
• CloudStack has no VM backups. It is up to the user to perform backups of their work. It is not intended for mission critical workloads that require high availability.
• Internet facing applications on ports other than 80 and 443 may be limited and subject to IT security restrictions. If you have an application that needs to be accessible from outside campus, a security exception has to be submitted to IT security for approval.

Please contact us if you have any questions with these limitations and to consult whether your workload may work within the CloudStack environment.

Get started

To get started, request for a new CloudStack account via ServiceNow. You may add multiple users to the CloudStack account on the same ServiceNow form.

Using your virtual machine

You will be able to run any non-Windows based virtual machine in the CloudStack infrastructure. While we cannot provide specific management advice on each and every operating system available, we can provide you with some suggestions on important considerations to be aware of.

Educate yourself

All operating systems (OS) have user groups, web sites, wikis, or mailing lists somewhere on the internet. They can be a valuable resource. Most OS providers have on-line documentation that describes using their product. For example Rocky Linux, used by RCS, has a documentation site. These are excellent resources and can help you understand how to manage your virtual machine.

Keep security in mind

To help keep our network and infrastructure safe from cyber attacks, it is critical that your VMs are properly configured to reduce the number of ways that hackers could exploit it. Here are some common tasks that you can do to help harden your VM:

• Ensure that the only services running on your VM are the ones you must run. Each OS has a way of managing what services are running (sysinit, systemd etc). Please ensure that unnecessary services have been disabled.

• Disable or delete any unused accounts. Many OSs will have pre-configured accounts, and many applications will have pre-configured accounts. Make sure they are either disabled or not allowed to login.

• All accounts should have strong passwords.

• Many OS's have the ability to automatically update themselves. If possible please consider doing this. Updates can also be configured to skip certain software if it will interfere with your research, but please be advised that doing so could place your system at risk.

• If your VM must be exposed to the internet, consider using some kind of end-point security tool to help monitor for and block cyber attacks.

Accessing CloudStack

Accessing the CloudStack management console

The CloudStack management console is a web-based portal that allows you to view and manage your cloud infrastructure including virtual machines, storage, and network. Any modern web browsers including Chrome, Firefox, Edge, and Safari is supported.

Access the CloudStack management console is possible only from an IT-managed computer or through the IT General VPN when working on unmanaged machines (eg. AirUC) or when working off campus (eg. at home). Please review the IT knowledge base article on connecting to the General VPN or contact IT support if you need assistance connecting to the General VPN.

CloudStack VPN Connection

Login to CloudStack

To log in to CloudStack, navigate to https://cloudstack.rcs.ucalgary.ca/. If this site fails to load, please make sure you are either on a IT managed computer or connected to the General VPN.

Sign in to CloudStack using the Single Sign-On option as shown in the image below. This method will require you to authenticate through our central authentication service using your University of Calgary IT credentials and will require multi-factor authentication. You must have multi-factor authentication set up either via your phone or with the Microsoft Authenticator app.

CloudStack Login Page

Note: Due to a bug with the UI, if the Single Sign-On option is disabled, please refresh the login page and try again. This issue should be addressed in our next update for CloudStack.

CloudStack Dashboard

After logging in, you will be presented with your CloudStack management console. The dashboard shows you a general overview of your account's status.

CloudStack Dashboard

On the right hand side of the dashboard, you will also see recent activity and events that was done within your CloudStack account.

If you wish to see your CloudStack account resource quota and allocation, navigate to: Accounts -> Click on your account -> Resources.

CloudStack Resource Quota

Working with virtual machines

CloudStack allows you to control the lifecycle of virtual machines within your cloud account. VMs may be started, stopped, rebooted, or destroyed within your management console.

Create a VM

To create a new VM, enter the CloudStack management console and navigate to:  Compute -> Instances -> Add Instance

CloudStack Instance Summary

Virtual Machines require the following details:

1. Deployment zone. Your account will already be placed in the appropriate zone.
2. Boot template or ISO. You may choose either a pre-created template or boot from a custom CD-ROM ISO file.
3. Compute offering. You may select an appropriate size for your new VM. Resources will be counted against your account's quota.
4. Data Disk. You may choose to add an additional virtual disk to your VM to store your data. Alternatively, if you wish to use a single virtual disk for your VM, you may choose to override the size of your root disk in step 2 and select 'No thanks' in this step.
5. Networks. You may choose one or more networks your VM should connect to. All CloudStack accounts come with a default network already created and ready to be used.
6. SSH keypairs. For templates that support custom SSH key pairs, you may choose to use a custom SSH keypair to be installed as part of the deployment process.
7. Advanced settings. For templates that support custom user-data (Cloud-Init), you may choose to enable the advanced settings and provide your own Cloud-Init user-data payload. More on this in the advanced tasks section below.
8. Other VM details. You may give your new VM a friendly name and make it part of a group. Groups allow you to group related VMs together for better organization. You may change these details at a later time.

When you are done, review the instance summary on the right hand side and then click on the 'Launch Virtual Machine' button.

Selecting your VM Operating system

Many OSs will provide various editions that are tailored to a specific use case. A desktop VM may not be appropriate when you need to run a database server. The OS provider will have guides on how to choose an edition.

You may choose to install the operating system to your virtual machine using either pre-built templates or from scratch using an ISO image.

Install from a virtual machine template

We provide a Rocky Linux 8.5 and a Ubuntu Server 22.04 LTS template for your convenience. These templates are pre-built images with the operating system installed and ready for use. Our templates also support further automated setup configured using Cloud-Init configuration data that can be provided when deploying a new VM. Currently, we offer the following templates:

Template	Cloud-Init Support	Password Support	Default Username
Rocky Linux 8.5	Yes	Yes	rocky
Ubuntu Server 22.04	Yes	Yes	ubuntu

Rocky Linux is an open source Linux distribution that is binary-compatible with Red Hat Enterprise Linux and is what RCS recommends.

For templates that support passwords, the generated password that appears after a VM is created is applied to the default username.

Security note: All VM templates are configured with SSH password authentication enabled. You should be able to SSH to your VM from another system connected to the same guest network. Do not expose port 22 unless required and we highly recommend using key based authentication.

Virtual machine credentials

VM templates that have password support will have a randomly generated password set when the VM is first created or when a password reset request is made (available only when the VM is powered off). A randomly generated 6 character password will be displayed when a new password is set and appears as a notification in your CloudStack management console.

CloudStack VM Password

This password is set on the default username for your template. For example, the Rocky Linux VM template will set this password to the 'rocky' user account. You may become the super user by logging in as the rocky user and then running sudo su.

Note: If you specify a custom Cloud-Init config that creates additional users or sets account passwords, the displayed password will be overridden and have no effect.

Install from an ISO image

We provide various ISO images for popular Linux distributions. You may select one of these ISO images instead of using a pre-built template when deploying a new virtual machine. We currently provide:

Distribution	ISO
Ubuntu 20.04	ubuntu-20.04.4-desktop-amd64.iso ubuntu-20.04.4-live-server-amd64.iso
Ubuntu 21.10	ubuntu-21.10-desktop-amd64.iso ubuntu-21.10-live-server-amd64.iso
Ubuntu 22.04	ubuntu-22.04-live-server-amd64.iso
Rocky Linux 8.5	Rocky-8.5-x86_64-minimal.iso
Fedora 35	Fedora-Workstation-Live-x86_64-35-1.2.iso

You may install custom ISO file into your CloudStack account either by directly uploading the ISO through the web console or by providing a URL to the ISO file on the internet.

Please do not install Windows on our CloudStack infrastructure. It is against our user agreement to run Windows based systems in this infrastructure. If you need a Windows VM, please contact us for alternative solutions.

Register a ISO with a URL

CloudStack Download ISO

To add a custom ISO file from the internet, enter the CloudStack management console and navigate to:  Images -> ISOs -> Register ISO

You may check the state of the ISO file by clicking on it and verify the state of the file. If the file is successfully downloaded, its ready state should become ‘true’. The ISO file will only appear in the selection list when the file is downloaded successfully.

CloudStack ISO Ready

Upload a custom ISO

To upload an ISO file, enter the CloudStack management console and navigate to:  Images -> ISOs -> Upload ISO from Local (icon)

CloudStack Upload ISO

Selecting a compute offering

Compute offerings are predefined virtual machine sizes. For academic and research virtual machines, we offer the following compute offerings.

Compute offering	CPU cores	Memory	HA Available	Notes
rcs.tiny	1	1 GB	Yes	Generic QEMU CPU Use this class of compute offerings for typical workloads that do not require specific CPU feature flags. Virtual machines will run on both newer or older RCS hardware, depending on availability.
rcs.small	2	2 GB	Yes
rcs.medium	4	4 GB	Yes
rcs.large	4	8 GB	Yes
rcs.2xlarge	8	16 GB	Yes
icelake.small	2	2 GB	Yes	Intel Ice Lake CPU feature set Use this class of compute offerings if your workload is compute intensive or requires specific CPU feature flags such as AVX512. Virtual machines will run on only on newer RCS hardware.
icelake.medium	4	4 GB	Yes
icelake.large	8	8 GB	Yes
icelake.2xlarge	16	16 GB	Yes
bigmem.medium	2	64 GB	No	Generic QEMU CPU with large memory allocations Use this class of compute offerings if your workload requires lots of memory Virtual machines will run on older large memory RCS hardware. HA is not available for big memory virtual machines due to limited hardware.
bigmem.large	4	128 GB	No
bigmem.2xlarge	8	256 GB	No
bigmem.4xlarge	16	512 GB	No

If you need a customized compute offering for a specific workload, please contact us.

Connecting to your VM console

The CloudStack management console has a KVM (keyboard, video, mouse) feature built-in, allowing you to remotely connect to and interact with your virtual machine. To connect to your virtual machine's console, navigate to: Compute -> Instances -> Your Instance -> View console.

CloudStack View Console

Expanding a VM disk

CloudStack Expand Volume

Virtual machine disks can be expanded after they are created within CloudStack. However, you will need to expand the partitions and filesystems manually.

To grow an existing disk:

1. Go into your VM details page and click on ‘Volumes’.
2. Click on the volume you wish to expand.
3. Click on the ‘Resize Volume’ icon in the top right.

Once the volume has been expanded, you should be able to verify the disk volume has grown with lsblk. There should also be some messages by the kernel when this occurs. However, you will still need to expand any partitions, volumes, and filesystems on your system manually.

To expand your partition, use the growpart command followed by your disk device and partition number. Eg: /usr/bin/growpart /dev/vda 3

For LVM volume sets, you can expand the volume using the pvresize and lvresize commands:

• /usr/sbin/pvresize -y -q /dev/vda3
• /usr/sbin/lvresize -y -q -r -l +100%FREE /dev/mapper/<volume-name>

To expand your filesystem:

• XFS: /usr/sbin/xfs_growfs <volume>
• EXT: resize2fs <volume>

Destroying a VM

If you need to delete a VM, click on the red garbage bin icon in the VM instance page. All deletions are irreversible, so please make sure you have a copy of any data you need before proceeding.

CloudStack Delete VM

The VM root volume can be deleted immediately by enabling the 'Expunge' option in the dialog box. If left disabled, the VM root volume will linger for a day before it is deleted by the system. You may wish to expunge a volume if you are running low on space or volume quota.

Enabling High Availability (HA)

Virtual machines using one of the rcs or icelake compute offerings may be configured with high availability (HA) enabled. HA enabled virtual machines will be restarted if the underlying hardware crashes or becomes unavailable. This should be enabled for critical VMs in your infrastructure such as servers.

The bigmem compute offerings do not offer HA because there is limited big memory hosts available for CloudStack.

You may enable HA on a virtual machine by editing the virtual machine and toggling the 'HA enabled' option to the on state.

Virtual machine networking

By default, all CloudStack accounts come with a default virtual machine network that can be used for most general use cases. For more complex network setups, users can create additional guest networks that virtual machines can connect to. For example, you may wish to create an internal private network only for database traffic between your database server and web server.

A virtual machine network connects to the internet and the rest of campus through a virtual private cloud (VPC). Each VPC has a group of publicly accessible IP addresses as well as network policies (ACLs) that control what traffic is accepted.

The following diagram shows how a guest network connects to the internet and campus network.

CloudStack Guest Networking

To expose a virtual machine's services to campus or the internet, the appropriate port forwardings and ACL changes must be created on the VPC containing the guest network. More on this will be discussed in the next section.

Having multiple guest networks allows for more advanced network setups but is not required. We recommend using a single flat network for most workloads.

By default, all CloudStack accounts come with a default VPC and guest network set up with a NAT IP assigned. This default network is appropriate for most use cases.

IP addresses

Due to the design decisions made during the setup of the CloudStack platform, only internal 10.44.12X.X IPs can be assigned to your VPC. These IP addresses are accessible from the university campus network. However, there is a special section of IP addresses that can be accessed from the internet.

IP address range	Accessible from	Internet IP mapping
10.44.120.3-128	Campus, Internet	10.44.120.X maps to 136.159.140.X (ports 80 and 443 only)
10.44.120.129-255	Campus only	N/A
10.44.121.0-255	Campus only	N/A
10.44.122.0-255	Campus only	N/A
10.44.123.0-255	Campus only	N/A

If you need a service exposed to the internet, please request for a public IP address using our ServiceNow request form. Additionally, if your service is not port 80 or 443, you must also request for a firewall change request to allow the special port through.

Exposing a network service to campus

In order to make a virtual machine be visible to the campus network, you must first set up a port forwarding from a campus IP address to your virtual machine and allow the traffic in your network ACL.

To create a port forwarding, navigate to Network -> VPC -> Select your VPC -> Public IP Addresses. If you do not have any available IP addresses, you will need to click on 'Acquire New IP' and select an available IP address. Click on the IP address you wish to use to create a port forwarding on and then navigate to the 'Port Forwarding' tab. Enter the private port range, the public port range, the protocol, and select the target VM.

For example, to port forward only HTTP (tcp/80) traffic, you would enter the following:

CloudStack Port Forwarding

To update the ACL, navigate to Network -> VPC -> Select your VPC -> Network ACL lists -> Select your ACL. Alternatively, navigate to your guest network and click on the associated network ACL. Under the 'ACL list rules', you may add or remove rules to allow or deny network access. By default, the ACLs do not allow any incoming traffic except those explicitly listed. If you have non-standard ports being forwarded (anything other than 80 or 443), you must add an ACL rule to allow these ports for them to be accessible.

Once the port forwarding is created and the appropriate ACL added, you should be able to access the service from on campus. If for some reason access to your service does not work, there may be a firewall restriction on IT's network. In such circumstances, please contact us for assistance.

Exposing a network to the internet

Exposing a service to the internet is the same as exposing it to campus. However, you must create a port forwarding on an IP address that maps to an internet IP address outlined in the IP address table above. If your account does not have one of these IP addresses available, please request for one on the ServiceNow request form.

By default, only ports 80 and 443 are allowed through the Internet IP address. For all other ports, please create a firewall rule change request in ServiceNow.

Cloud-Init Automation

Ubuntu

The following Cloud-Init configs apply to Ubuntu VM templates.

Ubuntu desktop

Use the following Cloud-Init config with the Ubuntu Server template to set up an Ubuntu desktop environment. The setup step takes a up to 15 minutes to complete and you should see a login screen when the setup finishes.

Adjust the root and user password as desired. Below, the test user password is set to blank, allowing you to login to Gnome without a password.

#cloud-config
disable_root: false

write_files:
  - path: /usr/bin/expand_lvm_root
    content: |
      #!/bin/bash
      /usr/bin/growpart /dev/vda 3
      /usr/sbin/pvresize -y -q /dev/vda3
      /usr/sbin/lvresize -y -q -r -l +100%FREE /dev/mapper/ubuntu*
      /usr/sbin/resize2fs /dev/mapper/ubuntu*
    permissions: '0700'

users:
  - name: user
    lock_passwd: false
    inactive: false
    gecos: Test User
    primary_group: user
    groups: admin
    passwd: $1$ADUODeAy$eCJ1lPSxhSGmSvrmWxjLC1
    
# Install a graphical desktop
runcmd:
  - /usr/bin/expand_lvm_root
  - DEBIAN_FRONTEND=noninteractive apt -y update
  - DEBIAN_FRONTEND=noninteractive apt -y upgrade
  - DEBIAN_FRONTEND=noninteractive apt -y install tasksel
  - tasksel install gnome-desktop
  - systemctl set-default graphical.target
  - systemctl isolate graphical.target

Ubuntu with UC Authentication

Use the following Cloud-Init config to allow UC-based authentication. Local accounts with the same username as the IT account may use the IT credential to log in.

#cloud-config
disable_root: false

write_files:
  - path: /usr/bin/expand_lvm_root
    content: |
      #!/bin/bash
      /usr/bin/growpart /dev/vda 3
      /usr/sbin/pvresize -y -q /dev/vda3
      /usr/sbin/lvresize -y -q -r -l +100%FREE /dev/mapper/ubuntu*
      /usr/sbin/resize2fs /dev/mapper/ubuntu*
    permissions: '0700'

  - path: /etc/sssd/sssd.conf
    content: |
      [sssd]
      config_file_version = 2
      services = nss, pam, ifp
      domains = uc.ucalgary.ca
      [domain/uc.ucalgary.ca]
      id_provider = files
      debug_level = 5
      auth_provider = krb5
      chpass_provider = krb5
      krb5_realm = UC.UCALGARY.CA
      krb5_server = UC.UCALGARY.CA:88
      krb5_validate = false

  - path: /etc/krb5.conf
    content: |
      [logging]
       default = FILE:/var/log/krb5libs.log
       kdc = FILE:/var/log/krb5kdc.log
       admin_server = FILE:/var/log/kadmind.log
      [libdefaults]
       default_realm = UC.UCALGARY.CA
       dns_lookup_realm = false
       dns_lookup_kdc = false
       ticket_lifetime = 24h
       renew_lifetime = 7d
       forwardable = true
      [realms]
       UC.UCALGARY.CA = {
        kdc = uc.ucalgary.ca
       }
      [domain_realm]
       uc.ucalgary.ca = UC.UCALGARY.CA
       .uc.ucalgary.ca = UC.UCALGARY.CA

users:
  - name: myuofc.username
    lock_passwd: false
    inactive: false
    gecos: UofC User
    primary_group: user
    groups: admin


# Ensure VM has the largest / possible
# Install sss
runcmd:
  - /usr/bin/expand_lvm_root
  - DEBIAN_FRONTEND=noninteractive apt -y update
  - DEBIAN_FRONTEND=noninteractive apt -y upgrade
  - DEBIAN_FRONTEND=noninteractive apt -y install sssd-common sssd-krb5 sssd-krb5-common krb5-user sssd-dbus
  - chmod 600 /etc/sssd/sssd.conf
  - systemctl restart sssd
  - systemctl enable sssd
  - pam-auth-update --enable sss

Rocky Linux

The following Cloud-Init configs apply to Rocky Linux templates.

Rocky Linux Desktop

Use the following Cloud-Init config using the Rocky Linux template to set up a Rocky Linux desktop environment. The setup step takes up to 10 minutes to complete and you should see a login screen when the setup finishes.

Adjust the root and user password as desired. Below, the test user password is set to blank, allowing you to login to Gnome without a password.

#cloud-config
disable_root: false

users:
  - name: user
    lock_passwd: false
    inactive: false
    gecos: Test User
    primary_group: user
    groups: wheel
    passwd: $1$ADUODeAy$eCJ1lPSxhSGmSvrmWxjLC1
    
# Install a graphical desktop
runcmd:
  - yum -y install "@Workstation"
  - systemctl set-default graphical.target
  - systemctl isolate graphical.target

Rocky Linux Docker host

Use the following Cloud-Init config using the Rocky Linux template to set up a new docker host. This server can then be used to run Docker containers. Also included are:

1. The docker-compose utility to help deploy container stacks more easily
2. A helper script to expand the /var and / filesystems on first startup based on the available space in the ROOT volume.

Use the CloudStack generated password with the 'rocky' default user account to log in.

#cloud-config

write_files:
  - path: /usr/bin/expand_lvm_root
    content: |
      #!/bin/bash
      /usr/bin/growpart /dev/vda 3
      /usr/sbin/pvresize -y -q /dev/vda3
      /usr/sbin/lvresize -y -q -r -l +50%FREE /dev/mapper/*root
      /usr/sbin/lvresize -y -q -r -l +100%FREE /dev/mapper/*var
      /usr/sbin/xfs_growfs /
      /usr/sbin/xfs_growfs /var
    permissions: '0700'

  - path: /usr/bin/setup_docker
    content: |
      #!/bin/bash
      yum install -y yum-utils
      yum-config-manager \
         --add-repo \
         https://download.docker.com/linux/centos/docker-ce.repo
      yum install -y docker-ce docker-ce-cli containerd.io
      systemctl start docker
      systemctl enable docker
      
      curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
      chmod +x /usr/local/bin/docker-compose
    permissions: '0700'

  - path: /root/docker-compose.yml
    permissions: '0700'
    content: |
      version: '3.3'
      services:
        web:
          image: php:7.4-apache
          restart: always
          user: "0:0"
          volumes:
            - /var/www/html:/var/www/html
          ports:
            - "80:80"

  - path: /var/www/html/index.php
    permissions: '0644'
    content: |
      <h1>Hello there!</h1>
      <p>I see you from <?php echo $_SERVER['REMOTE_ADDR']; ?></p>
      <pre><?php print_r($_SERVER); ?></pre>
    
# Ensure VM has the largest / possible
runcmd:
  - /usr/bin/expand_lvm_root
  - /usr/bin/setup_docker
  - cd /root; docker-compose up -d

Rocky Linux with UC Authentication

Use the following Cloud-Init config to allow UC-based authentication. Local accounts with the same username as the IT account may use the IT credential to log in.

#cloud-config

write_files:
  - path: /usr/bin/setup_uc_auth
    permissions: '0700'
    content: |
      #!/bin/bash
      yum install -y sssd sssd-dbus sssd-krb5 krb5-workstation authselect-compat
      
      cat <<EOF > /etc/sssd/sssd.conf
      [sssd]
      config_file_version = 2
      services = nss, pam, ifp
      domains = uc.ucalgary.ca
      
      [domain/uc.ucalgary.ca]
      id_provider = files
      debug_level = 5
      auth_provider = krb5
      chpass_provider = krb5
      
      krb5_realm = UC.UCALGARY.CA
      krb5_server = UC.UCALGARY.CA:88
      krb5_validate = false
      EOF
      chmod 600 /etc/sssd/sssd.conf
      
      cat <<EOF > /etc/krb5.conf
      [logging]
       default = FILE:/var/log/krb5libs.log
       kdc = FILE:/var/log/krb5kdc.log
       admin_server = FILE:/var/log/kadmind.log
      
      [libdefaults]
       default_realm = UC.UCALGARY.CA
       dns_lookup_realm = false
       dns_lookup_kdc = false
       ticket_lifetime = 24h
       renew_lifetime = 7d
       forwardable = true
      
      [realms]
       UC.UCALGARY.CA = {
        kdc = itsodcsrv14.uc.ucalgary.ca
       }
      
      [domain_realm]
       uc.ucalgary.ca = UC.UCALGARY.CA
       .uc.ucalgary.ca = UC.UCALGARY.CA
      EOF
      
      mkdir -p /etc/authselect/custom/rcs
      cd /etc/authselect/custom/rcs
      echo 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 | base64 -d | tar -xzpf -
      
      if [[ "`authselect current -r`" != "custom/rcs" ]] ; then
        authselect select custom/rcs --force
        systemctl restart sssd
      fi
      
      systemctl enable sssd

runcmd:
  - /usr/bin/setup_uc_auth

Rocky Linux NFS server

Because there is no ability to share storage among multiple VMs, a local NFS server could be useful if you need to share data between multiple VMs.

#cloud-config

write_files:
  - path: /usr/bin/expand_lvm_root
    content: |
      #!/bin/bash
      /usr/bin/growpart /dev/vda 3
      /usr/sbin/pvresize -y -q /dev/vda3
      /usr/sbin/lvresize -y -q -r -l +50%FREE /dev/mapper/*root
      /usr/sbin/lvresize -y -q -r -l +100%FREE /dev/mapper/*var
      /usr/sbin/xfs_growfs /
      /usr/sbin/xfs_growfs /var
    permissions: '0700'

  - path: /usr/bin/setup_nfs
    content: |
      #!/bin/bash
      yum install -y nfs-utils

      mkdir /export
      if [ -b /dev/vdb ] ; then
        mkfs.xfs /dev/vdb
        echo "/dev/vdb  /export     xfs    defaults    1 2" >> /etc/fstab
        mount -a
      fi

      ip a | grep -w inet | awk '{print $2}' | while read subnet ; do
        echo "/export     $subnet(rw,no_subtree_check,no_root_squash,async)" >> /etc/exports
      done

      systemctl start nfs-server
      systemctl enable nfs-server
     
      exportfs -ra

    permissions: '0700'

runcmd:
  - /usr/bin/expand_lvm_root
  - /usr/bin/setup_nfs

NFS clients connected to the same network as the NFS server can then mount /export using a command similar to: mount -t nfs nfs-server:/export /mnt.

Infrastructure tools

Generating a CloudStack API

You can request for a CloudStack API key to automate infrastructure deployment using Terraform or CloudMonkey. A new API key can be generated by navigating to your profile page (top right) and then clicking on the 'Generate keys' button.

CloudStack API Key

CloudMonkey

CloudMonkey is a utility that makes it easier to interact with the CloudStack API. This tool may be used to help automate VM actions (such as start/stop/reboot), or infrastructure tasks (such as creating/destroying VMs, networks, or firewall rules).

To get started with CloudMonkey, refer to the following resources:

• Download from: https://github.com/apache/cloudstack-cloudmonkey/releases/tag/6.1.0
• Documentation at: https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI

Terraform Integration

Terraform allows you to define infrastructure as code and can be used in conjunction with CloudStack to configure your virtual machines and guest networks. Use the official CloudStack provider.

The following is an example Terraform file for reference. Specify your CloudStack API keys either as a separate vars.tf.

# Configure the CloudStack Provider
terraform {
  required_providers {
    cloudstack = {
      source = "cloudstack/cloudstack"
      version = "0.4.0"
    }
  }
}

provider "cloudstack" {
  api_url    = "${var.cloudstack_api_url}"
  api_key    = "${var.cloudstack_api_key}"
  secret_key = "${var.cloudstack_secret_key}"
}

# Create a new VPC
resource "cloudstack_vpc" "default" {
  name = "wedgenet-vpc"
  display_text = "wedgenet-vpc"
  cidr = "100.64.0.0/20"
  vpc_offering = "Default VPC offering"
  zone = "zone1"
}

# Create a new ACL
resource "cloudstack_network_acl" "default" {
    name  = "vpc-acl"
    vpc_id = "${cloudstack_vpc.default.id}"
}

# One ingress and one egress rule for the ACL
resource "cloudstack_network_acl_rule" "ingress" {
    acl_id = "${cloudstack_network_acl.default.id}"

    rule {
        action       = "allow"
        cidr_list    = ["0.0.0.0/0"]
        protocol     = "tcp"
        ports        = ["22", "80", "443"]
        traffic_type = "ingress"
    }
}

resource "cloudstack_network_acl_rule" "egress" {
    acl_id = "${cloudstack_network_acl.default.id}"

    rule {
        action       = "allow"
        cidr_list    = ["0.0.0.0/0"]
        protocol     = "all"
        traffic_type = "egress"
    }
}


# Create a new network in the VPC
resource "cloudstack_network" "primary" {
    name = "primary"
    display_text = "primary"
    cidr = "100.64.1.0/24"
    network_offering = "DefaultIsolatedNetworkOfferingForVpcNetworks"
    acl_id = "${cloudstack_network_acl.default.id}"
    vpc_id = "${cloudstack_vpc.default.id}"
    zone = "zone1"
}

# Create a new public IP address for this network
resource "cloudstack_ipaddress" "public_ip" {
    vpc_id = "${cloudstack_vpc.default.id}"
    network_id = "${cloudstack_network.wosnet1.id}"
}

# Create VMs. 
resource "cloudstack_instance" "vm" {
  count = 1
  name = "vm${count.index+1}"
  zone = "zone1"
  service_offering = "rcs.c4"
  template = "RockyLinux 8.5"
  network_id = "${cloudstack_network.wosnet1.id}"

  # Cloud Init data can be used to configure your VM on first startup if your template supports Cloud Init
  user_data = <<EOF
#cloud-config

# Require specific packages
packages:
 - tmux
 - git
 - tcpdump

EOF
}

Applying system updates

Research Computing Services strongly recommends users apply operating system updates as soon as possible. The commands used to apply system updates differ depending on the installed operating system.

Ubuntu / Debian based systems

Connect to the Linux system via the CloudStack console or through SSH, then:

1. Update the refresh package database: sudo apt update
2. Determine what packages will be updated: sudo apt list --upgradable
3. Apply the updates: sudo apt upgrade
4. You may wish to reboot the VM to apply all updates, such as when the kernel is updated: sudo reboot

Rocky Linux / Red Hat based systems

Connect to the Linux system via the CloudStack console or through SSH, then:

1. Clear any cached data in the package database: sudo dnf clean all
2. Apply all security updates: dnf update --security
3. You may wish to reboot the VM to apply all updates, such as when the kernel is updated: sudo reboot

For more information, please see Red Hat's documentation.

Troubleshooting

Cannot create a volume snapshot

Volume snapshots can only be taken on VMs that are powered off.

Cannot create a VM snapshot

Disk-only VM snapshots cannot be taken when the VM is running. If you intend to snapshot a running system, you must also snapshot its memory.

VM state is still running after shutdown

After running 'shutdown' on a VM, the VM state reported by CloudStack is still running.

Please try to do a force shutdown from the CloudStack management console. The VM state isn't updated by CloudStack and as a result, the state of a VM isn't properly reflected when power state changes outside of CloudStack (likely a bug?)