Balance-VMs.ps1

<#
.SYNOPSIS
    Balances VMs across hosts in a vCenter cluster, ensuring no host exceeds the specified VM limit.

.DESCRIPTION
    This script connects to a vCenter server using encrypted credentials, identifies overloaded hosts within a specified cluster,
    and migrates VMs to underloaded hosts to maintain a balanced distribution. It excludes specified VMs from migration
    based on their names or assigned tags. Additionally, it includes an enhanced dry-run mode to simulate migrations safely.

.AUTHOR
    virtualox

.GITHUB_REPOSITORY
    https://github.com/virtualox/VM-Balancer

.LICENSE
    This script is licensed under the GPL-3.0 License. See the LICENSE file for more information.

.USAGE
    .\Balance-VMs.ps1 [-DryRun]

.PARAMETER DryRun
    Executes the script in simulation mode without performing actual migrations. Useful for testing and verifying actions.

.NOTES
    - Ensure that the encryption key and encrypted credentials have been set up using Generate-EncryptionKey.ps1 and Create-VCenterCredentials.ps1.
    - Adjust the configuration variables and exclusion criteria within the script as needed.
    - The script requires appropriate permissions to migrate VMs within the specified vCenter cluster.
#>

param (
    [switch]$DryRun
)

# === Configuration Variables ===

# Path to the encryption key file
$encryptionKeyPath = "C:\Secure\Credentials\encryptionKey.key"  # <-- Must match the key generated by Generate-EncryptionKey.ps1

# Path to the encrypted credentials file
$credentialPath = "C:\Secure\Credentials\vcCredentials.xml"     # <-- Must match the credential path used in Create-VCenterCredentials.ps1

# vCenter Server details
$vcServer = "your_vcenter_server"       # <-- Replace with your vCenter server name or IP
$clusterName = "YourClusterName"        # <-- Replace with your cluster name

# VM balancing settings
$maxVMsPerHost = 60                     # Maximum number of VMs per host

# Exclusion Settings

## Name-Based Exclusion
# Specify exact VM names or use wildcards for patterns
$excludeVMNames = @(
    "cp-replica-*",    # Exclude VMs with names starting with 'cp-replica-'
    "horizon-*",       # Exclude VMs managed by Horizon (assuming they start with 'horizon-')
    "*-replica*",      # Exclude any VM containing '-replica' in its name
    "Important-VM1",   # Exclude specific VM by exact name
    "Critical-VM2"     # Add more as needed
)

## Tag-Based Exclusion
# Specify the names of tags assigned to VMs that should be excluded
$excludeVMTags = @(
    "DoNotMigrate",
    "Infrastructure",
    "VDI"
)

# === End of Configuration Variables ===

# Import the PowerCLI module
Import-Module VMware.PowerCLI -ErrorAction Stop

# Suppress certificate warnings (optional, remove if not needed)
Set-PowerCLIConfiguration -InvalidCertificateAction Ignore -Confirm:$false

# Function to check if the encryption key exists
function Test-EncryptionKeyExists {
    param (
        [string]$Path
    )
    return (Test-Path -Path $Path)
}

# Function to check if the credentials file exists
function Test-CredentialsFileExists {
    param (
        [string]$Path
    )
    return (Test-Path -Path $Path)
}

# Function to retrieve credentials
function Get-Credentials {
    param (
        [string]$KeyPath,
        [string]$CredPath
    )
    try {
        # Read the encryption key
        $key = Get-Content -Path $KeyPath -Encoding Byte

        # Read the encrypted credentials JSON
        $credentialJson = Get-Content -Path $CredPath -Raw | ConvertFrom-Json

        $username = $credentialJson.Username
        $encryptedPassword = $credentialJson.EncryptedPassword

        # Decrypt the password
        $securePassword = $encryptedPassword | ConvertTo-SecureString -Key $key

        # Create PSCredential object
        $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $securePassword

        return $cred
    }
    catch {
        Write-Error "Failed to retrieve and decrypt credentials: $_"
        exit 1
    }
}

