From c666235082e5d1a4be18bac10d6209d57baf0f42 Mon Sep 17 00:00:00 2001 From: Timur Kumakbayev Date: Sun, 18 Jan 2026 05:00:39 +0500 Subject: [PATCH] Build script and documentation updates (#83) --- .gitignore | 2 + README.md | 417 +++++++++++++++++++++++++++++++++++++------ debian/control | 9 +- scripts/build_deb.sh | 95 ++++++++++ 4 files changed, 471 insertions(+), 52 deletions(-) create mode 100755 scripts/build_deb.sh diff --git a/.gitignore b/.gitignore index 371605f..a0accee 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,5 @@ tests/test_results.txt /*.deb *.log *.substvars +build/ +changelog diff --git a/README.md b/README.md index 7d8d887..14f1eed 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,13 @@ disks, providing high performance and reliability. - [Multipath Configuration](#multipath-configuration) - [iSCSI Configuration](#iscsi-configuration) - [Installation](#installation) - - [Manual](#manual) - - [APT](#apt) + - [Manual Installation](#manual-installation) + - [Debian Package Installation (Recommended)](#debian-package-installation-recommended) - [Configuration](#configuration) - [Troubleshooting](#troubleshooting) + - [Debug Logging](#debug-logging) + - [Service Status](#service-status) + - [Diagnostic Commands](#diagnostic-commands) - [Known issues](#known-issues) - [Contributing](#contributing) @@ -93,7 +96,7 @@ blacklist_exceptions { } ``` -## iSCSI Configuration +### iSCSI Configuration Initiate iSCSI according to the Proxmox Guidelines. @@ -108,35 +111,106 @@ sudo iscsiadm -m node --op update -n node.startup -v automatic ## Installation -There are two methods to install the plugin: manual installation and APT -package installation. +There are two methods to install the plugin: manual installation and Debian +package installation via APT. -### Manual +> [!IMPORTANT] +> If you are using a cluster setup, install the plugin on all nodes in the +> cluster. The storage configuration will be automatically synchronized via +> corosync, but the plugin code must be present on each node. -To manually install the plugin, follow these steps: +### Manual Installation + +Manual installation is useful for development or when you want to install +from source. + +#### Step 1: Install required dependencies ```bash -# Clone repository -git clone https://github.com/kolesa-team/pve-purestorage-plugin.git -# Navigate to the Plugin Directory -cd pve-purestorage-plugin -# Create the custom plugin directory if it does not already exist -mkdir /usr/share/perl5/PVE/Storage/Custom -# Copy plugin to custom plugin directory -cp PureStoragePlugin.pm /usr/share/perl5/PVE/Storage/Custom/PureStoragePlugin.pm -# Restart Proxmox VE -systemctl restart pve-cluster.service pvedaemon.service pvestatd.service pveproxy.service pvescheduler.service +sudo apt-get update +sudo apt-get install -y \ + libwww-perl \ + libjson-perl \ + libjson-xs-perl ``` -### APT - -**Note**: Replace `` with your desired version number -(e.g., `0.0.1`). +#### Step 2: Clone the repository ```bash -PACKAGE_VERSION="" curl -L -o libpve-storage-purestorage-perl.deb "https://github.com/kolesa-team/pve-purestorage-plugin/releases/download/v$PACKAGE_VERSION/libpve-storage-purestorage-perl_$PACKAGE_VERSION-1_all.deb" +git clone https://github.com/kolesa-team/pve-purestorage-plugin.git +cd pve-purestorage-plugin +``` -sudo apt install ./libpve-storage-purestorage-perl.deb +#### Step 3: Install the plugin + +```bash +# Create the custom plugin directory +sudo mkdir -p /usr/share/perl5/PVE/Storage/Custom + +# Copy plugin file +sudo cp PureStoragePlugin.pm /usr/share/perl5/PVE/Storage/Custom/PureStoragePlugin.pm + +# Set correct permissions +sudo chmod 644 /usr/share/perl5/PVE/Storage/Custom/PureStoragePlugin.pm +``` + +#### Step 4: Restart Proxmox VE services + +```bash +sudo systemctl restart pvedaemon.service pveproxy.service +``` + +#### Step 5: Verify installation + +```bash +pvesm status +# The purestorage type should now be available +``` + +### Debian Package Installation (Recommended) + +Installing via Debian package is the recommended method as it handles +dependencies automatically and provides easy updates. + +#### Step 1: Download the package* + +Replace `` with the desired version (e.g., `0.0.1`). Check +the [releases page](https://github.com/kolesa-team/pve-purestorage-plugin/releases) +for available versions. + +```bash +PACKAGE_VERSION="" +wget "https://github.com/kolesa-team/pve-purestorage-plugin/releases/download/v${PACKAGE_VERSION}/libpve-storage-purestorage-perl_${PACKAGE_VERSION}-1_all.deb" +``` + +#### Step 2: Install the package + +```bash +sudo apt install ./libpve-storage-purestorage-perl_${PACKAGE_VERSION}-1_all.deb +``` + +#### Step 3: Verify installation + +```bash +dpkg -l | grep libpve-storage-purestorage-perl +# Should show the installed package version +``` + +#### To upgrade to a newer version + +```bash +# Download new version +PACKAGE_VERSION="" +wget "https://github.com/kolesa-team/pve-purestorage-plugin/releases/download/v${PACKAGE_VERSION}/libpve-storage-purestorage-perl_${PACKAGE_VERSION}-1_all.deb" + +# Upgrade +sudo apt install ./libpve-storage-purestorage-perl_${PACKAGE_VERSION}-1_all.deb +``` + +#### To uninstall + +```bash +sudo apt remove libpve-storage-purestorage-perl ``` ## Configuration @@ -229,15 +303,18 @@ steps: ### Debug Logging -Enable debug logging to diagnose issues: +The plugin provides detailed debug logging to help diagnose issues. Debug +output is written to syslog and can be viewed in Proxmox logs. -**Persistent (via configuration):** +**Enable debug logging:** + +Persistent (via configuration): ```bash pvesm set --debug 1 ``` -**Temporary (for single command, when debug is not set in config):** +Temporary (for single command, when debug is not set in config): ```bash PURESTORAGE_DEBUG=1 pvesm list @@ -246,12 +323,12 @@ PURESTORAGE_DEBUG=1 pvesm list > **Note:** If `debug` is set in storage configuration, it takes priority > over `PURESTORAGE_DEBUG` environment variable. -Debug levels: +**Debug levels:** - `0` - Off (production, default) -- `1` - Basic (token operations, main function calls) -- `2` - Verbose (HTTP requests, token validation details) -- `3` - Trace (all internal operations) +- `1` - Basic (token operations, main function calls, volume operations) +- `2` - Verbose (HTTP requests, token validation, API responses) +- `3` - Trace (all internal operations, detailed flow) **Example debug output:** @@ -264,6 +341,47 @@ Debug :: Token is valid (age: 125s) Debug :: Using cached token from file (age: 125s) ``` +**Common debug scenarios:** + +Debug volume creation: + +```bash +PURESTORAGE_DEBUG=2 pvesm alloc 10G +``` + +Debug volume deletion: + +```bash +PURESTORAGE_DEBUG=2 pvesm free : +``` + +Debug API authentication issues: + +```bash +PURESTORAGE_DEBUG=3 pvesm status +``` + +**View debug logs:** + +Check Proxmox daemon logs: + +```bash +journalctl -u pvedaemon -f +``` + +Filter for PureStorage plugin messages: + +```bash +journalctl -u pvedaemon | grep -E "(Debug ::|Info ::|Warning ::|Error ::)" +``` + +Check token cache status: + +```bash +ls -lah /etc/pve/priv/purestorage/ +cat /etc/pve/priv/purestorage/_array0.json | jq . +``` + ### Service Status Ensure that the Proxmox VE services are running correctly. You can restart @@ -273,33 +391,195 @@ the services if necessary: sudo systemctl restart pve-cluster.service pvedaemon.service pvestatd.service pveproxy.service pvescheduler.service ``` -### Network and Storage +### Diagnostic Commands -- Verify Network Connectivity: Ensure that the Proxmox VE nodes can reach - the Pure Storage array over the network. Check for firewall rules or - network issues that might be blocking communication. -- Review Logs: Check the Proxmox VE logs for any error messages related to - storage or the plugin. Logs are typically found in /var/log/pve. These - commands are helpful for troubleshooting: +**Multipath diagnostics:** - ```bash - multipath -ll -v3 #diagnose issues with the multipath service - iscsiadm -m node #list what iscsi nodes are mounted - ls -l /dev/mapper/3624a9370* #list wwids of Pure mapped devices on the system - ``` +List all multipath devices with details: -- Multipath Configuration: Verify that your multipath.conf is correctly - configured and that multipath devices are recognized. Use multipath -ll - to list the current multipath devices. -- API Token Permissions: Ensure that the API token used has the necessary - permissions to create and manage volumes on the Pure Storage array. -- Plugin Updates: Ensure you are using the latest version of the plugin. - Check the GitHub repository for updates. +```bash +multipath -ll +``` + +Verbose multipath debugging: + +```bash +multipath -ll -v3 +``` + +Show only Pure Storage devices: + +```bash +multipath -ll | grep -A 10 "3624a9370" +``` + +Reload multipath configuration: + +```bash +systemctl reload multipathd +``` + +**iSCSI diagnostics:** + +List all iSCSI sessions: + +```bash +iscsiadm -m session +``` + +Show detailed session information: + +```bash +iscsiadm -m session -P 3 +``` + +List all discovered targets: + +```bash +iscsiadm -m node +``` + +Rescan iSCSI sessions: + +```bash +iscsiadm -m session --rescan +``` + +**PureStorage volume diagnostics:** + +List all Pure Storage mapped devices: + +```bash +ls -l /dev/mapper/3624a9370* +``` + +Show device information: + +```bash +lsblk | grep "3624a9370" +``` + +Check device WWIDs: + +```bash +/lib/udev/scsi_id --whitelisted --device=/dev/mapper/3624a9370 +``` + +Show device mapper table: + +```bash +dmsetup table +``` + +Show device mapper dependencies: + +```bash +dmsetup deps -o devname +``` + +List all device mapper devices: + +```bash +dmsetup ls --tree +``` + +Show detailed info for specific device: + +```bash +dmsetup info /dev/mapper/3624a9370 +``` + +**Partition management (kpartx):** + +List partitions on a device: + +```bash +kpartx -l /dev/mapper/3624a9370 +``` + +Add partition mappings: + +```bash +kpartx -a /dev/mapper/3624a9370 +``` + +Remove partition mappings: + +```bash +kpartx -d /dev/mapper/3624a9370 +``` + +Sync partition table: + +```bash +kpartx -u /dev/mapper/3624a9370 +``` + +**Storage plugin diagnostics:** + +List all volumes on storage: + +```bash +pvesm list +``` + +Show storage status: + +```bash +pvesm status +``` + +Scan for new volumes: + +```bash +pvesm scan +``` + +Test volume allocation (dry-run): + +```bash +pvesm alloc test-volume 1G +pvesm free :test-volume +``` + +**Network connectivity:** + +Test API endpoint connectivity: + +```bash +curl -k https:///api/2.30/arrays +``` + +Test with API token: + +```bash +curl -k -X POST https:///api/2.30/login \ + -H "Content-Type: application/json" \ + -d '{"api_token":""}' +``` + +Check iSCSI portal connectivity: + +```bash +nc -zv 3260 +``` + +**Common issues:** + +- **API Token Permissions**: Ensure the API token has sufficient permissions + to create and manage volumes on the Pure Storage array +- **Multipath Configuration**: Verify multipath.conf is correctly configured + and multipath devices are recognized +- **Network Connectivity**: Check firewall rules and network routes to Pure + Storage array +- **Plugin Updates**: Ensure you are using the latest version of the plugin ### Known issues -- `lvm inside a volume`: If you plan to use LVM inside a volume, it is - better to add purestorage volumes to the ignore list to avoid scanning. +**LVM inside a volume:** + +If you plan to use LVM inside a volume, it is better to add purestorage +volumes to the ignore list to avoid scanning. ```bash cat /etc/lvm/lvmlocal.conf @@ -310,6 +590,41 @@ devices { } ``` +**Debug output contamination ([#56](https://github.com/kolesa-team/pve-purestorage-plugin/issues/56)):** + +When debug logging is enabled, debug messages may contaminate command +outputs that should be clean (e.g., `qm showcmd`, `pvesm path`). This can +break tools that parse these outputs. + +Workaround: Disable debug logging when using commands that need clean output: + +```bash +pvesm set --debug 0 +``` + +Or use temporary debug only when needed: + +```bash +PURESTORAGE_DEBUG=1 +``` + +**Volume auto-mount issues ([#59](https://github.com/kolesa-team/pve-purestorage-plugin/issues/59)):** + +The `filesystem_path` function returns device paths that may not work +reliably when volumes are deactivated. This affects operations like +`qm showcmd` and backup tools (e.g., Veeam) that need direct access to +volume paths. + +Current behavior: Volumes are activated on-demand and may deactivate when +not in use. + +Workaround: Ensure volumes are activated before accessing them directly. +For automated workflows, consider implementing volume activation in your +scripts. + +Note: A proper solution using autofs for automatic volume mounting is being +evaluated. + ## Contributing Contributions to this project are welcome. diff --git a/debian/control b/debian/control index 15bf494..d0de1b5 100644 --- a/debian/control +++ b/debian/control @@ -10,10 +10,17 @@ Build-Depends: debhelper, devscripts Package: libpve-storage-purestorage-perl Architecture: all -Depends: ${perl:Depends}, ${misc:Depends}, libpve-storage-perl (>= 8.2.1), multipath-tools +Depends: ${perl:Depends}, ${misc:Depends}, + libpve-storage-perl (>= 8.2.1), + multipath-tools, + libjson-xs-perl, + libwww-perl, + liburi-perl Description: Pure Storage integration library for Proxmox VE This package provides a Perl library to integrate Pure FlashArray Storage systems with the Proxmox VE storage management infrastructure. . It allows administrators to configure and manage Pure FlashArray Storage devices directly within the Proxmox VE environment. + . + Supports Proxmox VE 8.2+ and Proxmox VE 9+. diff --git a/scripts/build_deb.sh b/scripts/build_deb.sh new file mode 100755 index 0000000..b53380a --- /dev/null +++ b/scripts/build_deb.sh @@ -0,0 +1,95 @@ +#!/bin/bash +set -e + +# Build Debian package locally using Docker +# This script mimics the CI/CD build process for local testing + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_DIR="$(dirname "$SCRIPT_DIR")" +BUILD_IMAGE="debian:bookworm" + +echo "Building Debian package locally..." + +# Check if Docker is available +if ! command -v docker &> /dev/null; then + echo "Error: Docker is not installed or not in PATH" + exit 1 +fi + +# Run build in Docker container +docker run --rm \ + -v "$PROJECT_DIR:/workspace" \ + -w /workspace \ + "$BUILD_IMAGE" \ + bash -c ' + set -e + + echo "Installing build dependencies..." + apt-get update -qq + apt-get install -y -qq \ + debhelper \ + devscripts \ + build-essential \ + git + + echo "Installing package build dependencies..." + apt-get build-dep -y . || true + + echo "Generating changelog..." + pkgname=libpve-storage-purestorage-perl + tag_list=$(git tag -l | grep -ve "-rc\.[0-9]$" | grep -ve "-beta\.[0-9]$" | sort -V) + + if [ -z "$tag_list" ]; then + echo "Warning: No tags found, using default version" + echo "$pkgname (0.0.1-1) stable; urgency=medium" > debian/changelog + echo "" >> debian/changelog + echo " * Initial release" >> debian/changelog + echo "" >> debian/changelog + echo " -- Local Build $(date -R)" >> debian/changelog + else + prevtag="" + for tag in ${tag_list}; do + tag_header="$tag^..$tag" + tag_info=$prevtag..$tag + tag_version=$(echo $tag | cut -c2-)-1 + + if [[ "$prevtag" == "" ]]; then + tag_header="$tag" + tag_info="$tag" + elif [[ "$tag" == "$prevtag" ]]; then + continue + fi + + echo >> changelog + git log --pretty="format: -- %aN <%aE> %aD%n%n" $tag_header >> changelog + git log --pretty=format:" * %s%n" $tag_info >> changelog + echo "" >> changelog + echo "$pkgname ($tag_version) stable; urgency=medium" >> changelog + + prevtag=$tag + done + + tac changelog > debian/changelog + fi + + echo "Building package..." + dpkg-buildpackage -us -uc -b + + echo "Generating checksums..." + cd .. + sha256sum *.deb > sha256sums 2>/dev/null || true + + echo "Moving files to build output directory..." + mkdir -p /workspace/build + mv *.deb *.buildinfo *.changes sha256sums /workspace/build/ 2>/dev/null || true + + echo "Build complete!" + echo "" + echo "Generated files:" + ls -lh /workspace/build/ + ' + +echo "" +echo "Package built successfully!" +echo "Output files are in the build/ directory:" +ls -lh "$PROJECT_DIR"/build/*.deb 2>/dev/null || echo "No .deb files found"