sal/kubernetes/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 library
• k8s-openapi: Kubernetes API types
• tokio: Async runtime
• regex: Pattern matching for resource deletion
• rhai: 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 or KUBECONFIG 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 namespace
• services_list() - List all services in the namespace
• deployments_list() - List all deployments in the namespace
• configmaps_list() - List all configmaps in the namespace
• secrets_list() - List all secrets in the namespace

Resource Management

• pod_get(name) - Get a specific pod by name
• service_get(name) - Get a specific service by name
• deployment_get(name) - Get a specific deployment by name
• pod_delete(name) - Delete a specific pod by name
• service_delete(name) - Delete a specific service by name
• deployment_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 exists
• namespaces_list() - List all namespaces (cluster-wide)

Utility Functions

• resource_counts() - Get counts of all resource types in the namespace
• namespace() - 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 KubernetesManager
• pods_list(km) - List pods
• services_list(km) - List services
• deployments_list(km) - List deployments
• namespaces_list(km) - List all namespaces
• delete(km, pattern) - Delete resources matching pattern
• namespace_create(km, name) - Create namespace
• namespace_exists(km, name) - Check namespace existence
• resource_counts(km) - Get resource counts
• pod_delete(km, name) - Delete specific pod
• service_delete(km, name) - Delete specific service
• deployment_delete(km, name) - Delete specific deployment
• namespace(km) - Get manager's namespace

Examples

The examples/kubernetes/ directory contains comprehensive examples:

• basic_operations.rhai - Basic listing and counting operations
• namespace_management.rhai - Creating and managing namespaces
• pattern_deletion.rhai - Using PCRE patterns for bulk deletion
• multi_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