# Function to check if the host is eligible (connected and not in maintenance mode)
function Is-HostEligible {
    param (
        $VMHost
    )
    return ($VMHost.ConnectionState -eq 'Connected' -and -not $VMHost.ExtensionData.Runtime.InMaintenanceMode)
}


# Function to apply exclusion filters to VMs
function Apply-ExclusionFilters {
    param (
        [VMware.VimAutomation.ViCore.Impl.V1.Inventory.VirtualMachineImpl]$VM
    )
    # Name-Based Exclusion
    foreach ($pattern in $excludeVMNames) {
        if ($VM.Name -like $pattern) {
            return $false
        }
    }

    # Tag-Based Exclusion
    foreach ($tag in $excludeVMTags) {
        if ($VM.Tags -contains $tag) {
            return $false
        }
    }

    return $true
}

# Function to secure the script execution
function Verify-Security {
    # Ensure encryption key exists
    if (-not (Test-EncryptionKeyExists -Path $encryptionKeyPath)) {
        Write-Error "Encryption key not found at '$encryptionKeyPath'. Please generate it using Generate-EncryptionKey.ps1 and store credentials using Create-VCenterCredentials.ps1."
        exit 1
    }

    # Ensure credentials file exists
    if (-not (Test-CredentialsFileExists -Path $credentialPath)) {
        Write-Error "Encrypted credentials file not found at '$credentialPath'. Please store credentials using Create-VCenterCredentials.ps1."
        exit 1
    }
}

# Function to get host object by name
function Get-HostByName {
    param (
        [string]$Name
    )
    return $hosts | Where-Object { $_.Name -eq $Name }
}

# Main Execution

# Verify security prerequisites
Verify-Security

# Retrieve credentials
$cred = Get-Credentials -KeyPath $encryptionKeyPath -CredPath $credentialPath

# Connect to vCenter
try {
    Connect-VIServer -Server $vcServer -Credential $cred -ErrorAction Stop
    Write-Output "Successfully connected to vCenter Server '$vcServer'."
}
catch {
    Write-Error "Failed to connect to vCenter Server '$vcServer'. $_"
    exit 1
}

# Get the cluster object
$cluster = Get-Cluster -Name $clusterName -ErrorAction SilentlyContinue

if (-not $cluster) {
    Write-Error "Cluster '$clusterName' not found."
    Disconnect-VIServer -Server $vcServer -Confirm:$false
    exit 1
}

# Get all eligible hosts in the cluster
$hosts = Get-VMHost -Location $cluster | Where-Object { Is-HostEligible -VMHost $_ }

if ($hosts.Count -eq 0) {
    Write-Error "No eligible hosts found in cluster '$clusterName'. Ensure that hosts are not in Maintenance or Disconnected states."
    Disconnect-VIServer -Server $vcServer -Confirm:$false
    exit 1
}

# Create a hashtable to store host VM counts
$hostVMCounts = @{}

foreach ($vmHost in $hosts) {
    # Retrieve all VMs on the host
    $vmsOnHost = Get-VM -Location $vmHost -ErrorAction SilentlyContinue

    # Apply Exclusion Filters
    $vmsToConsider = $vmsOnHost | Where-Object { Apply-ExclusionFilters -VM $_ }

    # Count the number of VMs to consider for migration
    $vmCount = $vmsToConsider.Count
    $hostVMCounts[$vmHost.Name] = $vmCount
}

# Identify overloaded and underloaded hosts
$overloadedHosts = $hostVMCounts.GetEnumerator() | Where-Object { $_.Value -gt $maxVMsPerHost } | Sort-Object -Property Value -Descending
$underloadedHosts = $hostVMCounts.GetEnumerator() | Where-Object { $_.Value -lt $maxVMsPerHost } | Sort-Object -Property Value

