CloudStack User Guide

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

Introduction

CloudStack is a 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. CloudStack is not appropriate for workloads requiring Windows since RCS and IT provides alternative solutions. Virtual machines can be accessed from the campus network. Web services running in the CloudStack infrastructure can also be exposed to the internet.

Access to CloudStack can be requested via ServiceNow.

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.

In order to access the CloudStack management console, you must connect from a IT-managed computer or through the IT General VPN. If you are connecting from off-campus or from an untrusted network such as AirUC, you must connect to the General VPN in order to access the CloudStack management console.

CloudStack VPN Connection

For help on connecting to the General VPN, please visit https://ucalgary.service-now.com/it?id=kb_article&sys_id=52a169d6dbe5bc506ad32637059619cd

Login to CloudStack

To log in to CloudStack, navigate to https://cloudstack.rcs.ucalgary.ca/. Most accounts will rely on your IT account via Single Sign-On. On the login page, click on the 'Single Sign-On' tab and then the 'Login' button. You will be redirected to our central authentication service where you can complete the login process using your IT credentials. You will also be asked to verify using a multi-factor authentication method such as with the Microsoft Authenticator app or a phone call.

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.

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

Other ways to access your CloudStack account

You may also choose to use other tools to manage your CloudStack resources including CloudMonkey and Terraform (using the CloudStack provider). In order to use these tools, you will need to generate a new API key on your account under your profile.

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.

Virtual machine credentials

Our included Rocky Linux VM template supports password handling through CloudStack. When you create a new VM using this template, a randomly generated 6 character password will be displayed.

CloudStack VM Password

For the Rocky Linux VM template, this password is applied to the 'rocky' user account on the virtual machine. You may become the super user by logging in as the rocky user and then running sudo su.

Note: Our Rocky Linux VM template has SSH password authentication enabled by default. You should be able to authenticate as the rocky user via SSH using the generated password and with a SSH key pair that you specified during the VM creation step. The root account is disabled by default and cannot be used to log in.

Choosing a virtual machine template

We provide a Rocky Linux 8.5 template for your convenience. Rocky Linux is an open source Linux distribution that is binary-compatible with Red Hat Enterprise Linux. Our Rocky Linux 8.5 image comes with Cloud-Init preconfigured and will accept any custom Cloud-Init user data payloads. Additionally, this template also supports CloudStack's VM password management system.

Creating a custom template

Alternatively, you may decide to install a custom OS such as a different Linux distribution or other UNIX based operating systems and create a template from that. To create a custom template:

1. Create a new virtual machine and select your custom ISO media. If you wish to upload your own ISO, see the 'register ISO' section below.
2. Start the virtual machine and proceed through the OS setup process
3. Once the system has been set up, prepare the VM to be templated by removing any host-specific files such as SSH host keys, static network configuration settings, temporary files and caches.
4. Power off the virtual machine
5. Navigate to the virtual machine page and click on the 'create template' button

CloudStack Instance Controls

Registering a custom 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. If you need a Windows VM, please contact us as we have alternative solutions.

Download a ISO from the internet

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

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

Virtual machine networking

The CloudStack platform allows you to define custom virtual private cloud (VPC) network which can contain any number of guest networks that your virtual machines connect to. Each guest network has its own private network address space and is not directly routable from campus or the internet. For virtual machines that require internet access, the VPC or guest network it is connected to must have a NAT IP address associated. The following diagram shows how a guest network connects to the internet and campus network.

CloudStack Guest Networking

In order to expose a virtual machine's services to campus or the internet, the appropriate port forwardings must be set up 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.

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
10.44.121.0-255	Campus only
10.44.122.0-255	Campus only
10.44.123.0-255	Campus only

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.

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

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.

Advanced tasks

Cloud-Init

Using our Rocky Linux template and the Cloud-Init feature that's built in to CloudStack, you can easily set up virtual machines for specific tasks without any manual setup.

Docker host

Use the following Cloud-Init config to set up a new docker host.

#cloud-config

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

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/*root
      /usr/sbin/xfs_growfs /
    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>
      '"`UNIQ--pre-00000001-QINU`"'
    
# Ensure VM has the largest / possible
runcmd:
  - /usr/bin/expand_lvm_root
  - /usr/bin/setup_docker
  - cd /root; docker-compose up -d

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

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

}