Herosal Kubernetes (herosal-kubernetes)

Kubernetes cluster management and operations for the Herosal library.

Installation

Add this to your Cargo.toml:

[dependencies]
herosal-kubernetes = "0.1.0"

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.

Labels vs Environment Variables

Understanding the difference between labels and environment variables is crucial for effective Kubernetes deployments:

Labels (Kubernetes Metadata)

• Purpose: Organize, select, and manage Kubernetes resources
• Scope: Kubernetes cluster management and resource organization
• Visibility: Used by Kubernetes controllers, selectors, and monitoring systems
• Examples: app=my-app, tier=backend, environment=production, version=v1.2.3
• Use Cases: Resource grouping, service discovery, monitoring labels, deployment strategies

Environment Variables (Container Configuration)

• Purpose: Configure application runtime behavior and settings
• Scope: Inside container processes - available to your application code
• Visibility: Accessible via process.env, os.environ, etc. in your application
• Examples: NODE_ENV=production, DATABASE_URL=postgres://..., API_KEY=secret
• Use Cases: Database connections, API keys, feature flags, runtime configuration

Example: Complete Application Configuration

// Labels: For Kubernetes resource management
let mut labels = HashMap::new();
labels.insert("app".to_string(), "web-api".to_string());           // Service discovery
labels.insert("tier".to_string(), "backend".to_string());         // Architecture layer
labels.insert("environment".to_string(), "production".to_string()); // Deployment stage
labels.insert("version".to_string(), "v2.1.0".to_string());       // Release version

// Environment Variables: For application configuration
let mut env_vars = HashMap::new();
env_vars.insert("NODE_ENV".to_string(), "production".to_string());              // Runtime mode
env_vars.insert("DATABASE_URL".to_string(), "postgres://db:5432/app".to_string()); // DB connection
env_vars.insert("REDIS_URL".to_string(), "redis://cache:6379".to_string());     // Cache connection
env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());                   // Logging config

Usage

Application Deployment (Recommended)

Deploy complete applications with labels and environment variables:

use herosal_kubernetes::KubernetesManager;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let km = KubernetesManager::new("default").await?;

    // Configure labels for Kubernetes resource organization
    let mut labels = HashMap::new();
    labels.insert("app".to_string(), "my-app".to_string());
    labels.insert("tier".to_string(), "backend".to_string());

    // Configure environment variables for the container
    let mut env_vars = HashMap::new();
    env_vars.insert("NODE_ENV".to_string(), "production".to_string());
    env_vars.insert("DATABASE_URL".to_string(), "postgres://db:5432/myapp".to_string());
    env_vars.insert("API_KEY".to_string(), "secret-api-key".to_string());

    // Deploy application with deployment + service
    km.deploy_application(
        "my-app",           // name
        "node:18-alpine",   // image
        3,                  // replicas
        3000,               // port
        Some(labels),       // Kubernetes labels
        Some(env_vars),     // container environment variables
    ).await?;

    println!("✅ Application deployed successfully!");
    Ok(())
}

Basic Operations

use herosal_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");

// Deploy application with labels and environment variables
deploy_application(km, "my-app", "node:18-alpine", 3, 3000, #{
    "app": "my-app",
    "tier": "backend",
    "environment": "production"
}, #{
    "NODE_ENV": "production",
    "DATABASE_URL": "postgres://db:5432/myapp",
    "API_KEY": "secret-api-key"
});

print("✅ Application deployed!");

// Basic operations
let pods = pods_list(km);
print("Found " + pods.len() + " pods");

namespace_create(km, "my-namespace");
delete(km, "test-.*");

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

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

Application Deployment

• deploy_application(name, image, replicas, port, labels, env_vars) - Deploy complete application with deployment and service
• deployment_create(name, image, replicas, labels, env_vars) - Create deployment with environment variables and labels

Resource Creation

• pod_create(name, image, labels, env_vars) - Create pod with environment variables and labels
• service_create(name, selector, port, target_port) - Create service with port mapping
• configmap_create(name, data) - Create configmap with data
• secret_create(name, data, secret_type) - Create secret with data and optional type

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
• configmap_delete(name) - Delete a specific configmap by name
• secret_delete(name) - Delete a specific secret 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:

