Skip to content

installation.md

Latest commit

 

History

History
359 lines (264 loc) · 10.7 KB

installation.md

File metadata and controls

359 lines (264 loc) · 10.7 KB

CloudStack Installation Guide

This document provides an automated installation guide for CloudStack 4.19 using Ansible.

Architecture

CloudStack is a distributed IaaS platform composed of multiple layers. The architecture deployed through this project is as follows.

Installation Architecture

Main Components

1. Gateway Node

  • NAT Gateway: Provides internet connectivity for Management network nodes
  • iptables Masquerade: Translates Management network traffic to Public network
  • IP Forwarding: Routes traffic between Management and Public networks
  • Purpose: Enables Management network nodes (Management Server, Database, KVM Hosts' management interface) to access the internet through NAT

Note: Gateway node is optional if your Management network already has direct internet access. It's required when Management network uses private IPs (e.g., 10.15.0.0/24) that need NAT to reach the internet.

2. Management Node

  • CloudStack Management Server: Central control and orchestration of entire cloud infrastructure
  • Usage Server: Resource usage tracking and billing

3. Database Node

  • MySQL 8.0: CloudStack Management Database

4. Storage Node

  • NFS Server: Provides Primary and Secondary Storage for VM disks and templates to Compute Nodes and Secondary Storage VMs

5. Compute Nodes (KVM Hosts)

  • KVM/QEMU: Virtual machine execution environment
  • CloudStack Agent: Communication agent with Management Server
  • Network Bridges:
    • cloudbr0: Management/Storage traffic
    • cloudbr1: Public/Guest traffic

Requirements

To build a CloudStack environment, the following hardware, software, and network requirements must be met.

Supported Environment

Item Version/Spec
CloudStack 4.19.3.0
OS <= Ubuntu 22.04 LTS (Noble)
Database MySQL 8.0
Java OpenJDK 11
Hypervisor KVM/QEMU
Network Mode Advanced Zone (VXLAN)
Automation Ansible 2.9+

Minimum Specifications by Node

Gateway Node (Optional)

Item Minimum Recommended
CPU 1 Core 2 Core
RAM 1 GB 2 GB
Disk 20 GB 50 GB
Network 2 NIC (Management + Public) 2 NIC (Management + Public)

When Gateway is required:

  • Management network uses private IPs without direct internet access
  • Need centralized NAT control for Management network traffic

Gateway node must have:

  • Network interface in Management network (e.g., 10.15.0.1)
  • Network interface in Public network with internet access (e.g., 10.10.0.1)
  • Both interfaces configured and routing enabled

CloudStack Networking

Management Node

Item Minimum Recommended
CPU 2 Core 4 Core
RAM 4 GB 8 GB
Disk 50 GB 100 GB (SSD)
Network 2 NIC (Management + Public) 2 NIC (Management + Public)

Database Node

Item Minimum Recommended
CPU 2 Core 4 Core
RAM 4 GB 8 GB
Disk 50 GB 200 GB (SSD)
Network 2 NIC (Management + Public) 2 NIC (Management + Public)

Storage Node (NFS)

Item Minimum Recommended
CPU 2 Core 4 Core
RAM 4 GB 8 GB
Disk 200 GB 500 GB+ (SSD)
Network 1 NIC (Public) 1 NIC (Public)

KVM Host (Compute Node)

Item Minimum Recommended
CPU 4 Core (VT-x/AMD-V support) 8+ Core (VT-x/AMD-V support)
RAM 8 GB 16 GB+
Disk 100 GB 500 GB+ (SSD)
Network 2 NIC (Management + Public) 2 NIC (Management + Public)

Important: KVM Host must have CPU virtualization support (Intel VT-x or AMD-V) enabled.

egrep -c 'vmx' /proc/cpuinfo

Network Requirements

CloudStack Advanced Zone requires at least 2 physically separated networks:

1️⃣ Management Network

  • CIDR Example: 10.15.0.0/24
  • Purpose:
    • CloudStack internal management traffic
    • Management Server ↔ Hypervisor communication
    • Hypervisor ↔ Storage(NFS) communication
    • Pod internal IP allocation
  • Required Nodes: All nodes (Management, Database, Storage, KVM Hosts)

2️⃣ Public Network

  • CIDR Example: 10.10.0.0/24
  • Purpose:
    • Guest VM internet connectivity
    • Public IP allocation (Floating IP)
    • System VM (SSVM, CPVM) external communication
    • Virtual Router external interface
  • Required Nodes: KVM Hosts only (Management is optional)

Gateway Configuration Notes:

  • Gateway acts as the router between Management (10.15.0.0/24) and Public (10.10.0.0/24) networks
  • Gateway should be set as the default route for Management network nodes
  • Management/Database nodes can optionally access internet via Gateway NAT instead of having direct Public IPsptional)

IP Allocation Plan Example

  • management server and database server can co-locate on the same node.
  • Public IP will be used for CloudStack System VMs (such as Secondary Storage VM, VNC proxy VM, Virtual Router).
