xoadmin 1.2.4

bindings and wrappers to manage an XOA instance

xoadmin

xoadmin is an asynchronous Python client for interacting with Xen Orchestra's REST API and WebSocket. It enables the management of VMs, users, storage, and more, through Xen Orchestra.

• Authenticate via WebSocket.
• Perform operations on VMs.
• Manage users, including creating and deleting users.
• Handle storage operations like listing storage repositories (SRs) and managing Virtual Disk Images (VDIs).

Installation

To use the XO Admin Library, ensure you have Python 3.9+ installed.

1. From Source: Clone and install the package from source

git clone https://github.com/elnissi-io/xoadmin.git
pip install .

2. From pip: Simple pip install

pip install xoadmin

Quick Start

1. Initialize the XOAManager with the base URL of your Xen Orchestra instance:

from xoadmin.api.manager import XOAManager

manager = XOAManager(host="your-xo-instance-host", verify_ssl=False)

2. Authenticate using your Xen Orchestra credentials:

await manager.authenticate(username="your-username", password="your-password")

3. Now, you can perform various operations through the manager:

vms = await manager.list_all_vms()
print(vms)

Ensure you run your script in an environment that supports asynchronous execution, like:

import asyncio

asyncio.run(main())

Documentation

Currently a work in progress.

For more detailed information on available methods and their usage, refer to the source code in the src/xoadmin directory. Each module (vm.py, user.py, storage.py) contains classes with methods corresponding to the Xen Orchestra functionalities they manage.

Command Line Interface (CLI)

Usage: xoadmin [OPTIONS] COMMAND [ARGS]...

  XOA Admin CLI tool for managing Xen Orchestra instances.

Options:
  --help  Show this message and exit.

Commands:
  apply    Apply configuration to Xen Orchestra instances.
  auth     Authentication management commands.
  config   Configuration management commands.
  host     Manage hosts.
  storage  Storage management commands.
  user     Manage users.
  vm       VM management commands.

The XO Admin Library provides a Command Line Interface (CLI) to simplify interaction with Xen Orchestra. Here's how you can use it:

1. Installation: Install either from source or using pip:

2. Authentication: Initialize the XOAManager with the base URL of your Xen Orchestra instance and authenticate using your credentials:

   In a container environment for instance:

   xoadmin config generate
   

   This will display a copyable config file you could manually create in ~/.xoadmin/config.

   Alternatively, you could tell it to write it to a file using --output <filepath>

   xoadmin config generate --output ~/.xoadmin/config
   

   xoadmin config generate will tell you which environment variables were not defined, you could then manually define the values needed under the config file

   ➜ xoadmin git:(main) ✗ xoadmin config generate -o test.yml
   XOA configuration generated and saved to test.yml.
   # No environment variables were found.
   # Environment variables not defined (using defaults):
   # - XOA_HOST
   # - XOA_REST_API
   # - XOA_WEBSOCKET
   # - XOA_USERNAME
   # - XOA_PASSWORD
   # - XOA_VERIFY_SSL
   

3. Performing Operations: You can now perform various operations using the CLI.

   The cli utilizes a config file under ~/.xoadmin/config

   xoa:
     host: localhost
     ws_url: ws://localhost
     rest_api: http://localhost:80
     verify_ssl: false
     password: admin
     username: [e-mail]
   

   List vms

   xoadmin vm list
   

   List users

   xoadmin user list
   

   List hosts

   xoadmin host list
   

Applying a Configuration

xoadmin allows you to quickly add hosts and users to an XOA instance using a YAML file:

1. Create a YAML file with your desired configuration settings. For example:

   hypervisors:
     - host: 192.168.0.1
       username: root
       password: password
       allowUnauthorized: true
   
   users:
     - username: user
       password: password
       permission: admin
   

2. Apply the configuration using the apply command:

   xoadmin apply -f config.yaml
   

Module Usage

You can also integrate the XO Admin Library directly into your Python scripts for more customized usage. Here's an example of how you can do this:

import asyncio
from xoadmin.api.manager import XOAManager

async def main():
    # Initialize XOAManager
    manager = XOAManager(
        host="localhost",
        rest_api="http://localhost:80",
        websocket="ws://localhost",
        verify_ssl=False
    )
    
    # Authenticate
    await manager.authenticate(username="[e-mail]", password="admin")

    # Perform operations
    vms = await manager.list_all_vms()
    print(vms)

    # Close session
    await manager.close()

import asyncio
from xoadmin.api.api import XOAPI

async def main():
    api = XOAPI(
                rest_base_url="http://localhost:80", # without /rest
                ws_url="ws://localhost",
                verify_ssl=True,
            )

    await api.authenticate_with_websocket(
        "[e-mail]",
        "admin",
    )

Contributing and License

Contributions to the XO Admin Library are welcome! Please feel free to submit pull requests or open issues to discuss new features or improvements. This project is licensed under the Apache 2.0 License. For more details, refer to the LICENSE file.