gsadmin/PSProxmox
1
0
Fork 0
mirror of https://github.com/Grace-Solutions/PSProxmox.git synced 2026-08-31 01:09:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation to reflect new project structure

Browse Source
This commit is contained in:
Alphaeus Mote
2025-04-28 20:04:52 -04:00
parent 1ffbaa4fa9
commit 1a75ff9aa7
6 changed files with 257 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/README.md
+53 -1
View File
@@ -2,6 +2,14 @@
PSProxmox is a C#-based PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for interacting with Proxmox VE API, featuring structured return objects, mass deployment tools, automatic IP management, and more. PSProxmox is a C#-based PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for interacting with Proxmox VE API, featuring structured return objects, mass deployment tools, automatic IP management, and more.
## Project Structure
- **Module/**: Contains the PowerShell module files
- **PSProxmox/**: Contains the C# source code for the module
- **Documentation/**: Contains detailed documentation and examples
- **Scripts/**: Contains build and installation scripts
- **Release/**: Contains built releases (created by build script)
## Features ## Features
- **Session Management**: Authenticate and persist sessions with Proxmox VE clusters - **Session Management**: Authenticate and persist sessions with Proxmox VE clusters
@@ -29,12 +37,32 @@ PSProxmox is a C#-based PowerShell module for managing Proxmox VE clusters. It p
- PowerShell 5.1 or PowerShell 7+ - PowerShell 5.1 or PowerShell 7+
- .NET Framework 4.7.2 or .NET Core 2.0+ - .NET Framework 4.7.2 or .NET Core 2.0+
## Quick Start ## Installation
### From PowerShell Gallery (Recommended)
```powershell ```powershell
# Install from PowerShell Gallery # Install from PowerShell Gallery
Install-Module -Name PSProxmox -Scope CurrentUser Install-Module -Name PSProxmox -Scope CurrentUser
```
### Manual Installation
```powershell
# Clone the repository
git clone https://github.com/freedbygrace/PSProxmox.git
cd PSProxmox
# Build the module
.\Scripts\build.ps1
# Install the module
.\Scripts\Install-PSProxmox.ps1
```
## Quick Start
```powershell
# Import the module # Import the module
Import-Module PSProxmox Import-Module PSProxmox
@@ -67,6 +95,30 @@ For detailed documentation on each cmdlet, you can:
4. Read the [Guides](guides/README.md) for comprehensive guides on various topics. 4. Read the [Guides](guides/README.md) for comprehensive guides on various topics.
## Development
### Building the Module
To build the module from source:
```powershell
# Run the build script
.\Scripts\build.ps1
```
This will:
1. Compile the C# code
2. Create a versioned release in the Release folder
3. Update the Module folder with the latest build
4. Create a ZIP package for distribution
### Project Organization
- **C# Source Code**: All C# source code is in the PSProxmox folder
- **PowerShell Module**: The PowerShell module files are in the Module folder
- **Documentation**: Comprehensive documentation is in the Documentation folder
- **Scripts**: Build and installation scripts are in the Scripts folder
## Contributing ## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. Contributions are welcome! Please feel free to submit a Pull Request.
Documentation/guides/Installation.md
+25 -5
View File
@@ -25,9 +25,9 @@ If you want to install it for all users on the system, run the following command
Install-Module -Name PSProxmox -Scope AllUsers Install-Module -Name PSProxmox -Scope AllUsers
``` ```
### Method 2: Install from GitHub ### Method 2: Install from GitHub Release
You can also install the PSProxmox module directly from GitHub: You can also install the PSProxmox module directly from a GitHub release:
1. Download the latest release from the [GitHub repository](https://github.com/freedbygrace/PSProxmox/releases) 1. Download the latest release from the [GitHub repository](https://github.com/freedbygrace/PSProxmox/releases)
2. Extract the ZIP file 2. Extract the ZIP file
@@ -37,7 +37,27 @@ You can also install the PSProxmox module directly from GitHub:
.\Install-PSProxmox.ps1 .\Install-PSProxmox.ps1
``` ```
### Method 3: Manual Installation ### Method 3: Build and Install from Source
You can build and install the PSProxmox module from source:
1. Clone the repository:
```powershell
git clone https://github.com/freedbygrace/PSProxmox.git
cd PSProxmox
```
2. Build the module:
```powershell
.\Scripts\build.ps1
```
3. Install the module:
```powershell
.\Scripts\Install-PSProxmox.ps1
```
### Method 4: Manual Installation
You can manually install the PSProxmox module by copying the files to your PowerShell modules directory: You can manually install the PSProxmox module by copying the files to your PowerShell modules directory:
@@ -47,12 +67,12 @@ You can manually install the PSProxmox module by copying the files to your Power
For Windows PowerShell: For Windows PowerShell:
```powershell ```powershell
Copy-Item -Path .\PSProxmox-Dist\* -Destination "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\PSProxmox" -Recurse -Force Copy-Item -Path .\* -Destination "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\PSProxmox" -Recurse -Force
``` ```
For PowerShell Core: For PowerShell Core:
```powershell ```powershell
Copy-Item -Path .\PSProxmox-Dist\* -Destination "$env:USERPROFILE\Documents\PowerShell\Modules\PSProxmox" -Recurse -Force Copy-Item -Path .\* -Destination "$env:USERPROFILE\Documents\PowerShell\Modules\PSProxmox" -Recurse -Force
``` ```
## Verifying the Installation ## Verifying the Installation
Module/README.md
+27 -172
View File
@@ -1,193 +1,48 @@
# PSProxmox # PSProxmox Module
PSProxmox is a PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for managing virtual machines, storage, networks, users, roles, and more. This directory contains the PowerShell module files for PSProxmox.
## Installation ## Structure
- **PSProxmox.psd1**: The module manifest file
- **bin/**: Contains the compiled DLL
## Building the Module
The module is built using the build script in the Scripts directory:
```powershell ```powershell
# Install from PowerShell Gallery .\Scripts\build.ps1
Install-Module -Name PSProxmox -Scope CurrentUser
``` ```
## Getting Started This will compile the C# code from the PSProxmox directory and place the DLL in the bin directory.
### Connecting to a Proxmox VE Server ## Installing the Module
You can install the module using the installation script in the Scripts directory:
```powershell ```powershell
# Connect using username and password .\Scripts\Install-PSProxmox.ps1
$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force
$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Username "root" -Password $securePassword -Realm "pam"
# Connect using a credential object
$credential = Get-Credential
$connection = Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam"
``` ```
### Managing Virtual Machines This will copy the module files to your PowerShell modules directory.
## Manual Installation
You can manually install the module by copying the files to your PowerShell modules directory:
For Windows PowerShell:
```powershell ```powershell
# Get all VMs Copy-Item -Path .\Module\* -Destination "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\PSProxmox" -Recurse -Force
$vms = Get-ProxmoxVM -Connection $connection
# Get a specific VM
$vm = Get-ProxmoxVM -Connection $connection -VMID 100
# Create a new VM
$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Name "test-vm" -Memory 2048 -Cores 2 -DiskSize 32 -Start
# Create a new VM using the builder pattern
$builder = New-ProxmoxVMBuilder -Name "web-server"
$builder.WithMemory(4096)
.WithCores(2)
.WithDisk(50, "local-lvm")
.WithNetwork("virtio", "vmbr0")
.WithIPConfig("192.168.1.10/24", "192.168.1.1")
.WithStart($true)
$vm = New-ProxmoxVM -Connection $connection -Node "pve1" -Builder $builder
# Start, stop, and restart VMs
Start-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100
Stop-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100
Restart-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100
# Remove a VM
Remove-ProxmoxVM -Connection $connection -Node "pve1" -VMID 100 -Confirm:$false
``` ```
### Managing Templates For PowerShell Core:
```powershell ```powershell
# Create a template from an existing VM Copy-Item -Path .\Module\* -Destination "$env:USERPROFILE\Documents\PowerShell\Modules\PSProxmox" -Recurse -Force
$template = New-ProxmoxVMTemplate -Connection $connection -VMID 100 -Name "Ubuntu-Template" -Description "Ubuntu 20.04 Template"
# Get all templates
$templates = Get-ProxmoxVMTemplate
# Create a VM from a template
$vm = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" -Name "web01" -Start
# Create multiple VMs from a template
$vms = New-ProxmoxVMFromTemplate -Connection $connection -Node "pve1" -TemplateName "Ubuntu-Template" -Prefix "web" -Count 3 -Start
``` ```
### Managing Storage ## Documentation
```powershell For detailed documentation, see the [Documentation](../Documentation) directory.
# Get all storage
$storage = Get-ProxmoxStorage -Connection $connection
# Get storage on a specific node
$storage = Get-ProxmoxStorage -Connection $connection -Node "pve1"
# Create a new storage
$storage = New-ProxmoxStorage -Connection $connection -Name "backup" -Type "dir" -Path "/mnt/backup" -Content "backup,iso"
# Remove a storage
Remove-ProxmoxStorage -Connection $connection -Name "backup" -Confirm:$false
```
### Managing Networks
```powershell
# Get all network interfaces on a node
$networks = Get-ProxmoxNetwork -Connection $connection -Node "pve1"
# Create a new bridge interface
$network = New-ProxmoxNetwork -Connection $connection -Node "pve1" -Interface "vmbr1" -Type "bridge" -BridgePorts "eth1" -Method "static" -Address "192.168.2.1" -Netmask "255.255.255.0" -Autostart
# Remove a network interface
Remove-ProxmoxNetwork -Connection $connection -Node "pve1" -Interface "vmbr1" -Confirm:$false
```
### Managing Users and Roles
```powershell
# Get all users
$users = Get-ProxmoxUser -Connection $connection
# Create a new user
$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force
$user = New-ProxmoxUser -Connection $connection -Username "john" -Realm "pam" -Password $securePassword -FirstName "John" -LastName "Doe" -Email "john.doe@example.com"
# Remove a user
Remove-ProxmoxUser -Connection $connection -UserID "john@pam" -Confirm:$false
# Get all roles
$roles = Get-ProxmoxRole -Connection $connection
# Create a new role
$role = New-ProxmoxRole -Connection $connection -RoleID "Developer" -Privileges "VM.Allocate", "VM.Config.Disk", "VM.Config.CPU", "VM.PowerMgmt"
# Remove a role
Remove-ProxmoxRole -Connection $connection -RoleID "Developer" -Confirm:$false
```
### Managing SDN
```powershell
# Get all SDN zones
$zones = Get-ProxmoxSDNZone -Connection $connection
# Create a new SDN zone
$zone = New-ProxmoxSDNZone -Connection $connection -Zone "zone1" -Type "vlan" -Bridge "vmbr0"
# Remove an SDN zone
Remove-ProxmoxSDNZone -Connection $connection -Zone "zone1" -Confirm:$false
# Get all SDN VNets
$vnets = Get-ProxmoxSDNVnet -Connection $connection
# Create a new SDN VNet
$vnet = New-ProxmoxSDNVnet -Connection $connection -VNet "vnet1" -Zone "zone1" -IPv4 "192.168.1.0/24" -Gateway "192.168.1.1"
# Remove an SDN VNet
Remove-ProxmoxSDNVnet -Connection $connection -VNet "vnet1" -Confirm:$false
```
### Managing Clusters
```powershell
# Get cluster information
$cluster = Get-ProxmoxCluster -Connection $connection
# Join a node to a cluster
$securePassword = ConvertTo-SecureString "password" -AsPlainText -Force
Join-ProxmoxCluster -Connection $connection -ClusterName "cluster1" -HostName "pve1" -Password $securePassword
# Leave a cluster
Leave-ProxmoxCluster -Connection $connection -Force
# Create a cluster backup
$backup = New-ProxmoxClusterBackup -Connection $connection -Compress -Wait
# Restore a cluster backup
Restore-ProxmoxClusterBackup -Connection $connection -BackupID "vzdump-cluster-2023_04_28-12_00_00.vma.lzo" -Force -Wait
```
### Managing IP Addresses
```powershell
# Create a new IP pool
$pool = New-ProxmoxIPPool -Name "Production" -CIDR "192.168.1.0/24" -ExcludeIPs "192.168.1.1", "192.168.1.254"
# Get all IP pools
$pools = Get-ProxmoxIPPool
# Get a specific IP pool
$pool = Get-ProxmoxIPPool -Name "Production"
# Clear an IP pool
Clear-ProxmoxIPPool -Name "Production"
```
## Disconnecting
```powershell
# Disconnect from the server
Disconnect-ProxmoxServer -Connection $connection
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
PSProxmox/README.md
+48
View File
@@ -0,0 +1,48 @@
# PSProxmox Source Code
This directory contains the C# source code for the PSProxmox module.
## Structure
- **Client/**: Contains the API client code
- **Cmdlets/**: Contains the PowerShell cmdlet implementations
- **IPAM/**: Contains the IP address management code
- **Models/**: Contains the data models
- **Session/**: Contains the session management code
- **Templates/**: Contains the template management code
- **Utilities/**: Contains utility functions
- **bin/**: Contains the compiled DLL (created during build)
- **obj/**: Contains intermediate build files (created during build)
- **PSProxmox.Main.csproj**: The main project file
- **PSProxmox.Main.sln**: The solution file
## Building
The source code is built using the build script in the Scripts directory:
```powershell
.\Scripts\build.ps1
```
This will compile the C# code and place the DLL in the Module\bin directory.
## Development
### Adding a New Cmdlet
1. Create a new file in the Cmdlets directory
2. Implement the cmdlet class
3. Add the cmdlet to the CmdletsToExport array in the Module\PSProxmox.psd1 file
### Adding a New Model
1. Create a new file in the Models directory
2. Implement the model class
### Adding a New API Client Method
1. Add the method to the ProxmoxApiClient class in the Client directory
## Documentation
For detailed documentation, see the [Documentation](../Documentation) directory.
README.md
+68 -2
View File
@@ -1,14 +1,48 @@
# PSProxmox # PSProxmox
PSProxmox is a PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for managing virtual machines, storage, networks, users, roles, and more. PSProxmox is a C#-based PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for interacting with Proxmox VE API, featuring structured return objects, mass deployment tools, automatic IP management, and more.
## Features
- **Session Management**: Authenticate and persist sessions with Proxmox VE clusters
- **Core CRUD Operations**: Manage VMs, Storage, Network, Users, Roles, SDN, and Clusters
- **Templates**: Create and use VM deployment templates
- **Mass Creation**: Bulk create VMs with prefix/counter
- **IP Management**: CIDR parsing, subnetting, FIFO IP queue assignment
- **Structured Objects**: All outputs are typed C# classes (PowerShell-native)
- **Pipeline Support**: Cmdlets support pipeline input where appropriate
## Project Structure
- **Module/**: Contains the PowerShell module files
- **PSProxmox/**: Contains the C# source code for the module
- **Documentation/**: Contains detailed documentation and examples
- **Scripts/**: Contains build and installation scripts
- **Release/**: Contains built releases (created by build script)
## Installation ## Installation
### From PowerShell Gallery (Recommended)
```powershell ```powershell
# Install from PowerShell Gallery # Install from PowerShell Gallery
Install-Module -Name PSProxmox -Scope CurrentUser Install-Module -Name PSProxmox -Scope CurrentUser
``` ```
### Manual Installation
```powershell
# Clone the repository
git clone https://github.com/freedbygrace/PSProxmox.git
cd PSProxmox
# Build the module
.\Scripts\build.ps1
# Install the module
.\Scripts\Install-PSProxmox.ps1
```
## Getting Started ## Getting Started
### Connecting to a Proxmox VE Server ### Connecting to a Proxmox VE Server
@@ -188,9 +222,41 @@ Clear-ProxmoxIPPool -Name "Production"
Disconnect-ProxmoxServer -Connection $connection Disconnect-ProxmoxServer -Connection $connection
``` ```
## Development
### Building the Module
To build the module from source:
```powershell
# Run the build script
.\Scripts\build.ps1
```
This will:
1. Compile the C# code
2. Create a versioned release in the Release folder
3. Update the Module folder with the latest build
4. Create a ZIP package for distribution
### Project Organization
- **C# Source Code**: All C# source code is in the PSProxmox folder
- **PowerShell Module**: The PowerShell module files are in the Module folder
- **Documentation**: Comprehensive documentation is in the Documentation folder
- **Scripts**: Build and installation scripts are in the Scripts folder
## Documentation ## Documentation
For detailed documentation, see the [Documentation](Documentation) directory. For detailed documentation, see the [Documentation](Documentation) directory. The documentation includes:
- [Cmdlet Reference](Documentation/cmdlets/README.md)
- [Examples](Documentation/examples/README.md)
- [Guides](Documentation/guides/README.md)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License ## License
Scripts/README.md
+36
View File
@@ -0,0 +1,36 @@
# PSProxmox Scripts
This directory contains scripts for building and installing the PSProxmox module.
## Scripts
- **build.ps1**: Builds the PSProxmox module
- **Install-PSProxmox.ps1**: Installs the PSProxmox module
## Building the Module
To build the module, run the build.ps1 script:
```powershell
.\build.ps1
```
This will:
1. Compile the C# code
2. Create a versioned release in the Release folder
3. Update the Module folder with the latest build
4. Create a ZIP package for distribution
## Installing the Module
To install the module, run the Install-PSProxmox.ps1 script:
```powershell
.\Install-PSProxmox.ps1
```
This will copy the module files to your PowerShell modules directory.
## Documentation
For detailed documentation, see the [Documentation](../Documentation) directory.