Manager Creation & Application Deployment:

• kubernetes_manager_new(namespace) - Create a KubernetesManager
• deploy_application(km, name, image, replicas, port, labels, env_vars) - Deploy application with environment variables

Resource Listing:

• pods_list(km) - List pods
• services_list(km) - List services
• deployments_list(km) - List deployments
• configmaps_list(km) - List configmaps
• secrets_list(km) - List secrets
• namespaces_list(km) - List all namespaces
• resource_counts(km) - Get resource counts

Resource Operations:

• delete(km, pattern) - Delete resources matching pattern
• pod_delete(km, name) - Delete specific pod
• service_delete(km, name) - Delete specific service
• deployment_delete(km, name) - Delete specific deployment
• configmap_delete(km, name) - Delete specific configmap
• secret_delete(km, name) - Delete specific secret

Namespace Functions:

• namespace_create(km, name) - Create namespace
• namespace_exists(km, name) - Check namespace existence
• namespace_delete(km, name) - Delete namespace
• namespace(km) - Get manager's namespace

Examples

The examples/kubernetes/clusters/ directory contains comprehensive examples:

Rust Examples

Run with: cargo run --example <name> --features kubernetes

• postgres - PostgreSQL database deployment with environment variables
• redis - Redis cache deployment with configuration
• generic - Multiple application deployments (nginx, node.js, mongodb)

Rhai Examples

Run with: ./target/debug/herodo examples/kubernetes/clusters/<script>.rhai

• postgres.rhai - PostgreSQL cluster deployment script
• redis.rhai - Redis cluster deployment script

Real-World Examples

PostgreSQL Database

let mut env_vars = HashMap::new();
env_vars.insert("POSTGRES_DB".to_string(), "myapp".to_string());
env_vars.insert("POSTGRES_USER".to_string(), "postgres".to_string());
env_vars.insert("POSTGRES_PASSWORD".to_string(), "secretpassword".to_string());

km.deploy_application("postgres", "postgres:15", 1, 5432, Some(labels), Some(env_vars)).await?;

Redis Cache

let mut env_vars = HashMap::new();
env_vars.insert("REDIS_PASSWORD".to_string(), "redispassword".to_string());
env_vars.insert("REDIS_MAXMEMORY".to_string(), "256mb".to_string());

km.deploy_application("redis", "redis:7-alpine", 3, 6379, None, Some(env_vars)).await?;

Running Tests

# Unit tests (no cluster required)
cargo test --package herosal-kubernetes

# Integration tests (requires cluster)
KUBERNETES_TEST_ENABLED=1 cargo test --package herosal-kubernetes

# Rhai integration tests
KUBERNETES_TEST_ENABLED=1 cargo test --package herosal-kubernetes --features rhai

# Run specific test suites
cargo test --package herosal-kubernetes deployment_env_vars_test
cargo test --package herosal-kubernetes edge_cases_test

# Rhai environment variables test
KUBERNETES_TEST_ENABLED=1 ./target/debug/herodo kubernetes/tests/rhai/env_vars_test.rhai

Test Requirements

• Kubernetes Cluster: Integration tests require a running Kubernetes cluster

• Environment Variable: Set KUBERNETES_TEST_ENABLED=1 to enable integration tests

• Permissions: Tests require permissions to create/delete resources in the default namespace

Example: Production-Ready Deployment

// Production labels for monitoring and management
let mut labels = HashMap::new();
labels.insert("app".to_string(), "web-api".to_string());
labels.insert("version".to_string(), "v1.2.3".to_string());
labels.insert("environment".to_string(), "production".to_string());
labels.insert("team".to_string(), "backend".to_string());

// Non-sensitive environment variables
let mut env_vars = HashMap::new();
env_vars.insert("NODE_ENV".to_string(), "production".to_string());
env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
env_vars.insert("PORT".to_string(), "3000".to_string());
// Note: Use Kubernetes secrets for DATABASE_URL, API_KEY, etc.

km.deploy_application("web-api", "myapp:v1.2.3", 3, 3000, Some(labels), Some(env_vars)).await?;