- Add Kubernetes cluster management and operations - Include pod, service, and deployment management - Implement pattern-based resource deletion - Support namespace creation and management - Provide Rhai scripting wrappers for all functions - Include production safety features (timeouts, retries, rate limiting) |
||
---|---|---|
.. | ||
src | ||
tests | ||
Cargo.toml | ||
README.md |
SAL Kubernetes
Kubernetes cluster management and operations for the System Abstraction Layer (SAL).
⚠️ IMPORTANT SECURITY NOTICE
This package includes destructive operations that can permanently delete Kubernetes resources!
- The
delete(pattern)
function uses PCRE regex patterns to bulk delete resources - Always test patterns in a safe environment first
- Use specific patterns to avoid accidental deletion of critical resources
- Consider the impact on dependent resources before deletion
- No confirmation prompts - deletions are immediate and irreversible
Overview
This package provides a high-level interface for managing Kubernetes clusters using the kube-rs
SDK. It focuses on namespace-scoped operations through the KubernetesManager
factory pattern.
Production Safety Features
- Configurable Timeouts: All operations have configurable timeouts to prevent hanging
- Exponential Backoff Retry: Automatic retry logic for transient failures
- Rate Limiting: Built-in rate limiting to prevent API overload
- Comprehensive Error Handling: Detailed error types and proper error propagation
- Structured Logging: Production-ready logging for monitoring and debugging
Features
- Namespace-scoped Management: Each
KubernetesManager
instance operates on a single namespace - Pod Management: List, create, and manage pods
- Pattern-based Deletion: Delete resources using PCRE pattern matching
- Namespace Operations: Create and manage namespaces (idempotent operations)
- Resource Management: Support for pods, services, deployments, configmaps, secrets, and more
- Rhai Integration: Full scripting support through Rhai wrappers
Usage
Basic Operations
use sal_kubernetes::KubernetesManager;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a manager for the "default" namespace
let km = KubernetesManager::new("default").await?;
// List all pods in the namespace
let pods = km.pods_list().await?;
println!("Found {} pods", pods.len());
// Create a namespace (no error if it already exists)
km.namespace_create("my-namespace").await?;
// Delete resources matching a pattern
km.delete("test-.*").await?;
Ok(())
}
Rhai Scripting
// Create Kubernetes manager for namespace
let km = kubernetes_manager_new("default");
// List pods
let pods = pods_list(km);
print("Found " + pods.len() + " pods");
// Create namespace
namespace_create(km, "my-app");
// Delete test resources
delete(km, "test-.*");
Dependencies
kube
: Kubernetes client libraryk8s-openapi
: Kubernetes API typestokio
: Async runtimeregex
: Pattern matching for resource deletionrhai
: Scripting integration (optional)
Configuration
Kubernetes Authentication
The package uses the standard Kubernetes configuration methods:
- In-cluster configuration (when running in a pod)
- Kubeconfig file (
~/.kube/config
orKUBECONFIG
environment variable) - Service account tokens
Production Safety Configuration
use sal_kubernetes::{KubernetesManager, KubernetesConfig};
use std::time::Duration;
// Create with custom configuration
let config = KubernetesConfig::new()
.with_timeout(Duration::from_secs(60))
.with_retries(5, Duration::from_secs(1), Duration::from_secs(30))
.with_rate_limit(20, 50);
let km = KubernetesManager::with_config("my-namespace", config).await?;
Pre-configured Profiles
// High-throughput environment
let config = KubernetesConfig::high_throughput();
// Low-latency environment
let config = KubernetesConfig::low_latency();
// Development/testing
let config = KubernetesConfig::development();
Error Handling
All operations return Result<T, KubernetesError>
with comprehensive error types for different failure scenarios including API errors, configuration issues, and permission problems.
API Reference
KubernetesManager
The main interface for Kubernetes operations. Each instance is scoped to a single namespace.
Constructor
KubernetesManager::new(namespace)
- Create a manager for the specified namespace
Resource Listing
pods_list()
- List all pods in the namespaceservices_list()
- List all services in the namespacedeployments_list()
- List all deployments in the namespaceconfigmaps_list()
- List all configmaps in the namespacesecrets_list()
- List all secrets in the namespace
Resource Management
pod_get(name)
- Get a specific pod by nameservice_get(name)
- Get a specific service by namedeployment_get(name)
- Get a specific deployment by namepod_delete(name)
- Delete a specific pod by nameservice_delete(name)
- Delete a specific service by namedeployment_delete(name)
- Delete a specific deployment by name
Pattern-based Operations
delete(pattern)
- Delete all resources matching a PCRE pattern
Namespace Operations
namespace_create(name)
- Create a namespace (idempotent)namespace_exists(name)
- Check if a namespace existsnamespaces_list()
- List all namespaces (cluster-wide)
Utility Functions
resource_counts()
- Get counts of all resource types in the namespacenamespace()
- Get the namespace this manager operates on
Rhai Functions
When using the Rhai integration, the following functions are available:
kubernetes_manager_new(namespace)
- Create a KubernetesManagerpods_list(km)
- List podsservices_list(km)
- List servicesdeployments_list(km)
- List deploymentsnamespaces_list(km)
- List all namespacesdelete(km, pattern)
- Delete resources matching patternnamespace_create(km, name)
- Create namespacenamespace_exists(km, name)
- Check namespace existenceresource_counts(km)
- Get resource countspod_delete(km, name)
- Delete specific podservice_delete(km, name)
- Delete specific servicedeployment_delete(km, name)
- Delete specific deploymentnamespace(km)
- Get manager's namespace
Examples
The examples/kubernetes/
directory contains comprehensive examples:
basic_operations.rhai
- Basic listing and counting operationsnamespace_management.rhai
- Creating and managing namespacespattern_deletion.rhai
- Using PCRE patterns for bulk deletionmulti_namespace_operations.rhai
- Working across multiple namespaces
Testing
Run tests with:
# Unit tests (no cluster required)
cargo test --package sal-kubernetes
# Integration tests (requires cluster)
KUBERNETES_TEST_ENABLED=1 cargo test --package sal-kubernetes
# Rhai integration tests
KUBERNETES_TEST_ENABLED=1 cargo test --package sal-kubernetes --features rhai
Security Considerations
- Always use specific PCRE patterns to avoid accidental deletion of important resources
- Test deletion patterns in a safe environment first
- Ensure proper RBAC permissions are configured
- Be cautious with cluster-wide operations like namespace listing
- Consider using dry-run approaches when possible