From 1a75ff9aa71d0611503e854e878d69c2f02f3e3d Mon Sep 17 00:00:00 2001 From: Alphaeus Mote Date: Mon, 28 Apr 2025 20:04:52 -0400 Subject: [PATCH] Update documentation to reflect new project structure --- Documentation/README.md | 54 +++++++- Documentation/guides/Installation.md | 30 +++- Module/README.md | 199 ++++----------------------- PSProxmox/README.md | 48 +++++++ README.md | 70 +++++++++- Scripts/README.md | 36 +++++ 6 files changed, 257 insertions(+), 180 deletions(-) create mode 100644 PSProxmox/README.md create mode 100644 Scripts/README.md diff --git a/Documentation/README.md b/Documentation/README.md index 9a76ddb..e6d4fa5 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -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. +## 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 - **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+ - .NET Framework 4.7.2 or .NET Core 2.0+ -## Quick Start +## Installation + +### From PowerShell Gallery (Recommended) ```powershell # Install from PowerShell Gallery 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-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. +## 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 Contributions are welcome! Please feel free to submit a Pull Request. diff --git a/Documentation/guides/Installation.md b/Documentation/guides/Installation.md index ad942ec..22b050a 100644 --- a/Documentation/guides/Installation.md +++ b/Documentation/guides/Installation.md @@ -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 ``` -### 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) 2. Extract the ZIP file @@ -37,7 +37,27 @@ You can also install the PSProxmox module directly from GitHub: .\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: @@ -47,12 +67,12 @@ You can manually install the PSProxmox module by copying the files to your Power For Windows 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: ```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 diff --git a/Module/README.md b/Module/README.md index f72c555..390c4ed 100644 --- a/Module/README.md +++ b/Module/README.md @@ -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 -# Install from PowerShell Gallery -Install-Module -Name PSProxmox -Scope CurrentUser +.\Scripts\build.ps1 ``` -## 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 -# Connect using username and password -$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" +.\Scripts\Install-PSProxmox.ps1 ``` -### 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 -# Get all VMs -$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 +Copy-Item -Path .\Module\* -Destination "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\PSProxmox" -Recurse -Force ``` -### Managing Templates - +For PowerShell Core: ```powershell -# Create a template from an existing VM -$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 +Copy-Item -Path .\Module\* -Destination "$env:USERPROFILE\Documents\PowerShell\Modules\PSProxmox" -Recurse -Force ``` -### Managing Storage +## Documentation -```powershell -# Get all storage -$storage = Get-ProxmoxStorage -Connection $connection +For detailed documentation, see the [Documentation](../Documentation) directory. -# 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. diff --git a/PSProxmox/README.md b/PSProxmox/README.md new file mode 100644 index 0000000..1c9cf9a --- /dev/null +++ b/PSProxmox/README.md @@ -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. diff --git a/README.md b/README.md index fdabdad..4988250 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,48 @@ # 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 +### From PowerShell Gallery (Recommended) + ```powershell # Install from PowerShell Gallery 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 ### Connecting to a Proxmox VE Server @@ -188,9 +222,41 @@ Clear-ProxmoxIPPool -Name "Production" 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 -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 diff --git a/Scripts/README.md b/Scripts/README.md new file mode 100644 index 0000000..3c7886c --- /dev/null +++ b/Scripts/README.md @@ -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.