Crate ansible

Expand description

§Ansible-rs

A modern, type-safe Rust wrapper library for Ansible command-line tools.

This library provides a safe, ergonomic interface for executing Ansible commands, playbooks, and managing Ansible configurations from Rust applications. It supports all major Ansible tools including ansible, ansible-playbook, ansible-vault, ansible-config, and ansible-inventory.

§Features

🔒 Type-safe - Leverages Rust’s type system to prevent common configuration errors
🚀 Modern API - Uses builder patterns and fluent interfaces for ergonomic usage
🛡️ Comprehensive error handling - Detailed error types for different failure modes
⚡ Memory efficient - Optimized for minimal allocations and clones
🔧 Smart build system - Automatic Ansible detection and installation during build
🌍 Cross-platform - Supports Linux, macOS, and BSD systems
📚 Rust 2024 edition - Uses the latest Rust features and idioms
🧪 100% test coverage - Comprehensive test suite with property-based testing

§System Requirements

Supported platforms: Linux, macOS, FreeBSD, OpenBSD, NetBSD
Ansible: Version 2.9 or higher (automatically detected and installed)
Python: Version 3.6 or higher (required by Ansible)

The build script will automatically detect and attempt to install Ansible if not present. See the installation guide for manual installation.

§Quick Start

§Basic Ansible Commands

use ansible::{Ansible, Module};

let mut ansible = Ansible::default();
ansible
    .set_system_envs()
    .filter_envs(["HOME", "PATH"])
    .add_host("all")
    .set_inventory("./hosts");

// Execute a ping
let result = ansible.ping()?;
println!("Ping result: {}", result);

// Execute a shell command
let result = ansible.shell("uptime")?;
println!("Uptime: {}", result);

§Playbook Execution

use ansible::{Playbook, Play};

let mut playbook = Playbook::default();
playbook.set_inventory("./hosts");

// Run from file
let result = playbook.run(Play::from_file("site.yml"))?;
println!("Playbook result: {}", result);

// Run from string content
let yaml_content = r#"
---
- hosts: all
  tasks:
    - name: Ensure nginx is installed
      package:
        name: nginx
        state: present
"#;
let result = playbook.run(Play::from_content(yaml_content))?;

§Ansible Vault Operations

Manage encrypted files and strings with Ansible Vault:

use ansible::AnsibleVault;

let mut vault = AnsibleVault::new();
vault.set_vault_password_file("vault_pass.txt");

// Encrypt a file
vault.encrypt("secrets.yml")?;

// Decrypt a file
vault.decrypt("secrets.yml")?;

// Encrypt a string
let encrypted = vault.encrypt_string("my_secret_password")?;
println!("Encrypted: {}", encrypted);

§Configuration Management

Query and manage Ansible configuration:

use ansible::{AnsibleConfig, ConfigFormat, PluginType};

let mut config = AnsibleConfig::new();

// List all configuration options
let config_list = config.list()?;
println!("Configuration: {}", config_list);

// Dump configuration in JSON format
config.set_format(ConfigFormat::Json);
let config_dump = config.dump()?;
println!("Config dump: {}", config_dump);

// List specific plugin types
config.set_plugin_type(PluginType::Callback);
let callbacks = config.list()?;

§Inventory Management

Parse and query Ansible inventories:

use ansible::{AnsibleInventory, InventoryFormat};

let mut inventory = AnsibleInventory::new();
inventory
    .set_inventory("hosts.yml")
    .set_format(InventoryFormat::Json);

// List all hosts
let hosts = inventory.list()?;
println!("Hosts: {}", hosts);

// Get specific host information
let host_info = inventory.host("web01")?;
println!("Host info: {}", host_info);

// Parse inventory data
let inventory_data = inventory.parse_inventory_data()?;
for (group_name, group) in &inventory_data.groups {
    println!("Group {}: {} hosts", group_name, group.hosts.len());
}

§System Requirements Validation

Check system compatibility and Ansible installation:

use ansible::{validate_system, get_system_info, PlatformValidator};

// Quick validation
validate_system()?;

// Detailed system information
let system_info = get_system_info()?;
println!("{}", system_info);

if system_info.is_fully_supported() {
    println!("All Ansible features are available!");
} else {
    println!("Missing features: {:?}", system_info.missing_features());
}

// Check individual components
if PlatformValidator::is_platform_supported() {
    println!("Platform is supported");
}

§Error Handling

The library provides comprehensive error handling with detailed error types:

use ansible::{Ansible, AnsibleError};

let result = Ansible::default().ping();
match result {
    Ok(output) => println!("Success: {}", output),
    Err(AnsibleError::CommandFailed { message, exit_code, stdout, stderr }) => {
        eprintln!("Command failed: {}", message);
        if let Some(code) = exit_code {
            eprintln!("Exit code: {}", code);
        }
        if let Some(stderr) = stderr {
            eprintln!("Error: {}", stderr);
        }
    }
    Err(AnsibleError::UnsupportedPlatform(msg)) => {
        eprintln!("Platform not supported: {}", msg);
    }
    Err(e) => eprintln!("Other error: {}", e),
}

§Environment Variables

Control build-time behavior with environment variables:

SKIP_ANSIBLE_CHECK=1 - Skip Ansible installation check during build
ANSIBLE_AUTO_INSTALL=true - Enable automatic Ansible installation
CI=1 - Disable interactive installation prompts in CI environments
DOCS_RS=1 - Skip all checks when building documentation

§Module Organization

The library is organized into several modules:

Core Ansible command execution and module management
Ansible playbook execution and management
vault - Ansible Vault encryption and decryption operations
config - Ansible configuration querying and management
inventory - Inventory parsing and host management
platform - System requirements validation and platform detection
errors - Comprehensive error types and handling
command_config - Low-level command configuration utilities

§Examples

See the examples/ directory for complete working examples:

examples/basic.rs - Basic Ansible commands
examples/playbook.rs - Playbook execution
examples/new_features_demo.rs - Vault, config, and inventory features
examples/system_check.rs - System requirements validation
examples/test_build.rs - Build script functionality testing

Re-exports§

pub use errors::AnsibleError;
pub use errors::Result;
pub use vault::AnsibleVault;
pub use vault::VaultError;
pub use config::AnsibleConfig;
pub use config::ConfigFormat;
pub use config::PluginType;
pub use inventory::AnsibleInventory;
pub use inventory::InventoryFormat;
pub use inventory::InventoryData;
pub use inventory::InventoryGroup;
pub use inventory::InventoryMeta;
pub use platform::PlatformValidator;
pub use platform::SystemInfo;
pub use platform::validate_system;
pub use platform::get_system_info;

Modules§

command_config: Low-level command configuration utilities.
config: Ansible configuration querying and management.
errors: Comprehensive error handling for Ansible operations.
inventory: Ansible inventory parsing and host management.
platform: Platform compatibility and system requirements validation.
vault: Ansible Vault encryption and decryption operations.

Structs§

Ansible: Main Ansible command builder and executor.
Playbook: Ansible playbook executor with comprehensive configuration options.

Enums§

FileState: File states for file management modules.
GroupState: Group states for group management modules.
Module: Type-safe representation of Ansible modules with their arguments.
PackageState: Package states for package management modules.
Play: Represents different sources of playbook content.
ServiceState: Service states for service management modules.
UserState: User states for user management modules.

Crate ansibleCopy item path