feat: Add Kubernetes module to SAL
- 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)
This commit is contained in:
Mahmoud-Emad
218
kubernetes/README.md
Normal file
218
kubernetes/README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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
|
||||
|
||||
```rust
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```rust
|
||||
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
|
||||
|
||||
```rust
|
||||
// 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user