Skip to content

Commit 053e20a

Browse files
datacore-chiranthjsdatacore-chiranthjs
authored
Adding Proxmox Storage Plugin for SANsymphony (#12)
* Adding Proxmox Storage Plugin for SANsymphony * adding Debian repo here for more visibility
1 parent 1a9f050 commit 053e20a

File tree

22 files changed

+5272
-0
lines changed

22 files changed

+5272
-0
lines changed

‎SANsymphony/Proxmox Storage Plugin/LICENSE‎

Lines changed: 218 additions & 0 deletions
Large diffs are not rendered by default.

‎SANsymphony/Proxmox Storage Plugin/README.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# DataCore Storage Plugin for Proxmox VE
2+
3+
A Proxmox VE storage plugin to integrate [DataCore SANsymphony™](https://www.datacore.com/products/sansymphony/) storage using iSCSI, with native multipath support and custom CLI management.
4+
5+
---
6+
7+
Note: All the mentioned installation destination will be changed to the same github repo once we publish the plugin and we will also attach the Web help link once its live
8+
-
9+
10+
---
11+
12+
## 📚 Table of Contents
13+
14+
1. [Overview](#-overview)
15+
3. [Prerequisites](#%EF%B8%8F-prerequisites)
16+
4. [Installation](#-installation)
17+
- [Using APT Repository (Recommended)](#-recommended-using-apt-repository)
18+
- [Using Debian Package (.deb)](#-alternative-debian-package-deb)
19+
5. [Configuration](#%EF%B8%8F-configuration)
20+
- [Using ssy-plugin (Recommended)](#-recommended-using-ssy-plugin-command)
21+
- [Using pvesm add command](#-using-pvesm-add-command)
22+
- [Manual storage.cfg editing](#-manually-editing-storage-configuration-file-etcpvestoragecfg)
23+
7. [Troubleshooting](#-troubleshooting)
24+
25+
---
26+
27+
<br/>
28+
29+
# ✨ Overview
30+
31+
The plugin enables shared iSCSI storage managed by DataCore SANsymphony to be used directly from Proxmox VE. You can manage storage via the Proxmox UI/CLI or using the built-in `ssy-plugin` command-line interface.
32+
33+
Key capabilities include:
34+
- Management of multiple iSCSI sessions with multipath support
35+
- Seamless provisioning of shared Virtual Disks (VDs)
36+
- LVM support on top of SANsymphony VDs
37+
- Compatibility with both Proxmox UI and CLI
38+
- An interactive wrapper CLI tool (`ssy-plugin`) for simplified management
39+
40+
<br/>
41+
42+
# ⚠️ Prerequisites
43+
44+
- Ensure the `VD Template` is already created in SANsymphony.
45+
46+
If installing via `.deb`:
47+
- Install `jq` and `multipath-tools` manually.
48+
- Enable `multipath` and configure `udev rules` manually (see [Host Configuration Guide](https://dcsw.atlassian.net/wiki/spaces/ProxmoxDoc/pages/8528330757/Host+Configuration+Guide+PVE)).
49+
50+
<br/>
51+
52+
# 📦 Installation
53+
54+
## ✅ Recommended: Using APT Repository
55+
56+
Run these commands **on each Proxmox node**:
57+
58+
### 1. Import GPG Key
59+
```bash
60+
wget -P /usr/share/keyrings https://cjsstorage.blob.core.windows.net/datacore/ssy-pgp-key.public
61+
```
62+
63+
### 2. Add Apt Source
64+
```bash
65+
echo "deb [signed-by=/usr/share/keyrings/ssy-pgp-key.public] \
66+
https://cjsstorage.blob.core.windows.net/datacore/ssy-apt-repo stable main" \
67+
| tee /etc/apt/sources.list.d/ssy.list
68+
```
69+
70+
### 3. Update & Install Plugin
71+
```bash
72+
apt update
73+
apt install ssy-plugin
74+
```
75+
76+
## 🗂 Alternative: Debian Package (.deb)
77+
78+
Use this method if you cannot access the apt repo from the PVE node.
79+
80+
### 1. Download the package
81+
```bash
82+
wget https://cjsstorage.blob.core.windows.net/datacore/SANsymphony-plugin_1.0.0_amd64.deb
83+
```
84+
85+
### 2. Install it
86+
```bash
87+
dpkg -i SANsymphony-plugin_1.0.0_amd64.deb
88+
```
89+
90+
<br/>
91+
92+
# ⚙️ Configuration
93+
94+
> [!TIP]
95+
> In a cluster setup, configuration only needs to be performed on one node.
96+
97+
After installing the plugin, configure Proxmox VE to use it. Since Proxmox VE does not currently support adding custom storage plugins via the GUI, use the `pvesm` command or the built-in `ssy-plugin` command:
98+
99+
## 🧭 Recommended: Using `ssy-plugin` command
100+
101+
The `ssy-plugin` tool can be used in two modes:
102+
103+
### 1. Interactive Mode
104+
105+
Launches a prompt-based interface for guided use.
106+
107+
```bash
108+
ssy-plugin
109+
```
110+
111+
Sample menu:
112+
```
113+
Please select the Operation type:
114+
1. Add SANsymphony Storage class (SSY)
115+
2. Add LVM Storage class (LVM)
116+
3. Remove existing Storage class
117+
4. Display SSY multipath status
118+
```
119+
120+
### 2. Non-Interactive Mode (Direct Command Execution)
121+
122+
You can also run individual commands directly from the shell, passing all parameters via flags.
123+
124+
View help:
125+
```bash
126+
ssy-plugin -h
127+
```
128+
129+
**Syntax:**
130+
```bash
131+
ssy-plugin [ACTION] [OPTIONS]
132+
```
133+
134+
| ACTION | Description |
135+
| ----------- | ------------------------------------------------------------------------------ |
136+
| `ssy` | Add a new SANsymphony storage class. |
137+
| `lvm` | Add a new LVM (Logical Volume Manager) storage class. |
138+
| `remove` | Remove an existing storage class. |
139+
| `multipath` | Display the current SANsymphony multipath connection status for iSCSI targets. |
140+
141+
| OPTION | Description |
142+
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
143+
| LVMname | The name of the LVM storage class. |
144+
| LVMsize | Size of the LVM storage class in GiB. |
145+
| SSYname | The name of the SANsymphony (SSY) storage class. |
146+
| SSYipAddress | One or more comma-separated SANsymphony management IP addresses. Ensure Proxmox nodes can reach these IPs. |
147+
| SSYusername | The username used to authenticate with the SANsymphony REST API. |
148+
| SSYpassword | The password used to authenticate with the SANsymphony REST API. |
149+
| vdTemplateName | The name of the Virtual Disk Template to use for provisioning disks from SANsymphony. This template must already exist in SANsymphony. |
150+
| portals | One or more iSCSI FrontEnd portal IP addresses for SANsymphony, comma-separated. Use `all` to auto-discover FE iSCSI connections. |
151+
| nodes | A comma-separated list of Proxmox node names. Use `all` to include all PVE nodes in the cluster. |
152+
| shared | (`optional`) Set to `1` if the storage class should be shared across all nodes. If omitted, the storage class is treated as local. |
153+
| disable | (`optional`) Set to `1` to temporarily disable the storage class without removing it. |
154+
| default | (`optional`) Set to `1` to use default parameters where applicable. |
155+
156+
**Examples:**
157+
```bash
158+
ssy-plugin ssy \
159+
--SSYname SSY-example \
160+
--SSYipAddress 10.15.0.1,10.15.0.2 \
161+
--SSYusername administrator \
162+
--SSYpassword Password \
163+
--vdTemplateName Mirrored-VD \
164+
--portals all \
165+
--nodes all \
166+
--shared 1 \
167+
--disable 0
168+
```
169+
```bash
170+
ssy-plugin ssy \
171+
--SSYname SSY-example \
172+
--SSYipAddress 10.15.0.1,10.15.0.2 \
173+
--SSYusername administrator \
174+
--SSYpassword Password \
175+
--vdTemplateName Mirror-VD \
176+
--default 1
177+
```
178+
```bash
179+
ssy-plugin lvm \
180+
--LVMname SSY-LVM-example \
181+
--LVMsize 1024 \
182+
--SSYname SSY-example \
183+
--default 1
184+
```
185+
```bash
186+
ssy-plugin multipath
187+
```
188+
```bash
189+
ssy-plugin remove
190+
```
191+
192+
## 🧭 Using `pvesm add` command
193+
194+
You can also directly use the `pvesm add` command:
195+
196+
```bash
197+
pvesm add ssy <SSY Storage Class Name> \
198+
--SSYipAddress <SSY Management IP Address list> \
199+
--SSYusername <SSY Username> \
200+
--SSYpassword <SSY Password> \
201+
--portals <SSY FrontEnd iSCSI portals list> \
202+
--targets <SSY FrontEnd iSCSI Target IQN list> \
203+
--vdTemplateName <SSY Virtual Disk Template Name> \
204+
--nodes <Proxmox Node Names list> \
205+
--shared 1 \
206+
--disable 0
207+
```
208+
209+
## 🧭 Manually editing storage configuration file `/etc/pve/storage.cfg`
210+
211+
```bash
212+
ssy: <SSY Storage Class Name>
213+
DCipAddress <SSY Management IP Address list>
214+
DCusername <SSY Username>
215+
DCpassword <SSY Password>
216+
portals <SSY FrontEnd iSCSI portals list>
217+
targets <SSY FrontEnd iSCSI Target IQN list>
218+
vdTemplateName <SSY Virtual Disk Template Name>
219+
nodes <Proxmox Node Names list>
220+
shared 1
221+
disable 0
222+
```
223+
224+
| Parameter | Description |
225+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
226+
| storage_id | The storage identifier (name under which it will appear in the Proxmox Storage list). |
227+
| SSYipAddress | One or more comma-separated SANsymphony management IP addresses. Ensure Proxmox nodes can reach these IPs. |
228+
| SSYusername | The username used to authenticate with the SANsymphony REST API. |
229+
| SSYpassword | The password used to authenticate with the SANsymphony REST API. |
230+
| portals | One or more iSCSI FE portal IP addresses, comma-separated. These are used for initiator connections. |
231+
| targets | One or more iSCSI target IQNs (Initiator Qualified Names), comma-separated. |
232+
| vdTemplateName | The name of the Virtual Disk Template to use for provisioning disks from DataCore. This template must already exist in SANsymphony. |
233+
| nodes | (`optional`) A comma-separated list of Proxmox node names. Use this parameter to restrict the plugin to specific nodes. If omitted, the storage is available on all nodes. |
234+
| shared | (`optional`) Set to `1` to mark the storage as shared across all nodes. If omitted, the storage is treated as local. |
235+
| disable | (`optional`) Set to `1` to temporarily disable the storage without deleting it. |
236+
237+
**Example:**
238+
```
239+
ssy: Storage-Name
240+
DCipAddress 10.15.1.19,10.15.1.18
241+
DCusername administrator
242+
DCpassword Password
243+
portals 10.15.1.17,10.151.1.16
244+
targets iqn.2000-08.com.datacore:ssy1-1,iqn.2000-08.com.datacore:ssy2-1
245+
vdTemplateName SSY-VDT
246+
nodes pve1,pve2
247+
shared 1
248+
disable 0
249+
```
250+
251+
<br/>
252+
253+
# 🛠 Troubleshooting
254+
255+
If you encounter issues while using the plugin, consider the following steps:
256+
257+
- **Check Service Status:** Ensure that the Proxmox VE services are running correctly. You can restart the services if necessary:
258+
```bash
259+
systemctl restart pvedaemon pveproxy pvestatd pvescheduler
260+
```
261+
- **Verify Network Connectivity:** Ensure that the Proxmox VE nodes can reach SANsymphony over the network. Check for firewall rules or network issues that might be blocking communication.
262+
- **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`.
263+
Useful commands:
264+
```bash
265+
journalctl -xe # displays Proxmox logs
266+
multipath -ll -v3 # diagnose issues with the multipath service
267+
iscsiadm -m node # list what iSCSI nodes are mounted
268+
```
269+
- **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.
270+
- **SANsymphony User Permissions:** Ensure that the SANsymphony user has the necessary permissions to create and manage storage.
271+
- **Plugin Updates:** Ensure you are using the latest version of the plugin.

‎SANsymphony/Proxmox Storage Plugin/SANsymphony-plugin_1.0.0_amd64.deb‎

18.5 KB
Binary file not shown.

‎SANsymphony/Proxmox Storage Plugin/SANsymphony-plugin_1.0.0_amd64/DEBIAN/control‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Source: ssy-plugin
2+
Package: ssy-plugin
3+
Version: 1.0.0
4+
Maintainer: Chiranth J S <chiranth.js@datacore.com>
5+
Architecture: amd64
6+
Depends: python3 (>= 3.6), jq, open-iscsi, multipath-tools
7+
Description: A proxmox storage plugin for DataCore SANsymphony.
8+
Section: utils
9+
Priority: optional
10+

‎SANsymphony/Proxmox Storage Plugin/SANsymphony-plugin_1.0.0_amd64/DEBIAN/postinst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/bin/bash
2+
set -e
3+
4+
# appling datacore recommended iSCSI configuration settings.
5+
/usr/bin/ssy-configure-iscsid apply
6+
7+
# Reloading udev rules after adding datacore udev rules.
8+
echo "Reloading udev rules..."
9+
udevadm control --reload
10+
udevadm trigger
11+
12+
# Restart multipath-tools after the config file was updated
13+
echo "Restarting multipath-tools..."
14+
systemctl restart multipath-tools
15+
16+
exit 0

‎SANsymphony/Proxmox Storage Plugin/SANsymphony-plugin_1.0.0_amd64/etc/multipath.conf‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
defaults {
2+
user_friendly_names yes
3+
polling_interval 60
4+
find_multipaths "smart"
5+
}
6+
7+
blacklist {
8+
devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
9+
devnode "^hd[a-z]"
10+
}
11+
12+
devices {
13+
device {
14+
vendor "DataCore"
15+
product "Virtual Disk"
16+
path_checker tur
17+
prio alua
18+
failback 10
19+
no_path_retry fail
20+
dev_loss_tmo 60
21+
fast_io_fail_tmo 5
22+
rr_min_io_rq 100
23+
path_grouping_policy group_by_prio
24+
}
25+
}

‎SANsymphony/Proxmox Storage Plugin/SANsymphony-plugin_1.0.0_amd64/etc/udev/rules.d/99-datacore.rules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
SUBSYSTEM=="block", ACTION=="add", ATTRS{vendor}=="DataCore", ATTRS{model}=="Virtual Disk ",RUN+="/bin/sh -c 'echo 80 > /sys/block/%k/device/timeout'"

0 commit comments

Comments
 (0)