1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
|
=========================================
Proxmoxer: A wrapper for Proxmox REST API
=========================================
master branch: |master_build_status| |master_coverage_status| |pypi_version| |pypi_downloads|
develop branch: |develop_build_status| |develop_coverage_status|
What does it do and what's different?
-------------------------------------
Proxmoxer is a wrapper around the `Proxmox REST API v2 <https://pve.proxmox.com/pve-docs/api-viewer/index.html>`_.
It was inspired by slumber, but it dedicated only to Proxmox. It allows to use not only REST API over HTTPS, but
the same api over ssh and pvesh utility.
Like `Proxmoxia <https://github.com/baseblack/Proxmoxia>`_ it dynamically creates attributes which responds to the
attributes you've attempted to reach.
Installation
------------
.. code-block:: bash
pip install proxmoxer
For 'https' backend install requests
.. code-block:: bash
pip install requests
For 'ssh_paramiko' backend install paramiko
.. code-block:: bash
pip install paramiko
Short usage information
-----------------------
The first thing to do is import the proxmoxer library and create ProxmoxAPI instance.
.. code-block:: python
from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='admin@pam',
password='secret_word', verify_ssl=False)
This will connect by default through the 'https' backend.
It is possible to use already prepared public/private key authentication. It is possible to use ssh-agent also.
.. code-block:: python
from proxmoxer import ProxmoxAPI
proxmox = ProxmoxAPI('proxmox_host', user='proxmox_admin', backend='ssh_paramiko')
**Please note, https-backend needs 'requests' library, ssh_paramiko-backend needs 'paramiko' library,
openssh-backend needs 'openssh_wrapper' library installed.**
Queries are exposed via the access methods **get**, **post**, **put** and **delete**. For convenience added two
synonyms: **create** for **post**, and **set** for **put**.
.. code-block:: python
for node in proxmox.nodes.get():
for vm in proxmox.nodes(node['node']).openvz.get():
print "{0}. {1} => {2}" .format(vm['vmid'], vm['name'], vm['status'])
>>> 141. puppet-2.london.baseblack.com => running
101. munki.london.baseblack.com => running
102. redmine.london.baseblack.com => running
140. dns-1.london.baseblack.com => running
126. ns-3.london.baseblack.com => running
113. rabbitmq.london.baseblack.com => running
same code can be rewritten in the next way:
.. code-block:: python
for node in proxmox.get('nodes'):
for vm in proxmox.get('nodes/%s/openvz' % node['node']):
print "%s. %s => %s" % (vm['vmid'], vm['name'], vm['status'])
for example next lines do the same job:
.. code-block:: python
proxmox.nodes(node['node']).openvz.get()
proxmox.nodes(node['node']).get('openvz')
proxmox.get('nodes/%s/openvz' % node['node'])
proxmox.get('nodes', node['node'], 'openvz')
Some more examples:
.. code-block:: python
for vm in proxmox.cluster.resources.get(type='vm'):
print("{0}. {1} => {2}" .format(vm['vmid'], vm['name'], vm['status']))
.. code-block:: python
node = proxmox.nodes('proxmox_node')
pprint(node.storage('local').content.get())
or the with same results
.. code-block:: python
node = proxmox.nodes.proxmox_node()
pprint(node.storage.local.content.get())
Example of creation of lxc container:
.. code-block:: python
node = proxmox.nodes('proxmox_node')
node.lxc.create(vmid=202,
ostemplate='local:vztmpl/debian-9.0-standard_20170530_amd64.tar.gz',
hostname='debian-stretch',
storage='local',
memory=512,
swap=512,
cores=1,
password='secret',
net0='name=eth0,bridge=vmbr0,ip=192.168.22.1/20,gw=192.168.16.1')
Example of creating the same lxc container with parameters in a dictonary.
This approach allows to add ``ssh-public-keys`` without getting syntax errors.
.. code-block:: python
newcontainer = { 'vmid': 202,
'ostemplate': 'local:vztmpl/debian-9.0-standard_20170530_amd64.tar.gz',
'hostname': 'debian-stretch',
'storage': 'local',
'memory': 512,
'swap': 512,
'cores': 1,
'password': 'secret',
'net0': 'name=eth0,bridge=vmbr0,ip=192.168.22.1/20,gw=192.168.16.1' }
node = proxmox.nodes('proxmox_node')
node.lxc.create(**newcontainer)
Example of template upload:
.. code-block:: python
local_storage = proxmox.nodes('proxmox_node').storage('local')
local_storage.upload.create(content='vztmpl',
filename=open(os.path.expanduser('~/templates/debian-6-my-core_1.0-1_i386.tar.gz'))))
Example of rrd download:
.. code-block:: python
response = proxmox.nodes('proxmox').rrd.get(ds='cpu', timeframe='hour')
with open('cpu.png', 'wb') as f:
f.write(response['image'].encode('raw_unicode_escape'))
Example of usage of logging:
.. code-block:: python
# now logging debug info will be written to stdout
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s:%(name)s: %(message)s')
Roadmap
-------
* write tests
* support other actual python versions
* add optional validation of requests
* add some shortcuts for convenience
History
-------
1.0.3 (1018-09-10)
..................
* Improvement: Added option to specify port in hostname parameter (`pvanagtmaal <https://github.com/pvanagtmaal>`_)
* Improvement: Added stderr to the Response content (`Jérôme Schneider <https://github.com/merinos>`_)
* Bugfix: Paramiko python3: stdout and stderr must be a str not bytes (`Jérôme Schneider <https://github.com/merinos>`_)
* New lxc example in docu (`Geert Stappers <https://github.com/stappersg>`_)
1.0.2 (2017-12-02)
..................
* Tarball repackaged with tests
1.0.1 (2017-12-02)
..................
* LICENSE file now included in tarball
* Added verify_ssl parameter to ProxmoxHTTPAuth (`Walter Doekes <https://github.com/wdoekes>`_)
1.0.0 (2017-11-12)
..................
* Update Proxmoxer readme (`Emmanuel Kasper <https://github.com/EmmanuelKasper>`_)
* Display the reason of API calls errors (`Emmanuel Kasper <https://github.com/EmmanuelKasper>`_, `kantsdog <https://github.com/kantsdog>`_)
* Filter for ssh response code (`Chris Plock <https://github.com/chrisplo>`_)
0.2.5 (2017-02-12)
..................
* Adding sudo to execute CLI with paramiko ssh backend (`Jason Meridth <https://github.com/jmeridth>`_)
* Proxmoxer/backends/ssh_paramiko: improve file upload (`Jérôme Schneider <https://github.com/merinos>`_)
0.2.4 (2016-05-02)
..................
* Removed newline in tmp_filename string (`Jérôme Schneider <https://github.com/merinos>`_)
* Fix to avoid module reloading (`jklang <https://github.com/jklang>`_)
0.2.3 (2016-01-20)
..................
* Minor typo fix (`Srinivas Sakhamuri <https://github.com/srsakhamuri>`_)
0.2.2 (2016-01-19)
..................
* Adding sudo to execute pvesh CLI in openssh backend (`Wei Tie <https://github.com/TieWei>`_, `Srinivas Sakhamuri <https://github.com/srsakhamuri>`_)
* Add support to specify an identity file for ssh connections (`Srinivas Sakhamuri <https://github.com/srsakhamuri>`_)
0.2.1 (2015-05-02)
..................
* fix for python 3.4 (`kokuev <https://github.com/kokuev>`_)
0.2.0 (2015-03-21)
..................
* Https will now raise AuthenticationError when appropriate. (`scap1784 <https://github.com/scap1784>`_)
* Preliminary python 3 compatibility. (`wdoekes <https://github.com/wdoekes>`_)
* Additional example. (`wdoekes <https://github.com/wdoekes>`_)
0.1.7 (2014-11-16)
..................
* Added ignore of "InsecureRequestWarning: Unverified HTTPS request is being made..." warning while using https (requests) backend.
0.1.4 (2013-06-01)
..................
* Added logging
* Added openssh backend
* Tests are reorganized
0.1.3 (2013-05-30)
..................
* Added next tests
* Bugfixes
0.1.2 (2013-05-27)
..................
* Added first tests
* Added support for travis and coveralls
* Bugfixes
0.1.1 (2013-05-13)
..................
* Initial try.
.. |master_build_status| image:: https://travis-ci.org/swayf/proxmoxer.png?branch=master
:target: https://travis-ci.org/swayf/proxmoxer
.. |master_coverage_status| image:: https://coveralls.io/repos/swayf/proxmoxer/badge.png?branch=master
:target: https://coveralls.io/r/swayf/proxmoxer
.. |develop_build_status| image:: https://travis-ci.org/swayf/proxmoxer.png?branch=develop
:target: https://travis-ci.org/swayf/proxmoxer
.. |develop_coverage_status| image:: https://coveralls.io/repos/swayf/proxmoxer/badge.png?branch=develop
:target: https://coveralls.io/r/swayf/proxmoxer
.. |pypi_version| image:: https://img.shields.io/pypi/v/proxmoxer.svg
:target: https://pypi.python.org/pypi/proxmoxer
.. |pypi_downloads| image:: https://img.shields.io/pypi/dm/proxmoxer.svg
:target: https://pypi.python.org/pypi/proxmoxer
|