Vim_rs: A VMware vSphere API Client for Rust

announcements
1

I'm excited to announce the release of vim_rs 0.2.0, a modern, asynchronous Rust interface to the VMware vSphere Virtual Infrastructure JSON API. This library enables Rust developers to programmatically manage VMware infrastructure with type safety and high performance.

Features

  • Fully Asynchronous: Built on tokio runtime for efficient non-blocking operations
  • Type-Safe: Comprehensive Rust types for the vSphere API objects
  • Macro System: Two powerful macros for simplified property access:
    • vim_retrievable: For one-time property retrieval with strong typing
    • vim_updatable: For continuous property monitoring with change notifications
  • Hybrid Type System: Intelligently combines traits and enums to balance type safety with performance
  • Documented: Original VMware documentation included as rustdoc

Examples

Connect to a vCenter server:

let client = ClientBuilder::new("https://vcenter.example.com")
    .basic_authn("administrator@vsphere.local", "password")
    .app_details(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"))
    .insecure(true) // For self-signed certs
    .build()
    .await?;

Define a struct to retrieve host information with one API call:

vim_retrievable!(
    struct HostInfo: HostSystem {
        name = "name",
        power_state = "runtime.power_state",
        connected = "runtime.connection_state",
        cpu_usage = "summary.quick_stats.overall_cpu_usage",
        memory_usage = "summary.quick_stats.overall_memory_usage",
    }
);

async fn get_hosts(client: &Client) -> Result<()> {
    let retriever = ObjectRetriever::new(client.clone())?;
    let hosts: Vec<HostInfo> = retriever
        .retrieve_objects_from_container(&client.service_content().root_folder)
        .await?;

    for host in hosts {
        println!("Host {} is {:?}", host.name, host.power_state);
    }
    Ok(())
}

Stay continuously up to date with inventory changes:

vim_updatable!(
    struct VmDetails: VirtualMachine {
        name = "name",
        power_state = "runtime.power_state",
    }
);

....
    let cache = ObjectCache::new_with_listener(Box::new(ChangeListener {}));
    let mut manager = CacheManager::new(client.clone())?;
    let mut monitor = manager.create_monitor()?;

    manager
        .add_container_cache(Box::new(cache), &client.service_content().root_folder)
        .await?;

    loop {
        let updates = monitor.wait_updates(10).await?;
        if let Some(updates) = updates {
            manager.apply_updates(updates)?;
        } 
    }

When to Use

This library is particularly useful if you:

  • Need to automate VMware infrastructure management
  • Want strong type safety and Rust's performance benefits
  • Require asynchronous operations for scalable applications
  • Need to efficiently monitor changes in your vSphere environment

Links

This is version 0.2.0, and I welcome feedback and contributions to improve the library.

2

tbh i would have picked a different name, since when i hear vim I think of the vim text editor, which comes installed by default on linux and macos, and is apparently used by around 30% of rust programmers.

11 Likes
3

Thanks for the feedback. I considered this. The API is labeled Virtual Infrastructure Management (VIM or VI) too. I thought these are different contexts. I hope it is not offending to the community.

4

i think most people won't be too confused when they read the crate description on crates.io, but if they don't happen to see that they may be confused since if you were building a vim text editor rust library, vim_rs is one of the few names you'd expect it to have.

1 Like
5

Yes, I think it is worth changing. I almost didn't read this thread because I assumed it was about a vim (the editor) crate.

6

I want to share the release of version 0.2.1. The main focus of this release is vTUI a lightweight console UI that allows one to check on their virtual infrastructure in a pinch.

vtui-0.1.0

vTUI is built with Ratatui and crossterm.

vTUI now supports:

  1. Search using "/"
  2. Cluster, Host, VM, Network and Datastore views
  3. Navigation to related objects e.g. VMs running on specific host
  4. Exit from application using 'Ctrl-C' from any state
  5. Display of basic vCenter data
  6. Live updates of the inventory

Precompiled binaries of vTUI can be found in the github release page Release Support loading list of objects, array length property and much improved vTUI · noclue/vim_rs · GitHub

To support vTUI minor improvements are made to the vim_rs and vim_macros libraries to support retrieval and monitoring of lists of objects i.e. ListView as well as support the special length property on arrays.