455f84528b
Some checks are pending
Rhai Tests / Run Rhai Tests (push) Waiting to run
- Add sal-virt package to the workspace members - Update MONOREPO_CONVERSION_PLAN.md to reflect the completion of sal-process and sal-virt packages - Update src/lib.rs to include sal-virt - Update src/postgresclient to use sal-virt instead of local virt module - Update tests to use sal-virt
168 lines
4.4 KiB
Markdown
168 lines
4.4 KiB
Markdown
# SAL Virt Package
|
|
|
|
The `sal-virt` package provides comprehensive virtualization and containerization tools for building, managing, and deploying containers and filesystem layers.
|
|
|
|
## Features
|
|
|
|
- **Buildah**: OCI/Docker image building with builder pattern API
|
|
- **Nerdctl**: Container lifecycle management with containerd
|
|
- **RFS**: Remote filesystem mounting and layer management
|
|
- **Cross-Platform**: Works across Windows, macOS, and Linux
|
|
- **Rhai Integration**: Full support for Rhai scripting language
|
|
- **Error Handling**: Comprehensive error types and handling
|
|
|
|
## Modules
|
|
|
|
### Buildah
|
|
Container image building with Buildah, providing:
|
|
- Builder pattern for container configuration
|
|
- Image management and operations
|
|
- Content operations (copy, add, run commands)
|
|
- Debug mode support
|
|
|
|
### Nerdctl
|
|
Container management with Nerdctl, providing:
|
|
- Container lifecycle management (create, start, stop, remove)
|
|
- Image operations (pull, push, build, tag)
|
|
- Network and volume management
|
|
- Health checks and resource limits
|
|
- Builder pattern for container configuration
|
|
|
|
### RFS
|
|
Remote filesystem operations, providing:
|
|
- Mount/unmount operations for various filesystem types
|
|
- Pack/unpack operations for filesystem layers
|
|
- Support for Local, SSH, S3, WebDAV, and custom filesystems
|
|
- Store specifications for different backends
|
|
|
|
## Usage
|
|
|
|
### Basic Buildah Example
|
|
|
|
```rust
|
|
use sal_virt::buildah::Builder;
|
|
|
|
// Create a new builder
|
|
let mut builder = Builder::new("my-container", "alpine:latest")?;
|
|
|
|
// Configure the builder
|
|
builder.set_debug(true);
|
|
|
|
// Add content and run commands
|
|
builder.copy("./app", "/usr/local/bin/app")?;
|
|
builder.run(&["chmod", "+x", "/usr/local/bin/app"])?;
|
|
|
|
// Commit the image
|
|
let image_id = builder.commit("my-app:latest")?;
|
|
```
|
|
|
|
### Basic Nerdctl Example
|
|
|
|
```rust
|
|
use sal_virt::nerdctl::Container;
|
|
|
|
// Create a container from an image
|
|
let container = Container::from_image("web-app", "nginx:alpine")?
|
|
.with_port("8080:80")
|
|
.with_volume("/host/data:/app/data")
|
|
.with_env("ENV_VAR", "production")
|
|
.with_restart_policy("always");
|
|
|
|
// Run the container
|
|
let result = container.run()?;
|
|
```
|
|
|
|
### Basic RFS Example
|
|
|
|
```rust
|
|
use sal_virt::rfs::{RfsBuilder, MountType, StoreSpec};
|
|
|
|
// Mount a remote filesystem
|
|
let mount = RfsBuilder::new("user@host:/remote/path", "/local/mount", MountType::SSH)
|
|
.with_option("read_only", "true")
|
|
.mount()?;
|
|
|
|
// Pack a directory
|
|
let specs = vec![StoreSpec::new("file").with_option("path", "/tmp/store")];
|
|
let pack_result = pack_directory("/source/dir", "/output/pack.rfs", &specs)?;
|
|
```
|
|
|
|
## Rhai Integration
|
|
|
|
All functionality is available in Rhai scripts:
|
|
|
|
```javascript
|
|
// Buildah in Rhai
|
|
let builder = bah_new("my-container", "alpine:latest");
|
|
builder.copy("./app", "/usr/local/bin/app");
|
|
builder.run(["chmod", "+x", "/usr/local/bin/app"]);
|
|
|
|
// Nerdctl in Rhai
|
|
let container = nerdctl_container_from_image("web-app", "nginx:alpine")
|
|
.with_port("8080:80")
|
|
.with_env("ENV", "production");
|
|
container.run();
|
|
|
|
// RFS in Rhai
|
|
let mount_options = #{ "read_only": "true" };
|
|
rfs_mount("user@host:/remote", "/local/mount", "ssh", mount_options);
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- `sal-process`: For command execution
|
|
- `sal-os`: For filesystem operations
|
|
- `anyhow`: For error handling
|
|
- `serde`: For serialization
|
|
- `rhai`: For scripting integration
|
|
|
|
## Testing
|
|
|
|
The package includes comprehensive tests:
|
|
|
|
```bash
|
|
# Run all tests
|
|
cargo test
|
|
|
|
# Run specific test suites
|
|
cargo test buildah_tests
|
|
cargo test nerdctl_tests
|
|
cargo test rfs_tests
|
|
|
|
# Run Rhai integration tests
|
|
cargo test --test rhai_integration
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Each module provides its own error types:
|
|
- `BuildahError`: For Buildah operations
|
|
- `NerdctlError`: For Nerdctl operations
|
|
- `RfsError`: For RFS operations
|
|
|
|
All errors implement `std::error::Error` and provide detailed error messages.
|
|
|
|
## Platform Support
|
|
|
|
- **Linux**: Full support for all features
|
|
- **macOS**: Full support (requires Docker Desktop or similar)
|
|
- **Windows**: Full support (requires Docker Desktop or WSL2)
|
|
|
|
## Security
|
|
|
|
- Credentials are handled securely and never logged
|
|
- URLs with passwords are masked in logs
|
|
- All operations respect filesystem permissions
|
|
- Network operations use secure defaults
|
|
|
|
## Configuration
|
|
|
|
Most operations can be configured through environment variables:
|
|
- `BUILDAH_DEBUG`: Enable debug mode for Buildah
|
|
- `NERDCTL_DEBUG`: Enable debug mode for Nerdctl
|
|
- `RFS_DEBUG`: Enable debug mode for RFS
|
|
|
|
## License
|
|
|
|
Apache-2.0
|