if ($overloadedHosts.Count -eq 0) {
    Write-Output "All hosts have $maxVMsPerHost VMs or fewer. No balancing needed."
    Disconnect-VIServer -Server $vcServer -Confirm:$false
    exit 0
}

if ($underloadedHosts.Count -eq 0) {
    Write-Output "No hosts available with less than $maxVMsPerHost VMs to migrate VMs to."
    Disconnect-VIServer -Server $vcServer -Confirm:$false
    exit 0
}

# Start balancing
foreach ($overloaded in $overloadedHosts) {
    $overHostName = $overloaded.Key
    $overHostVMCount = $overloaded.Value
    $overHost = Get-HostByName -Name $overHostName

    $vmsToMoveCount = $overHostVMCount - $maxVMsPerHost

    if ($vmsToMoveCount -le 0) {
        continue
    }

    Write-Output "Host '$overHostName' is overloaded with $overHostVMCount VMs. Need to move $vmsToMoveCount VMs."

    # Get VMs on the overloaded host, excluding replicas and tagged VMs, sorted by power state (optional: adjust sorting as needed)
    $vmsOnOverHost = Get-VM -Location $overHost | Where-Object { Apply-ExclusionFilters -VM $_ } | Sort-Object -Property PowerState

    foreach ($vm in $vmsOnOverHost) {
        # Check again if there are still VMs to move
        if ($vmsToMoveCount -le 0) {
            break
        }

        # Find a target host that is underloaded and can host the VM
        $targetHostEntry = $underloadedHosts | Where-Object { $_.Value -lt $maxVMsPerHost } | Sort-Object -Property Value | Select-Object -First 1

        if ($targetHostEntry) {
            $targetHostName = $targetHostEntry.Key
            $targetHostObj = Get-HostByName -Name $targetHostName

            # Additional check to ensure the target host is still eligible
            if ($targetHostObj.ConnectionState -ne 'Connected' -or $targetHostObj.ExtensionData.Runtime.InMaintenanceMode) {
                Write-Warning "Target host '$targetHostName' is no longer eligible. Skipping."
                # Remove the host from underloaded list
                $underloadedHosts = $underloadedHosts | Where-Object { $_.Key -ne $targetHostName }
                continue
            }

            if ($DryRun) {
                Write-Output "[Dry-Run] Would migrate VM '$($vm.Name)' from '$overHostName'."

                # Simulate the migration by updating the VM counts
                $hostVMCounts[$overHostName] -= 1
                $hostVMCounts[$targetHostName] += 1

                # Update the underloaded hosts list if the target host reaches the limit
                if ($hostVMCounts[$targetHostName] -ge $maxVMsPerHost) {
                    $underloadedHosts = $underloadedHosts | Where-Object { $_.Key -ne $targetHostName }
                }

                $vmsToMoveCount -= 1
            }
            else {
                Write-Output "Migrating VM '$($vm.Name)' from '$overHostName' to '$targetHostName'. (Hardware Version: $($vm.HardwareVersion))"

                try {
                    # Perform the migration
                    Move-VM -VM $vm -Destination $targetHostObj -ErrorAction Stop

                    # Update the VM counts
                    $hostVMCounts[$overHostName] -= 1
                    $hostVMCounts[$targetHostName] += 1

                    # Update the underloaded hosts list if the target host reaches the limit
                    if ($hostVMCounts[$targetHostName] -ge $maxVMsPerHost) {
                        $underloadedHosts = $underloadedHosts | Where-Object { $_.Key -ne $targetHostName }
                    }

                    $vmsToMoveCount -= 1
                }
                catch {
                    Write-Warning "Failed to migrate VM '$($vm.Name)': $_"
                }
            }
        }
        else {
            Write-Warning "No available target hosts with less than $maxVMsPerHost VMs to migrate VM '$vm.Name'."
            break
        }
    }
}

Write-Output "VM balancing complete."

# Disconnect from vCenter
Disconnect-VIServer -Server $vcServer -Confirm:$false