From bf65b89ff87a4e4edf6130c10ca3f4a044b61201 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Thu, 8 Aug 2024 13:46:03 +0200 Subject: [PATCH 1/2] Fix docs layout --- CHANGELOG.md | 4 ++-- docs/conf.py | 2 -- docs/index.rst | 1 - docs/topics/index.rst | 7 ------- 4 files changed, 2 insertions(+), 12 deletions(-) delete mode 100644 docs/topics/index.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index e359b1e..eb0e4b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH # Changelog -# Saltext.Proxmox 1.1.0 (2023-10-11) +## v1.1.0 (2023-10-11) ### Removed @@ -21,7 +21,7 @@ This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH - fixed location parameter for `avail_images()` (#25) -# Saltext.Proxmox 1.0.0 (2023-04-26) +## v1.0.0 (2023-04-26) ### Added diff --git a/docs/conf.py b/docs/conf.py index c2b4f97..f7ec288 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -126,8 +126,6 @@ autosummary_generate = False -suppress_warnings = ["myst.header"] - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/index.rst b/docs/index.rst index a6d1947..767f120 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,6 @@ Salt Extension for interacting with Proxmox PVE :hidden: topics/installation - topics/index .. toctree:: :maxdepth: 2 diff --git a/docs/topics/index.rst b/docs/topics/index.rst deleted file mode 100644 index e4276a6..0000000 --- a/docs/topics/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -====== -Topics -====== - -.. toctree:: - :maxdepth: 1 - :glob: From f4dc4c118ae369fd714a32b6a058c369c26528b6 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Thu, 8 Aug 2024 15:20:33 +0200 Subject: [PATCH 2/2] Create separate configuration guide --- docs/index.rst | 1 + docs/topics/configuration.md | 98 ++++++++++++++++++++++ src/saltext/proxmox/clouds/proxmox.py | 114 ++------------------------ 3 files changed, 104 insertions(+), 109 deletions(-) create mode 100644 docs/topics/configuration.md diff --git a/docs/index.rst b/docs/index.rst index 767f120..b3efdfa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,7 @@ Salt Extension for interacting with Proxmox PVE :hidden: topics/installation + topics/configuration .. toctree:: :maxdepth: 2 diff --git a/docs/topics/configuration.md b/docs/topics/configuration.md new file mode 100644 index 0000000..b24a181 --- /dev/null +++ b/docs/topics/configuration.md @@ -0,0 +1,98 @@ +# Configuration + +## Provider +Set up the cloud configuration at `/etc/salt/cloud.providers` or `/etc/salt/cloud.providers.d/proxmox.conf`: + +```yaml +my-proxmox-config: + # Required parameters + user: myuser@pam # or myuser@pve + token: myapitoken + url: https://hypervisor.domain.tld:8006 + driver: proxmox +``` + +## Profile examples +### Create a new LXC container +```yaml +my-lxc-container: + provider: my-proxmox-config + technology: lxc + + # Required for cloud.bootstrap() + ssh_host: 192.168.101.2 + ssh_username: root + ssh_password: supersecret + + create: + # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/lxc + vmid: 123 + ostemplate: local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst + node: proxmox-node1 + + hostname: my-lxc-container + net0: name=eth0,bridge=vmbr0,firewall=1,gw=192.168.101.1,ip=192.168.101.2/24,tag=101,type=veth + password: supersecret +``` + +### Clone an existing LXC container +```yaml +my-lxc-container: + provider: my-proxmox-config + technology: lxc + + # Required for cloud.bootstrap() + ssh_host: 192.168.101.2 + ssh_username: root + ssh_password: supersecret + + clone: + # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/lxc/clone + vmid: 123 + newid: 456 + node: proxmox-node1 + + hostname: my-lxc-container + description: cloned vm +``` + +### Create a new QEMU VM +```yaml +my-qemu-vm: + provider: my-proxmox-config + technology: qemu + + # Required for cloud.bootstrap() + ssh_host: 192.168.101.2 + ssh_username: root + ssh_password: supersecret + + create: + # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/qemu + vmid: 123 + node: proxmox-node1 + + name: my-qemu-vm + ipconfig0: ip=192.168.101.2/24,gw=192.168.101.1 +``` + +### Clone an existing QEMU VM +```yaml +my-qemu-vm: + provider: my-proxmox-config + technology: qemu + + # Required for cloud.bootstrap() + ssh_host: 192.168.101.2 + ssh_username: root + ssh_password: supersecret + + clone: + # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/qemu/clone + vmid: 123 + newid: 456 + node: proxmox-node1 + + name: my-qemu-vm + description: cloned vm +``` diff --git a/src/saltext/proxmox/clouds/proxmox.py b/src/saltext/proxmox/clouds/proxmox.py index 9b30554..b22e500 100644 --- a/src/saltext/proxmox/clouds/proxmox.py +++ b/src/saltext/proxmox/clouds/proxmox.py @@ -1,116 +1,12 @@ """ Proxmox Cloud Module -====================== +==================== -The Proxmox cloud module is used to control access to Proxmox +The Proxmox cloud module is used to control access to Proxmox. -Set up the cloud configuration at ``/etc/salt/cloud.providers`` or - ``/etc/salt/cloud.providers.d/proxmox.conf``: - -.. code-block:: yaml - - my-proxmox-config: - # Required parameters - user: myuser@pam # or myuser@pve - token: myapitoken - url: https://hypervisor.domain.tld:8006 - driver: proxmox - -This cloud module is a wrapper for the Proxmox API. As such, all supported parameters for VM operations (create, clone, start, ...) by the Proxmox API are also supported through this cloud module. - -Profile configuration examples: - -Create a new LXC container --------------------------- - -.. code-block:: yaml - - my-lxc-container: - provider: my-proxmox-config - technology: lxc - - # Required for cloud.bootstrap() - ssh_host: 192.168.101.2 - ssh_username: root - ssh_password: supersecret - - create: - # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/lxc - vmid: 123 - ostemplate: local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst - node: proxmox-node1 - - hostname: my-lxc-container - net0: name=eth0,bridge=vmbr0,firewall=1,gw=192.168.101.1,ip=192.168.101.2/24,tag=101,type=veth - password: supersecret - -Clone an existing LXC container -------------------------------- - -.. code-block:: yaml - - my-lxc-container: - provider: my-proxmox-config - technology: lxc - - # Required for cloud.bootstrap() - ssh_host: 192.168.101.2 - ssh_username: root - ssh_password: supersecret - - clone: - # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/lxc/clone - vmid: 123 - newid: 456 - node: proxmox-node1 - - hostname: my-lxc-container - description: cloned vm - -Create a new QEMU VM --------------------- - -.. code-block:: yaml - - my-qemu-vm: - provider: my-proxmox-config - technology: qemu - - # Required for cloud.bootstrap() - ssh_host: 192.168.101.2 - ssh_username: root - ssh_password: supersecret - - create: - # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/qemu - vmid: 123 - node: proxmox-node1 - - name: my-qemu-vm - ipconfig0: ip=192.168.101.2/24,gw=192.168.101.1 - -Clone an existing QEMU VM -------------------------- - -.. code-block:: yaml - - my-qemu-vm: - provider: my-proxmox-config - technology: qemu - - # Required for cloud.bootstrap() - ssh_host: 192.168.101.2 - ssh_username: root - ssh_password: supersecret - - clone: - # For parameters check https:///pve-docs/api-viewer/index.html#/nodes/{node}/qemu/clone - vmid: 123 - newid: 456 - node: proxmox-node1 - - name: my-qemu-vm - description: cloned vm +This cloud module is a wrapper for the Proxmox API. As such, all supported parameters +for VM operations (create, clone, start, ...) by the Proxmox API are also +supported through this cloud module. :maintainer: EITR Technologies, LLC :depends: requests >= 2.2.1