# lmrc-kubernetes

> Part of the [LMRC Stack](https://gitlab.com/lemarco/lmrc-stack) - Infrastructure-as-Code toolkit for building production-ready Rust applications

A comprehensive Rust library for managing Kubernetes resources with a focus on deployments, services, secrets, and cluster operations.

[![Crates.io](https://img.shields.io/crates/v/lmrc-kubernetes.svg)](https://crates.io/crates/lmrc-kubernetes)
[![Documentation](https://docs.rs/lmrc-kubernetes/badge.svg)](https://docs.rs/lmrc-kubernetes)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)

## Features

### Core Resources

- **Deployments**: Full lifecycle management with health probes, init containers, rolling updates, rollbacks, and scaling
- **Services**: ClusterIP, NodePort, and LoadBalancer support
- **Secrets**: Docker registry and generic secrets management
- **Namespaces**: Namespace creation and management
- **ConfigMaps**: Configuration data management with volume mounting
- **Ingress**: HTTP/HTTPS routing with TLS support and path-based routing
- **Gateway API**: Next-generation traffic management with Gateway and HTTPRoute resources
- **NetworkPolicy**: Network security and micro-segmentation with ingress/egress rules
- **Jobs**: Batch processing with parallelism, retries, and TTL
- **CronJobs**: Scheduled recurring tasks with cron syntax
- **PersistentVolumeClaims**: Persistent storage management with multiple access modes
- **HorizontalPodAutoscaler**: Auto-scaling based on CPU, memory, and custom metrics

### Advanced Features

- Health probes (liveness, readiness, startup) with HTTP, TCP, and Exec support
- Init containers for initialization tasks
- Resource limits and requests (CPU and memory)
- Volume mounts (ConfigMap, Secret, EmptyDir, HostPath, PersistentVolumeClaim)
- Image pull secrets for private registries
- Service accounts for RBAC integration
- Command and args override for containers
- Pre-deployment validation
- Deployment strategies (RollingUpdate, Recreate)
- Multi-namespace support
- Label-based resource querying

### Developer Experience

- Type-safe builder patterns throughout
- Comprehensive error types with detailed context
- Ergonomic API design
- Full async/await support with tokio
- 66 unit tests covering all functionality

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
lmrc-kubernetes = "0.1"
tokio = { version = "1", features = ["full"] }
```

## Requirements

- Rust 1.70 or later
- Kubernetes cluster access (kubeconfig or in-cluster)
- Dependencies:
  - `kube` 2.0+ for Kubernetes client
  - `k8s-openapi` 0.26+ with v1_31 API support
  - `tokio` for async runtime

## Quick Start

```rust
use lmrc_kubernetes::{Client, ClientConfig};
use lmrc_kubernetes::deployment::{DeploymentSpec, ContainerSpec};
use lmrc_kubernetes::config::DeploymentOptions;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client
    let config = ClientConfig::infer().await?;
    let client = Client::new(config, "default").await?;

    // Create a deployment
    let container = ContainerSpec::new("app", "nginx:1.21")
        .with_port(80)
        .with_env("ENV", "production");

    let deployment = DeploymentSpec::new("web-app")
        .with_replicas(3)
        .with_container(container);

    // Apply the deployment
    let options = DeploymentOptions::new().wait(true);
    client.deployments().apply(&deployment, &options).await?;

    println!("Deployment successful!");
    Ok(())
}
```

## Usage Examples

### Deployment with Resource Limits

```rust
use lmrc_kubernetes::deployment::{ContainerSpec, DeploymentSpec, ResourceRequirements};

let resources = ResourceRequirements::new()
    .cpu_request("100m")
    .cpu_limit("500m")
    .memory_request("128Mi")
    .memory_limit("512Mi");

let container = ContainerSpec::new("app", "myapp:v1.0.0")
    .with_port(8080)
    .with_resources(resources);

let deployment = DeploymentSpec::new("my-app")
    .with_replicas(5)
    .with_container(container);
```

### Health Probes

```rust
use lmrc_kubernetes::deployment::{ContainerSpec, Probe};

let liveness = Probe::http("/healthz", 8080)
    .initial_delay_seconds(30)
    .period_seconds(10);

let readiness = Probe::http("/ready", 8080)
    .initial_delay_seconds(5)
    .timeout_seconds(5);

let container = ContainerSpec::new("app", "myapp:v1.0.0")
    .with_liveness_probe(liveness)
    .with_readiness_probe(readiness);
```

### ConfigMaps and Volume Mounts

```rust
use lmrc_kubernetes::configmap::ConfigMapSpec;
use lmrc_kubernetes::deployment::{ContainerSpec, Volume};

// Create ConfigMap
let configmap = ConfigMapSpec::new("app-config")
    .with_data("config.yaml", "setting: value");
client.configmaps().apply(&configmap).await?;

// Mount in deployment
let volume = Volume::from_configmap("config-volume", "app-config");
let container = ContainerSpec::new("app", "myapp:v1.0.0")
    .with_volume_mount("config-volume", "/etc/config");
```

### Docker Registry Secrets

```rust
// Create a Docker registry secret
client.secrets()
    .apply_docker_registry_secret(
        "my-registry-secret",
        "gcr.io",
        "oauth2accesstoken",
        &access_token,
    )
    .await?;

// Use in deployment
let deployment = DeploymentSpec::new("my-app")
    .with_image_pull_secret("my-registry-secret")
    .with_container(container);
```

### Service Creation

```rust
use lmrc_kubernetes::service::{ServiceSpec, ServiceType};

let service = ServiceSpec::new("my-service")
    .with_selector("app", "my-app")
    .with_port(80, 8080)
    .with_type(ServiceType::LoadBalancer);

client.services().apply(&service).await?;
```

### Ingress with TLS

```rust
use lmrc_kubernetes::ingress::{IngressSpec, IngressRule, IngressTLS};

let rule = IngressRule::new("example.com")
    .with_path("/api", "api-service", 8080)
    .with_path("/web", "web-service", 80);

let tls = IngressTLS::new()
    .with_host("example.com")
    .with_secret_name("tls-secret");

let ingress = IngressSpec::new("my-ingress")
    .with_rule(rule)
    .with_tls(tls);

client.ingress().apply(&ingress).await?;
```

### NetworkPolicy

```rust
use lmrc_kubernetes::networkpolicy::{NetworkPolicySpec, NetworkPolicyPeer, PolicyType};

let policy = NetworkPolicySpec::new("api-network-policy")
    .with_pod_selector("app", "api")
    .with_ingress_rule(vec![
        NetworkPolicyPeer::from_pod_selector("role", "frontend")
    ], vec![8080])
    .with_policy_type(PolicyType::Ingress);

client.network_policies().apply(&policy).await?;
```

### Jobs

```rust
use lmrc_kubernetes::job::JobSpec;

let job = JobSpec::new("data-migration")
    .with_container("migrate", "migration:v1.0.0")
    .with_parallelism(5)
    .with_completions(10)
    .with_backoff_limit(3);

client.jobs().apply(&job).await?;
```

### CronJobs

```rust
use lmrc_kubernetes::cronjob::CronJobSpec;

let cronjob = CronJobSpec::new("backup", "0 2 * * *")
    .with_container("backup", "backup:latest")
    .with_restart_policy("OnFailure");

client.cronjobs().apply(&cronjob).await?;
```

### PersistentVolumeClaims

```rust
use lmrc_kubernetes::pvc::{PersistentVolumeClaimSpec, AccessMode, StorageClass};

let pvc = PersistentVolumeClaimSpec::new("data-volume", "10Gi")
    .with_access_mode(AccessMode::ReadWriteOnce)
    .with_storage_class(StorageClass::Standard);

client.pvcs().apply(&pvc).await?;
```

### HorizontalPodAutoscaler

```rust
use lmrc_kubernetes::hpa::{HpaSpec, MetricType, MetricTarget};

let hpa = HpaSpec::new("my-app-hpa", "my-app")
    .with_replicas(2, 10)
    .with_metric(MetricType::Resource {
        name: "cpu".to_string(),
        target: MetricTarget::Utilization(80),
    });

client.hpas().apply(&hpa).await?;
```

### Rollback Deployment

```rust
use lmrc_kubernetes::config::RollbackOptions;

let rollback_opts = RollbackOptions::new()
    .revision(3)  // Optional: specify revision
    .timeout_secs(300);

client.deployments()
    .rollback("my-app", &rollback_opts)
    .await?;
```

### Scale Deployment

```rust
// Scale to 10 replicas
client.deployments().scale("my-app", 10).await?;
```

### Multi-Namespace Operations

```rust
// Create clients for different namespaces
let prod_client = client.with_namespace("production");
let staging_client = client.with_namespace("staging");

// Deploy to production
prod_client.deployments().apply(&deployment, &options).await?;

// Deploy to staging
staging_client.deployments().apply(&deployment, &options).await?;
```

## Error Handling

The library provides comprehensive error types with detailed context:

```rust
use lmrc_kubernetes::Error;

match client.deployments().apply(&deployment, &options).await {
    Ok(_) => println!("Deployment successful"),
    Err(Error::ValidationError(msg)) => eprintln!("Invalid spec: {}", msg),
    Err(Error::ImagePullError { image, container }) => {
        eprintln!("Failed to pull image {} for container {}", image, container)
    }
    Err(Error::ContainerCrashed { container, exit_code, reason }) => {
        eprintln!("Container {} crashed with code {}: {}", container, exit_code, reason)
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

## Architecture

The library is organized into focused modules:

- `client`: Main client for accessing Kubernetes API
- `deployment`: Deployment specifications and management
- `service`: Service specifications and management
- `secret`: Secret management
- `namespace`: Namespace operations
- `configmap`: ConfigMap management
- `ingress`: Ingress management
- `gateway`: Gateway API management
- `networkpolicy`: NetworkPolicy management
- `job`: Job management
- `cronjob`: CronJob management
- `pvc`: PersistentVolumeClaim management
- `hpa`: HorizontalPodAutoscaler management
- `config`: Configuration types and options
- `error`: Comprehensive error types

## Testing

Run the test suite:

```bash
# Run unit tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Check code quality
cargo clippy -- -W clippy::all
cargo fmt --check
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

Part of the LMRC Stack project. Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](../../LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](../../LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.
## Links

- [Documentation](https://docs.rs/lmrc-kubernetes)
- [Crates.io](https://crates.io/crates/lmrc-kubernetes)
- [Repository](https://gitlab.com/lemarco/lmrc-kubernetes)
- [Issue Tracker](https://gitlab.com/lemarco/lmrc-kubernetes/-/issues)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
