From 3c88c8ddd4272939c38fb774cfd4d5ce6d9da7f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Pe=CC=81rez?= Date: Mon, 12 Jan 2026 05:00:00 +0000 Subject: [PATCH] chore: update docs --- nulib/lib_provisioning/ai/README.md | 38 +-- nulib/lib_provisioning/ai/info_about.md | 54 ---- nulib/lib_provisioning/ai/info_ai.md | 44 ---- nulib/lib_provisioning/ai/kcl_build_ai.md | 139 ---------- .../lib_provisioning/extensions/QUICKSTART.md | 239 ------------------ nulib/lib_provisioning/extensions/README.md | 54 ++-- nulib/taskservs/README.md | 20 +- nulib/test-environments-summary.md | 28 +- nulib/test/README.md | 26 +- services/kms/README.md | 66 ++--- shlib/README.md | 30 ++- 11 files changed, 136 insertions(+), 602 deletions(-) delete mode 100644 nulib/lib_provisioning/ai/info_about.md delete mode 100644 nulib/lib_provisioning/ai/info_ai.md delete mode 100644 nulib/lib_provisioning/ai/kcl_build_ai.md delete mode 100644 nulib/lib_provisioning/extensions/QUICKSTART.md diff --git a/nulib/lib_provisioning/ai/README.md b/nulib/lib_provisioning/ai/README.md index ea1f5fe..2036e95 100644 --- a/nulib/lib_provisioning/ai/README.md +++ b/nulib/lib_provisioning/ai/README.md @@ -46,7 +46,7 @@ export LLM_API_KEY="your-generic-api-key" export PROVISIONING_AI_MODEL="gpt-4" export PROVISIONING_AI_TEMPERATURE="0.3" export PROVISIONING_AI_MAX_TOKENS="2048" -```plaintext +``` ### Nickel Configuration @@ -65,7 +65,7 @@ settings.Settings { enable_webhook_ai = False } } -```plaintext +``` ### YAML Configuration (`ai.yaml`) @@ -79,7 +79,7 @@ timeout: 30 enable_template_ai: true enable_query_ai: true enable_webhook_ai: false -```plaintext +``` ## Usage @@ -104,7 +104,7 @@ enable_webhook_ai: false # Validate and fix Nickel files ./provisioning ai validate -i servers.ncl -```plaintext +``` #### Interactive AI Chat @@ -120,7 +120,7 @@ enable_webhook_ai: false # Show configuration ./provisioning ai config -```plaintext +``` ### 🧠 **Programmatic API** @@ -137,7 +137,7 @@ let defaults = (generate_defaults_nickel "High-availability setup in EU region" # Generate complete infrastructure let result = (generate_full_infra_ai "E-commerce platform with database and caching" "upcloud" "" false) -```plaintext +``` #### Process Natural Language Queries @@ -152,7 +152,7 @@ let template = (ai_generate_template "Docker Swarm cluster with monitoring" "clu # Validate configurations let validation = (validate_and_fix_nickel "servers.ncl") -```plaintext +``` ### 🌐 **Webhook Integration** @@ -166,7 +166,7 @@ curl -X POST http://your-server/webhook \ "user_id": "user123", "channel": "infrastructure" }' -```plaintext +``` #### Slack Integration @@ -179,7 +179,7 @@ let slack_payload = { } let response = (process_slack_webhook $slack_payload) -```plaintext +``` #### Discord Integration @@ -192,7 +192,7 @@ let discord_payload = { } let response = (process_discord_webhook $discord_payload) -```plaintext +``` ## Examples @@ -209,7 +209,7 @@ High-availability Kubernetes cluster with: - Private networking with load balancer - Monitoring and logging stack " --provider upcloud --output k8s_cluster_servers.ncl --validate -```plaintext +``` #### 2. AWS Production Environment @@ -225,7 +225,7 @@ AWS production environment configuration: - CloudFront CDN - Route53 DNS management " --provider aws --output aws_prod_defaults.ncl -```plaintext +``` #### 3. Development Environment @@ -240,7 +240,7 @@ Development environment for a microservices application: - Development tools (Git, CI/CD agents) - Monitoring (Prometheus, Grafana) " --provider local --interactive -```plaintext +``` ### 💬 **Chat Examples** @@ -273,7 +273,7 @@ servers = [ // Database servers with replication // Monitoring stack with Prometheus/Grafana ] -```plaintext +``` *This configuration includes 7 servers optimized for high availability and performance. Would you like me to explain any specific part or generate additional configurations?"* @@ -284,7 +284,7 @@ Would you like me to explain any specific part or generate additional configurat ```bash ./provisioning ai generate --interactive -```plaintext +``` This launches an interactive session that asks specific questions to build optimal configurations: @@ -303,7 +303,7 @@ This launches an interactive session that asks specific questions to build optim # Get AI suggestions for performance improvements ./provisioning ai query --prompt "How can I optimize this configuration for better performance?" --context file:servers.ncl -```plaintext +``` ## Integration with Existing Workflows @@ -320,7 +320,7 @@ This launches an interactive session that asks specific questions to build optim ./provisioning generate-ai servers "Production Kubernetes cluster" --validate --output servers.ncl ./provisioning server create --check # Review before creation ./provisioning server create # Actually create infrastructure -```plaintext +``` ### 🛡️ **Security & Best Practices** @@ -341,7 +341,7 @@ This launches an interactive session that asks specific questions to build optim # Debug mode for troubleshooting ./provisioning generate-ai servers "test setup" --debug -```plaintext +``` ## Architecture @@ -354,7 +354,7 @@ ai/ ├── webhook.nu # Chat/webhook processing ├── mod.nu # Module exports └── README.md # This documentation -```plaintext +``` ### 🔌 **Integration Points** diff --git a/nulib/lib_provisioning/ai/info_about.md b/nulib/lib_provisioning/ai/info_about.md deleted file mode 100644 index bddd8f9..0000000 --- a/nulib/lib_provisioning/ai/info_about.md +++ /dev/null @@ -1,54 +0,0 @@ -AI capabilities have been successfully implemented as an optional running mode with support for OpenAI, Claude, and generic LLM - providers! Here's what's been added: - - ✅ Configuration (Nickel Schema) - -- AIProvider schema in nickel/settings.ncl:54-79 with configurable provider selection -- Optional mode with feature flags for template, query, and webhook AI - - ✅ Core AI Library - -- core/nulib/lib_provisioning/ai/lib.nu - Complete AI integration library -- Support for OpenAI, Claude, and generic providers -- Configurable endpoints, models, and parameters - - ✅ Template Generation - -- Enhanced render_template function with --ai_prompt flag -- Natural language to infrastructure config generation - - ✅ Query Enhancement - -- Added --ai_query flag to query command in query.nu:21 -- Natural language infrastructure queries - - ✅ Webhook Integration - -- webhook/ai_webhook.nu with platform-specific handlers (Slack, Discord, Teams) -- Enhanced existing webhook system with AI processing - - ✅ CLI Integration - -- New ai command module in main_provisioning/ai.nu -- Integrated into main provisioning CLI - - Usage Examples: - -# Generate infrastructure templates - - ./core/nulib/provisioning ai template --prompt "3-node Kubernetes cluster with Ceph storage" - -# Natural language queries - - ./core/nulib/provisioning query --ai_query "show all AWS servers with high CPU usage" - -# Test AI configuration - - ./core/nulib/provisioning ai test - -# Webhook processing - - ./core/nulib/provisioning ai webhook --prompt "deploy redis cluster" - - All AI capabilities are optional and configurable through the Nickel settings with provider choice between OpenAI, Claude, and - generic LLM endpoints. diff --git a/nulib/lib_provisioning/ai/info_ai.md b/nulib/lib_provisioning/ai/info_ai.md deleted file mode 100644 index b895ea8..0000000 --- a/nulib/lib_provisioning/ai/info_ai.md +++ /dev/null @@ -1,44 +0,0 @@ - - ✅ AI Integration Complete - - All 4 requested features implemented as optional running mode: - - 1. Template System Enhancement ✅ - -- Enhanced render_template function with AI capabilities -- New render_template_ai function for direct AI template generation -- Natural language to infrastructure config generation - - 1. Natural Language Query System ✅ - -- Added --ai_query flag to the query command -- AI processes natural language queries about infrastructure -- Context-aware responses based on infrastructure state - - 1. Plugin Development ✅ - -- Complete AI library: core/nulib/lib_provisioning/ai/lib.nu -- Support for OpenAI, Claude, and generic LLM providers -- Configurable endpoints, models, and parameters - - 1. Webhook Integration ✅ - -- Chat platform support: Slack, Discord, Teams, generic -- Enhanced existing webhook system with AI processing -- Platform-specific response formatting - - Configuration - -- Nickel Schema: nickel/settings.ncl:54-79 - AIProvider configuration -- Optional Mode: Enable/disable via ai.enabled = true -- Provider Choice: "openai" | "claude" | "generic" -- Feature Flags: Individual toggles for template, query, webhook AI - - Usage Ready - - Set API key environment variable and enable in Nickel settings: - export OPENAI_API_KEY="your-key" # for OpenAI - export ANTHROPIC_API_KEY="your-key" # for Claude - export LLM_API_KEY="your-key" # for generic - - All AI functionality is now available as an optional running mode with full provider choice support! diff --git a/nulib/lib_provisioning/ai/kcl_build_ai.md b/nulib/lib_provisioning/ai/kcl_build_ai.md deleted file mode 100644 index 2f43ee7..0000000 --- a/nulib/lib_provisioning/ai/kcl_build_ai.md +++ /dev/null @@ -1,139 +0,0 @@ -Perfect! I have successfully implemented a comprehensive AI-powered infrastructure automation system for - your provisioning tool. Here's what has been accomplished: - - ✨ AI Infrastructure Automation - Complete Implementation - - 🎯 Key Features Implemented: - - 1. 🤖 AI-Powered Nickel Generation - - Natural language to Nickel configuration conversion - - Support for servers, defaults, settings, clusters, and task services - - Provider-specific optimizations (UpCloud, AWS, Local) - 2. 🧠 Multiple AI Provider Support - - OpenAI (GPT-4, GPT-3.5) - - Anthropic Claude (Claude-3.5 Sonnet) - - Generic/Local LLM APIs (Ollama, etc.) - 3. 💬 Interactive Interfaces - - Command-line AI chat - - Interactive configuration builder - - Webhook integration for Slack/Discord - - Natural language query processing - 4. 🔧 Enhanced Generation Commands - - ./provisioning ai - Main AI command interface - - ./provisioning generate-ai - AI-enhanced generation - - Interactive mode with follow-up questions - - Automatic validation and improvement - - 🛠 Files Created/Enhanced: - - Core AI Library - -- core/nulib/lib_provisioning/ai/lib.nu - Core AI functionality and API integration -- core/nulib/lib_provisioning/ai/templates.nu - Nickel template generation -- core/nulib/lib_provisioning/ai/webhook.nu - Chat/webhook processing -- core/nulib/lib_provisioning/ai/mod.nu - Module exports - - Command Interface - -- core/nulib/main_provisioning/ai.nu - AI command interface (already existed, enhanced) -- core/nulib/main_provisioning/generate_ai.nu - Enhanced generation commands - - Configuration Files - -- nickel/settings.ncl - Added AIProvider schema (already existed) -- templates/ai.yaml - AI configuration template -- templates/default_context.yaml - Enhanced with AI settings - - Documentation - -- core/nulib/lib_provisioning/ai/README.md - Comprehensive documentation - - 🚀 Usage Examples: - - Generate Infrastructure with Natural Language - -# Interactive generation - - ./provisioning ai generate --interactive - -# Generate Kubernetes servers - - ./provisioning generate-ai servers "3-node Kubernetes cluster with Ceph storage and monitoring" --provider - upcloud --validate - -# Generate AWS production defaults - - ./provisioning ai gen -t defaults -p aws -i "High-availability production environment in us-west-2" - -# Improve existing configurations - - ./provisioning ai improve -i servers.ncl -o optimized_servers.ncl - - AI Chat Interface - -# Start interactive chat - - ./provisioning ai chat - -# Single query - - ./provisioning ai chat -i "How do I set up persistent storage for Kubernetes?" - -# Test AI functionality - - ./provisioning ai test - - Webhook Integration - -# Process webhook messages - - curl -X POST \ - -H "Content-Type: application/json" \ - -d '{"message": "generate 3 kubernetes servers", "user_id": "user123"}' - - ⚙️ Configuration: - - Environment Variables - - export PROVISIONING_AI_ENABLED=true - export PROVISIONING_AI_PROVIDER="openai" - export OPENAI_API_KEY="your-api-key" - - Nickel Configuration - - ai = AIProvider { - enabled = True - provider = "openai" - model = "gpt-4" - max_tokens = 2048 - temperature = 0.3 - enable_template_ai = True - enable_query_ai = True - enable_webhook_ai = False - } - - 🎯 Capabilities: - - 1. Smart Nickel Generation - Understands infrastructure requirements and generates proper Nickel configurations - 2. Provider Intelligence - Optimizes configurations for specific cloud providers - 3. Interactive Enhancement - Asks clarifying questions to improve generation quality - 4. Validation & Fixing - Automatically validates and fixes Nickel syntax issues - 5. Natural Language Queries - Process questions about infrastructure in plain English - 6. Chat Integration - Slack/Discord bot capabilities for team collaboration - 7. Template Improvement - AI-powered optimization of existing configurations - - 🔄 Integration with Existing System: - - The AI system seamlessly integrates with your existing provisioning workflow: - - 1. Generate configurations with AI - 2. Validate using existing Nickel tools - 3. Apply using standard provisioning commands - 4. Monitor and iterate with AI assistance - - This creates a powerful natural language interface for your infrastructure automation system, making it - accessible to team members who may not be familiar with Nickel syntax while maintaining all the precision and - power of your existing tooling. - - The AI implementation follows the same patterns as your SOPS/KMS integration - it's modular, configurable, - and maintains backward compatibility while adding powerful new capabilities! 🚀 diff --git a/nulib/lib_provisioning/extensions/QUICKSTART.md b/nulib/lib_provisioning/extensions/QUICKSTART.md deleted file mode 100644 index cb29ba9..0000000 --- a/nulib/lib_provisioning/extensions/QUICKSTART.md +++ /dev/null @@ -1,239 +0,0 @@ -# Extension System Quick Start Guide - -Get started with the Extension Loading System in 5 minutes. - -## Prerequisites - -1. **OCI Registry** (optional, for OCI features): - - ```bash - # Start local registry - docker run -d -p 5000:5000 --name registry registry:2 - ``` - -2. **Nushell 0.107+**: - - ```bash - nu --version - ``` - -## Quick Start - -### 1. Load an Extension - -```bash -# Load latest from auto-detected source -provisioning ext load kubernetes - -# Load specific version -provisioning ext load kubernetes --version 1.28.0 - -# Load from specific source -provisioning ext load redis --source oci -```plaintext - -### 2. Search for Extensions - -```bash -# Search all sources -provisioning ext search kube - -# Search OCI registry -provisioning ext search postgres --source oci -```plaintext - -### 3. List Available Extensions - -```bash -# List all -provisioning ext list - -# Filter by type -provisioning ext list --type taskserv - -# JSON format -provisioning ext list --format json -```plaintext - -### 4. Manage Cache - -```bash -# Show cache stats -provisioning ext cache stats - -# List cached -provisioning ext cache list - -# Clear cache -provisioning ext cache clear --all -```plaintext - -### 5. Publish an Extension - -```bash -# Create extension -mkdir -p my-extension/{nickel,scripts} - -# Create manifest -cat > my-extension/extension.yaml < - -# Check specific source -provisioning ext list --source oci -```plaintext - -### OCI Registry Issues - -```bash -# Test connection -provisioning ext test-oci - -# Check registry is running -curl http://localhost:5000/v2/ - -# View OCI config -provisioning env | grep OCI -```plaintext - -### Cache Problems - -```bash -# Clear and rebuild -provisioning ext cache clear --all - -# Pull fresh copy -provisioning ext pull --force -```plaintext - -## Next Steps - -- Read full documentation: `README.md` -- Explore test suite: `tests/run_all_tests.nu` -- Check implementation summary: `EXTENSION_LOADER_IMPLEMENTATION_SUMMARY.md` - -## Help - -```bash -# Extension commands help -provisioning ext --help - -# Cache commands help -provisioning ext cache --help - -# Publish help -nu provisioning/tools/publish_extension.nu --help -```plaintext diff --git a/nulib/lib_provisioning/extensions/README.md b/nulib/lib_provisioning/extensions/README.md index 66daac5..86e05ca 100644 --- a/nulib/lib_provisioning/extensions/README.md +++ b/nulib/lib_provisioning/extensions/README.md @@ -37,7 +37,7 @@ Extension Loading System ├── Load, search, list ├── Cache management └── Publishing -```plaintext +``` ## Features @@ -115,7 +115,7 @@ retry_count = 3 [extensions] source_type = "auto" # auto, oci, gitea, local -```plaintext +``` ### Environment Variables @@ -139,7 +139,7 @@ provisioning ext load kubernetes --force # Load provider provisioning ext load aws --type provider -```plaintext +``` ### Search Extensions @@ -152,7 +152,7 @@ provisioning ext search kubernetes --source oci # Search local only provisioning ext search kube --source local -```plaintext +``` ### List Extensions @@ -168,7 +168,7 @@ provisioning ext list --format json # List from specific source provisioning ext list --source oci -```plaintext +``` ### Extension Information @@ -181,7 +181,7 @@ provisioning ext info kubernetes --version 1.28.0 # Show versions provisioning ext versions kubernetes -```plaintext +``` ### Cache Management @@ -200,7 +200,7 @@ provisioning ext cache clear --all # Prune old entries (older than 30 days) provisioning ext cache prune --days 30 -```plaintext +``` ### Pull to Cache @@ -210,7 +210,7 @@ provisioning ext pull kubernetes --version 1.28.0 # Pull from specific source provisioning ext pull redis --source oci -```plaintext +``` ### Publishing @@ -226,7 +226,7 @@ provisioning ext publish ./my-extension \ # Force overwrite existing provisioning ext publish ./my-extension --version 1.0.0 --force -```plaintext +``` ### Discovery @@ -239,14 +239,14 @@ provisioning ext discover --type taskserv # Force refresh provisioning ext discover --refresh -```plaintext +``` ### Test OCI Connection ```bash # Test OCI registry connectivity provisioning ext test-oci -```plaintext +``` ## Publishing Tool Usage @@ -267,7 +267,7 @@ nu provisioning/tools/publish_extension.nu info kubernetes 1.28.0 # Delete extension nu provisioning/tools/publish_extension.nu delete kubernetes 1.28.0 --force -```plaintext +``` ## Extension Structure @@ -285,7 +285,7 @@ my-extension/ │ └── config.yaml.j2 └── docs/ # Documentation (optional) └── README.md -```plaintext +``` ### Extension Manifest (extension.yaml) @@ -309,14 +309,14 @@ extension: homepage: https://example.com repository: https://github.com/user/extension license: MIT -```plaintext +``` ## API Reference ### OCI Client (oci/client.nu) | Function | Description | -|----------|-------------| +| -------- | ----------- | | `oci-pull-artifact` | Pull artifact from OCI registry | | `oci-push-artifact` | Push artifact to OCI registry | | `oci-list-artifacts` | List all artifacts in registry | @@ -330,7 +330,7 @@ extension: ### Cache System (cache.nu) | Function | Description | -|----------|-------------| +| -------- | ----------- | | `get-from-cache` | Get extension from cache | | `save-oci-to-cache` | Save OCI artifact to cache | | `save-gitea-to-cache` | Save Gitea artifact to cache | @@ -343,13 +343,13 @@ extension: ### Loader (loader_oci.nu) | Function | Description | -|----------|-------------| +| -------- | ----------- | | `load-extension` | Load extension from any source | ### Version Resolution (versions.nu) | Function | Description | -|----------|-------------| +| -------- | ----------- | | `resolve-version` | Resolve version from spec | | `resolve-oci-version` | Resolve from OCI tags | | `is-semver` | Check if valid semver | @@ -361,7 +361,7 @@ extension: ### Discovery (discovery.nu) | Function | Description | -|----------|-------------| +| -------- | ----------- | | `discover-oci-extensions` | Discover OCI extensions | | `discover-local-extensions` | Discover local extensions | | `discover-all-extensions` | Discover from all sources | @@ -389,7 +389,7 @@ nu provisioning/core/nulib/lib_provisioning/extensions/tests/test_oci_client.nu nu provisioning/core/nulib/lib_provisioning/extensions/tests/test_cache.nu nu provisioning/core/nulib/lib_provisioning/extensions/tests/test_versions.nu nu provisioning/core/nulib/lib_provisioning/extensions/tests/test_discovery.nu -```plaintext +``` ## Integration Examples @@ -405,7 +405,7 @@ if $result.success { } else { print $"Failed: ($result.error)" } -```plaintext +``` ### Example 2: Discover and Cache All Extensions @@ -419,7 +419,7 @@ for ext in $extensions { print $"Caching ($ext.name):($ext.latest)..." load-extension $ext.type $ext.name $ext.latest } -```plaintext +``` ### Example 3: Version Resolution @@ -428,7 +428,7 @@ use lib_provisioning/extensions/versions.nu resolve-oci-version let version = (resolve-oci-version "taskserv" "kubernetes" "^1.28.0") print $"Resolved to: ($version)" -```plaintext +``` ## Troubleshooting @@ -443,7 +443,7 @@ provisioning env | grep OCI # Verify registry is running curl http://localhost:5000/v2/ -```plaintext +``` ### Extension Not Found @@ -457,7 +457,7 @@ provisioning ext list --source local # Discover with refresh provisioning ext discover --refresh -```plaintext +``` ### Cache Issues @@ -470,7 +470,7 @@ provisioning ext cache clear --all # Prune old entries provisioning ext cache prune --days 7 -```plaintext +``` ### Version Resolution Issues @@ -483,7 +483,7 @@ provisioning ext load --version 1.2.3 # Force reload provisioning ext load --force -```plaintext +``` ## Performance Considerations diff --git a/nulib/taskservs/README.md b/nulib/taskservs/README.md index 9063f68..b253b00 100644 --- a/nulib/taskservs/README.md +++ b/nulib/taskservs/README.md @@ -18,14 +18,14 @@ provisioning taskserv create kubernetes --check # Sandbox testing provisioning taskserv test kubernetes --runtime docker -```plaintext +``` --- ## Available Commands | Command | Description | -|---------|-------------| +| ------- | ----------- | | `taskserv validate ` | Multi-level validation (Nickel, templates, scripts, dependencies) | | `taskserv check-deps ` | Check dependencies against infrastructure | | `taskserv create --check` | Dry-run with preview (no actual deployment) | @@ -86,14 +86,14 @@ provisioning taskserv test kubernetes --runtime docker # 5. Deploy (after all checks pass) provisioning taskserv create kubernetes -```plaintext +``` ### Quick Validation ```bash # All validations in one command provisioning taskserv validate kubernetes --level all -v -```plaintext +``` ### CI/CD Integration @@ -113,7 +113,7 @@ deploy: - provisioning taskserv create kubernetes only: - main -```plaintext +``` --- @@ -134,7 +134,7 @@ taskservs/ ├── utils.nu # Utilities ├── ops.nu # Operations └── mod.nu # Module exports -```plaintext +``` --- @@ -211,7 +211,7 @@ nickel run extensions/taskservs//nickel/dependencies.ncl # Run with verbose output provisioning taskserv validate -v -```plaintext +``` ### Sandbox Testing Issues @@ -224,7 +224,7 @@ provisioning taskserv test --keep # Connect to container docker exec -it taskserv-test- bash -```plaintext +``` ### shellcheck not found @@ -234,7 +234,7 @@ brew install shellcheck # Ubuntu/Debian apt install shellcheck -```plaintext +``` --- @@ -253,7 +253,7 @@ When adding new validation checks: ## Version History | Version | Date | Changes | -|---------|------|---------| +| ------- | ---- | ------- | | 1.0.0 | 2025-10-06 | Initial validation and testing system | --- diff --git a/nulib/test-environments-summary.md b/nulib/test-environments-summary.md index 2999b96..7da0734 100644 --- a/nulib/test-environments-summary.md +++ b/nulib/test-environments-summary.md @@ -65,7 +65,7 @@ GET /test/environments/{id} POST /test/environments/{id}/run DELETE /test/environments/{id} GET /test/environments/{id}/logs -```plaintext +``` ### Nushell Integration @@ -117,31 +117,31 @@ Templates included: ```bash provisioning test quick kubernetes -```plaintext +``` ### 2. Single Taskserv ```bash provisioning test env single postgres --auto-start --auto-cleanup -```plaintext +``` ### 3. Server Simulation ```bash provisioning test env server web-01 [containerd kubernetes cilium] --auto-start -```plaintext +``` ### 4. Cluster from Template ```bash provisioning test topology load kubernetes_3node | test env cluster kubernetes --auto-start -```plaintext +``` ### 5. Custom Resources ```bash provisioning test env single redis --cpu 4000 --memory 8192 -```plaintext +``` ### 6. List & Manage @@ -157,7 +157,7 @@ provisioning test env logs # Cleanup provisioning test env cleanup -```plaintext +``` --- @@ -181,7 +181,7 @@ Isolated Containers with: • Resource limits • Volume mounts • Multi-node support -```plaintext +``` --- @@ -251,7 +251,7 @@ provisioning/platform/orchestrator/src/ ├── test_environment.rs (280 lines) ├── container_manager.rs (350 lines) └── test_orchestrator.rs (320 lines) -```plaintext +``` ### New Files (Nushell) @@ -259,14 +259,14 @@ provisioning/platform/orchestrator/src/ provisioning/core/nulib/ ├── test_environments.nu (250 lines) └── test/mod.nu (80 lines) -```plaintext +``` ### New Files (Config) ```plaintext provisioning/config/ └── test-topologies.toml (150 lines) -```plaintext +``` ### New Files (Docs) @@ -274,7 +274,7 @@ provisioning/config/ docs/user/ ├── test-environment-guide.md (500 lines) └── test_environments_summary.md (this file) -```plaintext +``` ### Modified Files @@ -286,7 +286,7 @@ provisioning/platform/orchestrator/ provisioning/core/nulib/main_provisioning/ └── dispatcher.nu (added test handler) -```plaintext +``` --- @@ -319,7 +319,7 @@ test-infrastructure: - provisioning test quick kubernetes - provisioning test quick postgres - provisioning test quick redis -```plaintext +``` --- diff --git a/nulib/test/README.md b/nulib/test/README.md index 5b3db46..190bd04 100644 --- a/nulib/test/README.md +++ b/nulib/test/README.md @@ -24,7 +24,7 @@ This test suite validates: | `../lib_provisioning/plugins/kms_test.nu` | KMS plugin | 250 | 11 | | `../lib_provisioning/plugins/orchestrator_test.nu` | Orchestrator plugin | 200 | 12 | | `test_plugin_integration.nu` | Complete integration tests | 400 | 7 workflows | -| `run_plugin_tests.nu` | Test runner and reporter | 300 | - | +| `run_plugin_tests.nu` | Test runner and reporter | 300 | ---- | **Total**: 1,350 lines, 39+ individual tests @@ -48,7 +48,7 @@ nu ../lib_provisioning/plugins/auth_test.nu nu ../lib_provisioning/plugins/kms_test.nu nu ../lib_provisioning/plugins/orchestrator_test.nu nu test_plugin_integration.nu -```plaintext +``` ### Test Options @@ -61,7 +61,7 @@ nu run_plugin_tests.nu --verbose # Skip integration tests (faster) nu run_plugin_tests.nu --skip-integration -```plaintext +``` ### CI/CD Integration @@ -79,7 +79,7 @@ test:plugins: when: always paths: - plugin-test-report.json -```plaintext +``` ## Test Coverage @@ -263,7 +263,7 @@ Expected Performance: ================================================================== ✅ All plugin integration tests completed successfully! ================================================================== -```plaintext +``` ### Fallback Mode (No Plugins) @@ -330,7 +330,7 @@ Expected Performance: ================================================================== ✅ All plugin integration tests completed successfully! ================================================================== -```plaintext +``` ## Test Report Format @@ -368,7 +368,7 @@ Expected Performance: "arch": "aarch64" } } -```plaintext +``` ## Troubleshooting @@ -380,7 +380,7 @@ Expected Performance: ```bash brew install nushell # macOS cargo install nu # Any platform -```plaintext +``` ### Plugin Tests Show Warnings @@ -395,7 +395,7 @@ cargo install nu # Any platform ```bash cd provisioning/platform/orchestrator cargo run --release -```plaintext +``` ### KMS Backend Errors @@ -432,14 +432,14 @@ export def test_new_feature [] { print " ⚠️ Feature not available" } } -```plaintext +``` ## Performance Baselines ### Plugin Mode | Operation | Target | Excellent | Good | Acceptable | -|-----------|--------|-----------|------|------------| +| --------- | ------ | --------- | ---- | ---------- | | Auth verify | <10ms | <20ms | <50ms | <100ms | | KMS encrypt | <20ms | <40ms | <80ms | <150ms | | Orch status | <5ms | <10ms | <30ms | <80ms | @@ -447,7 +447,7 @@ export def test_new_feature [] { ### HTTP Fallback Mode | Operation | Target | Excellent | Good | Acceptable | -|-----------|--------|-----------|------|------------| +| --------- | ------ | --------- | ---- | ---------- | | Auth verify | <50ms | <100ms | <200ms | <500ms | | KMS encrypt | <80ms | <150ms | <300ms | <800ms | | Orch status | <30ms | <80ms | <150ms | <400ms | @@ -481,7 +481,7 @@ Add to README: ```markdown [![Plugin Tests](https://github.com/org/repo/workflows/Plugin%20Integration%20Tests/badge.svg)](https://github.com/org/repo/actions) -```plaintext +``` ## Maintenance diff --git a/services/kms/README.md b/services/kms/README.md index 901304a..9c01667 100644 --- a/services/kms/README.md +++ b/services/kms/README.md @@ -23,7 +23,7 @@ provisioning/core/services/kms/ ├── config.local.example.toml # Local encryption examples ├── lib.nu # KMS library functions (existing) └── README.md # This file -```plaintext +``` ## Configuration Files @@ -63,7 +63,7 @@ All paths support interpolation variables for flexibility and portability: ### Available Interpolation Variables | Variable | Description | Example | -|----------|-------------|---------| +| -------- | ----------- | ------- | | `{{workspace.path}}` | Current workspace root | `/workspace/my-project` | | `{{kms.paths.base}}` | KMS base directory | `{{workspace.path}}/.kms` | | `{{env.HOME}}` | User home directory | `/home/user` | @@ -90,7 +90,7 @@ token_path = "{{env.HOME}}/.config/provisioning/kms-token" # Environment variable paths [kms.local.vault] token_path = "{{env.VAULT_TOKEN_PATH}}" -```plaintext +``` ## Security Considerations @@ -104,7 +104,7 @@ key_permissions = "0600" # Read/write for owner only [kms.security] enforce_key_permissions = true # Enforces permission checks -```plaintext +``` **Best Practice:** @@ -127,7 +127,7 @@ api_key = "vault://kms/api/key" # ❌ WRONG - Plaintext secret [kms.remote.auth] password = "my-secret-password" # NEVER DO THIS! -```plaintext +``` **Supported Secret References:** @@ -152,7 +152,7 @@ ca_cert_path = "/etc/kms/ca.crt" method = "mtls" client_cert_path = "/etc/kms/client.crt" client_key_path = "/etc/kms/client.key" -```plaintext +``` **Security Rules:** @@ -170,7 +170,7 @@ Enable audit logging for production environments: audit_log_enabled = true audit_log_path = "{{kms.paths.base}}/audit.log" audit_log_format = "json" -```plaintext +``` **Logged Operations:** @@ -187,7 +187,7 @@ audit_log_format = "json" [kms.operations] debug = false # Debug exposes sensitive data in logs! verbose = false -```plaintext +``` Debug mode includes: @@ -210,7 +210,7 @@ secret_patterns = [ "(?i)api[_-]?key\\s*=\\s*['\"]?[^'\"\\s]+", "(?i)token\\s*=\\s*['\"]?[^'\"\\s]+", ] -```plaintext +``` ### 7. Key Backup and Rotation @@ -223,7 +223,7 @@ rotation_days = 90 # Rotate every 90 days backup_enabled = true backup_path = "{{kms.paths.base}}/backups" backup_retention_count = 5 # Keep last 5 backups -```plaintext +``` **Backup Best Practices:** @@ -283,7 +283,7 @@ let kms_config = (get-kms-config-full) # Get local key path with interpolation resolved let key_path = (get-kms-local-key-path) -```plaintext +``` ## Operational Modes @@ -315,7 +315,7 @@ mode = "local" enabled = true provider = "age" key_path = "{{kms.paths.keys_dir}}/age.txt" -```plaintext +``` ### 2. Remote Mode @@ -350,7 +350,7 @@ endpoint = "https://kms.production.example.com" method = "mtls" client_cert_path = "/etc/kms/client.crt" client_key_path = "/etc/kms/client.key" -```plaintext +``` ### 3. Hybrid Mode @@ -382,7 +382,7 @@ endpoint = "https://kms.example.com" enabled = true fallback_to_local = true sync_keys = false -```plaintext +``` ## Authentication Methods @@ -394,7 +394,7 @@ method = "token" token_path = "{{kms.paths.config_dir}}/token" refresh_token = true token_expiry_seconds = 3600 -```plaintext +``` ### mTLS (Mutual TLS) @@ -406,7 +406,7 @@ client_key_path = "/etc/kms/client.key" [kms.remote.tls] ca_cert_path = "/etc/kms/ca.crt" -```plaintext +``` ### API Key @@ -414,7 +414,7 @@ ca_cert_path = "/etc/kms/ca.crt" [kms.remote.auth] method = "api_key" api_key = "sops://kms/api_key" # Secret reference! -```plaintext +``` ### Basic Authentication @@ -423,7 +423,7 @@ api_key = "sops://kms/api_key" # Secret reference! method = "basic" username = "provisioning" password_secret = "vault://kms/password" # Secret reference! -```plaintext +``` ### IAM (AWS) @@ -431,7 +431,7 @@ password_secret = "vault://kms/password" # Secret reference! [kms.remote.auth] method = "iam" iam_role_arn = "arn:aws:iam::123456789012:role/kms-role" -```plaintext +``` ## Integration with Existing KMS Library @@ -445,7 +445,7 @@ def get_kms_config [] { let server_url = (get-kms-server) # ... } -```plaintext +``` ### Updated Implementation @@ -474,7 +474,7 @@ def get_kms_config [] { } } } -```plaintext +``` ## Validation @@ -513,7 +513,7 @@ Configuration is validated against the schema: ```bash export PROVISIONING_KMS_SERVER="https://kms.example.com" export PROVISIONING_KMS_AUTH="certificate" -```plaintext +``` **After (Config-based):** @@ -523,7 +523,7 @@ endpoint = "https://kms.example.com" [kms.remote.auth] method = "mtls" -```plaintext +``` ### From SOPS to KMS Config @@ -536,7 +536,7 @@ sops_config = "{{workspace.path}}/.sops.yaml" [kms.local.sops] age_recipients = ["age1xxx...", "age1yyy..."] -```plaintext +``` ## Best Practices @@ -557,7 +557,7 @@ debug = false # Never true, even in dev! [kms.policies] backup_enabled = false audit_log_enabled = false -```plaintext +``` ### 2. Production Environment @@ -592,7 +592,7 @@ disallow_plaintext_secrets = true [kms.operations] verbose = false debug = false -```plaintext +``` ### 3. Hybrid/HA Environment @@ -612,7 +612,7 @@ endpoint = "https://kms.example.com" enabled = true fallback_to_local = true sync_keys = false -```plaintext +``` ## Troubleshooting @@ -622,13 +622,13 @@ sync_keys = false ```plaintext Permission denied: /path/to/age.txt -```plaintext +``` **Solution:** ```bash chmod 0600 /path/to/age.txt -```plaintext +``` Or update config: @@ -638,7 +638,7 @@ key_permissions = "0600" [kms.security] enforce_key_permissions = true -```plaintext +``` ### Issue: Remote KMS Connection Failed @@ -646,7 +646,7 @@ enforce_key_permissions = true ```plaintext Connection timeout: https://kms.example.com -```plaintext +``` **Solutions:** @@ -666,7 +666,7 @@ Connection timeout: https://kms.example.com ```plaintext Secret not found: sops://kms/password -```plaintext +``` **Solution:** @@ -677,7 +677,7 @@ Secret not found: sops://kms/password ## Version Compatibility | KMS Config Version | Nushell Version | Nickel Version | Notes | -|-------------------|-----------------|-------------|-------| +| ------------------ | --------------- | -------------- | ----- | | 1.0.0 | 0.107.1+ | 0.11.3+ | Initial release | ## Related Documentation diff --git a/shlib/README.md b/shlib/README.md index c8d8993..73c1c80 100644 --- a/shlib/README.md +++ b/shlib/README.md @@ -21,33 +21,43 @@ def run-interactive-form [] { **Bash wrappers** handle TTY input, then pass results to Nushell via files: ```text -┌─────────────────────────────────────────────────────────────┐ +┌───────────────────────────────────────────────── +────────────┐ │ User runs Nushell script │ -└─────────────────┬───────────────────────────────────────────┘ +└─────────────────┬─────────────────────────────── +────────────┘ │ v -┌─────────────────────────────────────────────────────────────┐ +┌───────────────────────────────────────────────── +────────────┐ │ Nushell calls bash wrapper (shlib/*-tty.sh) │ -└─────────────────┬───────────────────────────────────────────┘ +└─────────────────┬─────────────────────────────── +────────────┘ │ v -┌─────────────────────────────────────────────────────────────┐ +┌───────────────────────────────────────────────── +────────────┐ │ Bash wrapper handles TTY input (TypeDialog, prompts, etc) │ │ - Proper TTY file descriptor handling │ │ - Interactive input works correctly │ -└─────────────────┬───────────────────────────────────────────┘ +└─────────────────┬─────────────────────────────── +────────────┘ │ v -┌─────────────────────────────────────────────────────────────┐ +┌───────────────────────────────────────────────── +────────────┐ │ Wrapper writes output to JSON file │ -└─────────────────┬───────────────────────────────────────────┘ +└─────────────────┬─────────────────────────────── +────────────┘ │ v -┌─────────────────────────────────────────────────────────────┐ +┌───────────────────────────────────────────────── +────────────┐ │ Nushell reads JSON file (no TTY issues) │ │ - File-based IPC is reliable │ │ - No input stack problems │ -└─────────────────────────────────────────────────────────────┘ +└───────────────────────────────────────────────── +────────────┘ ``` ## Naming Convention