Node Management IP (10.15.0.0/24) Public IP (10.10.0.0/24)
Management (Gateway) 10.15.0.1 10.10.0.10
Database 10.15.0.1 10.10.0.10
Storage (NFS) - 10.10.0.201
KVM Host 1 10.15.0.101 10.10.0.101
KVM Host 2 10.15.0.102 10.10.0.102
Gateway 10.15.0.1 10.10.0.1
Pod IP Range 10.15.0.2 - 10.15.0.254 -
Public IP Range - 10.10.100.1 - 10.10.100.254

Software Requirements

Ansible Controller (Local Machine)

  • Ansible 2.9 or higher
  • Python 3.8 or higher
  • SSH access available (root or sudo privileges)

Target Nodes

  • Ubuntu 24.04 LTS (Noble Numbat)
  • SSH server enabled
  • root or sudo privileged user
  • Internet connection (for package downloads)

Installation Steps

1. Setup Ansible Environment

Install Ansible on Local Machine

cd cloudstack/
./setup-ansible-controller.sh

2. Configure Inventory Files

After the Ansible controller setup, configure the inventory and variables:

Create and edit inventory file:

cp inventory/hosts.example inventory/hosts
vi inventory/hosts
### inventory/hosts
[gateway]
cloudstack-gateway ansible_host=10.10.0.1  # Gateway Node IP (optional)

[management]
cloudstack-mgmt ansible_host=10.10.0.10    # Management Server IP

[database]
cloudstack-db ansible_host=10.10.0.11      # Database Server IP

[kvm-hosts]
kvm-host-01 ansible_host=10.10.0.21        # KVM Host 1 IP

[cloudstack:vars]
ansible_user=root                           # SSH user (root or sudo user)

Gateway Configuration:

If you're using a Gateway node, uncomment the [gateway] section and specify its Public network IP. The Gateway must have interfaces in both Management and Public networks

[cloudstack:vars]
ansible_user=root                     # SSH user (root or sudo user)

Important:

  • When using root user: Root account login must be allowed in SSH (PermitRootLogin yes in /etc/ssh/sshd_config)
  • When using sudo user: Set ansible_user to a user with sudo privileges and add --ask-become-pass option when running playbook

Configure passwords:

vi inventory/group_vars/all/vault.yml

Set passwords for root, MySQL, and CloudStack.

Configure network settings:

Set network CIDRs, gateway, and storage paths according to the Network Requirements section for CIDR examples.

vi inventory/group_vars/all/all.yml

Important: Bridge names will be used as Traffic Labels during Zone configuration.

Please refer to the comments in each file and OPTIONS.md for detailed configuration options.

3. Copy SSH Keys

Run the SSH key distribution script:

sudo ./copy-ssh-keys.sh

This script will:

  • Check or generate SSH key if not exists
  • Read hosts from inventory/hosts
  • Copy SSH public key to all target servers

Connection Test:

# Ansible connection test
ansible all -i inventory/hosts -m ping

4. CloudStack Deployment

Full Automated Installation (Recommended)

# Automated installation of all components (steps 00~04), when using root user
ansible-playbook -i inventory/hosts playbooks/site.yml

# When using Vault encryption
ansible-playbook -i inventory/hosts playbooks/site.yml --ask-vault-pass

Gateway Setup Verification: After running gateway setup, verify the configuration:

# On Gateway node, check IP forwarding
sysctl net.ipv4.ip_forward  # Should return: net.ipv4.ip_forward = 1

# Check NAT rules
sudo iptables -t nat -L POSTROUTING -v

# Test connectivity from Management network node
# On Management/Database node, ping external IP through Gateway
ping -c 3 8.8.8.8
# 3. Management Server installation
ansible-playbook -i inventory/hosts playbooks/03-setup-management.yml

# 4. Gateway Node (if configured)
# Verify IP forwarding and NAT rules
sysctl net.ipv4.ip_forward
sudo iptables -t nat -L -n -v | grep MASQUERADE

# On Management Server
systemctl status cloudstack-management

# On Database Server
systemctl status mysql

# On KVM Host
systemctl status libvirtd

Gateway Post-Installation State: After successful gateway setup, the following should be in place:

  • ✅ IP forwarding enabled (net.ipv4.ip_forward = 1)
  • ✅ iptables NAT MASQUERADE rule for Management network → Public interface
  • ✅ iptables FORWARD rules allowing bidirectional traffic
  • ✅ iptables rules persisted to /etc/iptables/rules.v4
  • ✅ Management network nodes can reach internet through Gateway# Access Management Server
# Access Management Server UI
http://[Management-Server-IP]:8080/client

Default Login Credentials:

  • Username: admin
  • Password: password

Check Service Status

# On Management Server
systemctl status cloudstack-management

# On Database Server
systemctl status mysql

# On KVM Host
systemctl status libvirtd

Next Steps

After completing the installation, proceed with Zone configuration to make CloudStack operational:

Zone Configuration Guide

The Zone configuration includes:

  • Installing CloudMonkey CLI tool
  • Generating API keys
  • Creating and configuring CloudStack Zone
  • Adding storage and compute resources
  • Enabling the Zone

Troubleshooting

For details, see troubleshooting.md.

References