DevOps SDK

A Go SDK for building DevOps automation applications using ConfigHub as the configuration backend. This SDK provides reusable modules for cost analysis, waste detection, resource optimization, and deployment strategies. It extends the official SDK for ConfigHub which is here.

---

📚 Table of Contents

CLI Linting (Most Popular):

• Quick Start: CLI Command Linter
• CLI Command Validation (Full Docs)
• Testing & Verification
• Enforcement Mechanisms

SDK Modules:

• SDK Modules Overview
• Core Modules
• Usage Examples
• Helper Functions
• Example Apps

---

🎯 Quick Start: CLI Command Linter

Get quick feedback on ConfigHub CLI commands in your project:

⚠️Note: This is a linter that provides helpful hints, not comprehensive validation. Always test with the actual cub CLI.

# One-line validation
curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh | bash -s -- .# Or clone and run locally
git clone https://github.com/monadic/devops-sdk.git
cd devops-sdk
./cub-command-analyzer.sh /path/to/your/project

What it validates:

• ✅ Command syntax (entity + verb structure)
• ✅ Required flags and combinations
• ✅ WHERE clause grammar (EBNF compliance)
• ✅ Common error patterns from ConfigHub maintainer feedback
• ✅ Semantic correctness with pre/post conditions

Test coverage:

• 39/39 unit tests passing (for known patterns)
• Integration tests against real cub CLI (as of 2025-10-12)
• Validated against 154 commands across production projects
• Based on official feedback from Brian Grant (ConfigHub maintainer)
• Note: Tests validate known commands; may not cover newest CLI features

Quick links:

• 📖 Standalone Quick Start Guide
• 📚 Full CLI Validation Documentation
• 🔍 Testing & Verification
• ⚠️Known Limitations

---

SDK Modules

• app.go - Base DevOps app framework with health checks and informers
• confighub.go - ConfigHub client with Sets, Filters, and BulkOps support
• claude.go - Claude AI integration for intelligent analysis
• kubernetes.go - Kubernetes utilities and informer setup
• cost.go - Cost analysis module for resource pricing
• waste.go - Waste detection module for over-provisioning
• optimizer.go - Optimization engine for resource rightsizing
• deployment.go - Core deployment strategies
• deployment_dev.go - Development mode deployment (direct to K8s)
• deployment_enterprise.go - Enterprise mode deployment (via Git)
• health.go - Health check endpoints for monitoring
• health_check.go - Comprehensive health checking system
• tables.go - ASCII table rendering for terminal output
• retry.go - Retry logic with exponential backoff
• package.go - Package management for ConfigHub resources

Overview

The DevOps SDK enables building persistent, event-driven DevOps applications. Key characteristics:

• Persistent Apps: Run continuously with Kubernetes informers, not just when triggered
• Event-Driven: React immediately to changes, not on schedules
• Stateful: ConfigHub tracks all config state and history
• AI-Powered: Integrated Claude AI for intelligent decisions
• Bulk Operations: Sets and Filters for cross-environment operations

Prerequisites

New to ConfigHub? Start with MicroTraderX Prerequisites for step-by-step installation of Docker, Kind, and ConfigHub CLI.

Quick checklist:

• Docker running (docker info)
• ConfigHub CLI installed (cub version)
• ConfigHub authenticated (cub auth login)
• Kubernetes cluster running (kubectl cluster-info)

Mini TCK: ConfigHub + Kubernetes Integration Test

The SDK includes a minimal Technology Compatibility Kit for verifying ConfigHub + Kubernetes integration:

./test-confighub-k8s

What it tests:

• ✅ ConfigHub API connectivity
• ✅ Kubernetes cluster access (creates Kind cluster)
• ✅ Worker installation and connection
• ✅ Unit apply workflow (ConfigHub → K8s)
• ✅ Live state verification (K8s → ConfigHub)

Quick verification:

# Run directly
curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/test-confighub-k8s | bash

This TCK is used by TraderX and MicroTraderX as a pre-flight check before deployments. See TCK.md for full documentation.

CLI Command Validation

The SDK includes comprehensive validation tools for ConfigHub cub CLI usage:

cub Command Analyzer

Static analysis tool that validates every cub command in your scripts:

# Analyze entire project
./cub-command-analyzer.sh /path/to/your/project/
# Analyze specific directory
./cub-command-analyzer.sh bin/
# Remote analysis
curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh | bash -s -- .

What it validates:

• ✅ Command syntax (entity + verb structure)
• ✅ Required flags and combinations
• ✅ WHERE clause grammar (EBNF compliance)
• ✅ Common error patterns from Brian Grant's feedback
• ✅ Semantic correctness with pre/post conditions

Example output:

==========================================
FILE: bin/deploy
LINE 42: cub unit update backend --patch '{"spec":{"replicas":3}}'
==========================================
SYNTAX VALIDATION:
[FAIL] Invalid syntax
Error: --patch requires one of: --from-stdin, --filename, --restore, --upgrade,
--merge-source, --label, --delete-gate, --destroy-gate, or --changeset
GRAMMAR VALIDATION:
[N/A] No WHERE clause present
COMMON ERRORS:
[WARN] Common errors found:
- --patch requires additional flags
- Inline JSON with --patch is invalid. For DATA: use stdin (-).
For METADATA: use --from-stdin. For fine-grained: use 'cub function do'
- Missing required --space flag
[INFO] Suggested corrections:
For unit DATA update (spec.replicas, etc.):
echo '{...}' | cub unit update --space <space> <unit> -
For unit METADATA update (labels, annotations):
echo '{...}' | cub unit update --patch --space <space> <unit> --from-stdin
For fine-grained updates:
cub function do --space <space> --where "Slug = '<unit>'" set-replicas 3
SEMANTIC EXPLANATION:
Updates unit 'backend' with patch operation
Pre-condition: Unit 'backend' exists
Post-condition: Unit updated based on patch operation

Validation Framework

Core validation library used by the analyzer:

Location: test/lib/cub-test-framework.sh

Functions:

• validate_cub_syntax() - Command structure validation
• validate_where_clause() - WHERE clause EBNF compliance
• detect_common_errors() - Pattern matching for 7 common mistakes
• generate_semantic_explanation() - English description with pre/post conditions

Supported entities: space, unit, filter, function, worker, auth, run, link, changeset, set, revision, target, context, dataset

Test Suite

Comprehensive tests proving validator correctness:

Unit tests (test/unit/test-cub-validator.sh):

• 39 tests covering all validation functions
• Known valid commands from global-app
• Known invalid commands from Brian's feedback
• WHERE clause grammar (EBNF)
• Common error patterns
• Edge cases

Integration tests (test/integration/test-cub-validator-integration.sh):

• Compares validator with actual cub CLI behavior
• Validates against real ConfigHub API
• Cross-references with cub --help output

Run tests:

# Unit tests (no dependencies)
./test/unit/test-cub-validator.sh
# Integration tests (requires cub CLI)
cub auth login
./test/integration/test-cub-validator-integration.sh

Results:

Tests run: 39
Tests passed: 39
Tests failed: 0
Success rate: 100%

Test Data Fixtures

Example metadata templates for ConfigHub testing:

Location: test-data/

Files:

• metadata.json - Unit metadata template (labels/annotations)
• space-metadata.json - Space metadata template
• README.md - Usage documentation and best practices

Usage:

# Copy templates to your project
cp test-data/*.json your-project/test-data/
# Use in tests
cat test-data/metadata.json | cub unit create --from-stdin myunit --space myspace

Testing & Verification

How is this linter tested?

The linter is tested through multiple methods (though cannot guarantee perfect accuracy):

1. Integration Tests Against Real cub CLI

The validator's results are compared against actual cub CLI behavior:

# Run integration tests (requires cub auth)
./test/integration/test-cub-validator-integration.sh

What these tests prove:

• If validator says VALID → cub CLI succeeds ✅
• If validator says INVALID → cub CLI fails ✅
• Validator matches actual ConfigHub API behavior

2. Based on Official Maintainer Feedback

All validation rules derive from Brian Grant's feedback (ConfigHub maintainer):

Key insights from Brian:

• Inline JSON error: "You're passing that data patch (which isn't a thing you can pass to update) as the unit slug"
• WHERE clause limitations: Data fields are opaque, OR operator not supported
• Required flags: --patch requires companion flags (--from-stdin, --filename, --upgrade, etc.)

See test/strategies/cub-tests.md for complete feedback documentation.

3. Validated Against Production Projects

Real-world validation across production codebases:

Project	Total Commands	Valid	Invalid	Status
TraderX	88	88	0	✅ 100%
MicroTraderX	66	66	0	✅ 100%
DevOps Examples	Multiple apps	All valid	0	✅ 100%

Total validated: 154+ commands across 3 production projects

4. Comprehensive Unit Tests

39 unit tests covering:

• ✅ Valid commands from global-app (canonical patterns)
• ✅ Invalid commands from Brian's feedback
• ✅ WHERE clause EBNF grammar
• ✅ All common error patterns
• ✅ Edge cases and boundary conditions

Test results: 39/39 passing (100% success rate)

5. Cross-Referenced with Official Documentation

Validation rules cross-checked against:

• ConfigHub source code (/confighub/public/cmd/cub/*.go)
• Official ConfigHub CLI help text (cub --help, cub <entity> --help)
• WHERE clause grammar specification (EBNF)

Confidence level: Moderate - Provides helpful linting for common patterns

Important limitations:

• Validator is a static analyzer with hardcoded rules
• May lag behind CLI updates (last synced: 2025-10-12, cub commit a9e49ba)
• Cannot validate all command combinations
• Always test with actual cub CLI before deploying

This tool provides quick feedback for obvious errors, but is not a substitute for testing with the actual CLI.

See LIMITATIONS.md for complete list of what this linter cannot do.

Validation Standards

All projects using this SDK must:

• ✅ Run cub-command-analyzer before commits
• ✅ Fix all invalid commands (exit code 0 required)
• ✅ Document validation status in README/TESTING.md
• ✅ Include CLI validation in CI/CD pipelines
• ✅ Validate documentation code (README, QUICKSTART, tutorials)

Documentation Code is Production Code: Commands in .md files are copy-pasted by users. Invalid examples cause hours of debugging frustration.

Current validation status (as of 2025-10-12):

• TraderX: 88/88 commands valid ✅
• MicroTraderX: 66/66 commands valid ✅
• DevOps Examples: 100% validated ✅

Note: Command counts are point-in-time metrics. Run the analyzer on your project to get current results.

See test/README.md for complete testing documentation.

Enforcement Mechanisms

To ensure CLI validation in your workflow:

1. Pre-Commit Hook

Install the pre-commit hook to validate commands before committing:

# Install hook
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
# Test hook
git add some-script.sh
git commit -m "test"# Hook runs automatically# Bypass hook (not recommended)
git commit --no-verify

The hook validates all staged shell scripts and prevents commits with invalid commands.

2. CI/CD Integration

Add GitHub Actions workflow to your repository:

File: .github/workflows/validate-cli.yml

name: Validate ConfigHub CLI Commandson:
push:
branches: [ main, develop ]pull_request:
branches: [ main, develop ]jobs:
validate-cli:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- name: Download validatorrun: | curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh \ -o cub-command-analyzer.sh chmod +x cub-command-analyzer.sh - name: Validate commandsrun: ./cub-command-analyzer.sh .

See examples/github-actions/validate-cli.yml for full example.

3. Enforcement Script

Use the enforcement script for manual validation:

# Validate current directory
./bin/validate-cli
# Validate specific project
./bin/validate-cli /path/to/project
# CI mode (stricter checks, no colors)
./bin/validate-cli --ci
# Show help
./bin/validate-cli --help

Exit codes:

• 0 - All commands valid
• 1 - Invalid commands found
• 2 - Validation errors (missing tools, etc.)

Core Modules

All content below this line 100% created by Claude.

1. Cost Analysis Module (cost.go) - 744 lines

Analyzes resource costs across ConfigHub spaces and Kubernetes deployments.

Features:

• Multi-cloud pricing models (AWS, GCP, Azure)
• Kubernetes resource cost estimation
• ConfigHub unit cost analysis
• Hierarchical space analysis
• Cost breakdown by resource type
• Support for all Kubernetes resource units (Ki, Mi, Gi, Ti, Pi)

Key Functions:

• NewCostAnalyzer() - Create cost analyzer with ConfigHub integration
• AnalyzeSpace() - Analyze costs for a single space
• AnalyzeHierarchy() - Analyze full environment hierarchy
• GenerateReport() - Create detailed cost report
• StoreAnalysisInConfigHub() - Save analysis results
• GetOptimizationRecommendations() - Get cost-saving suggestions
• ParseQuantity() - Parse Kubernetes resource quantities

2. Waste Detection Module (waste.go) - 890 lines

Identifies resource waste by comparing allocated vs actual usage.

Features:

• CPU waste detection with safety checks
• Memory waste analysis
• Storage waste identification
• Idle replica detection
• Waste categorization and prioritization
• Negative waste ratio protection

Key Functions:

• NewWasteAnalyzer() - Create waste analyzer with thresholds
• SetThresholds() - Configure waste detection sensitivity
• AnalyzeWaste() - Perform comprehensive waste analysis
• GenerateWasteReport() - Create detailed waste report
• IdentifyWaste() - High-level waste identification helper

3. Optimization Engine (optimizer.go) - 1,308 lines

Generates optimized configurations based on waste analysis.

Features:

• Multi-container resource optimization
• Proportional resource distribution
• Safety margin calculations (20% buffer)
• Risk assessment (LOW/MEDIUM/HIGH)
• Requests/limits ratios (CPU 150%, Memory 120%)
• Deep manifest copying with type safety

Key Functions:

• NewOptimizer() - Create optimization engine
• GenerateOptimizedConfiguration() - Generate optimized manifests
• ApplyOptimizations() - Apply optimizations to ConfigHub
• ValidateOptimizedConfiguration() - Validate optimized configs
• GenerateOptimizationReport() - Create optimization report
• StoreOptimizationInConfigHub() - Save optimizations

4. Dev Mode Deployment (deployment_dev.go)

Direct ConfigHub → Kubernetes deployment for fast development cycles.

Features:

• Direct manifest application
• No Git intermediary
• Watch and sync capabilities
• Instant rollback
• Validation tools

Key Functions:

• NewDevModeDeployer() - Create dev mode deployer
• DeployUnit() - Deploy single unit to Kubernetes
• DeploySpace() - Deploy entire space
• DeployWithFilter() - Deploy filtered units
• WatchAndSync() - Continuous sync from ConfigHub
• Rollback() - Rollback to previous revision
• ValidateDeployment() - Validate deployment status

5. Deployment Helper (deployment.go)

Core deployment strategies and environment management.

Features:

• Environment hierarchy creation (base → qa → staging → prod)
• Automatic space setup with unique prefixes
• Filter creation for bulk operations
• Base configuration loading
• Environment promotion patterns

Key Functions:

• NewDeploymentHelper() - Create deployment helper
• SetupBaseSpace() - Initialize base space with unique prefix
• CreateStandardFilters() - Create app/infra/all filters
• LoadBaseConfigurations() - Load configs from files
• CreateEnvironmentHierarchy() - Build full env hierarchy
• CreateVariant() - Create config variant
• ApplyToEnvironment() - Deploy to specific environment
• PromoteEnvironment() - Promote between environments
• QuickDeploy() - One-command deployment

6. Enterprise Mode Deployment (deployment_enterprise.go)

ConfigHub → Git → Flux/Argo → Kubernetes for production compliance.

Features:

• Git repository integration
• Flux and Argo CD support
• Full audit trail
• GitOps configuration generation
• Automated sync triggering

Key Functions:

• NewEnterpriseModeDeployer() - Create enterprise deployer
• DeployUnit() - Export unit to Git and trigger sync
• DeploySpace() - Export space to Git repository
• CreateGitOpsConfig() - Generate Flux/Argo configs
• ValidateGitOpsDeployment() - Validate GitOps deployment

Base Components

Claude AI Client (claude.go)

• Simple API for sending prompts to Claude
• JSON analysis with structured responses
• Automatic response parsing and error handling
• Comprehensive timestamped logging with request/response tracking

ConfigHub Client (confighub.go)

• Full CRUD operations for units and spaces
• Type-safe API interactions with real ConfigHub APIs
• Token-based authentication
• High-level convenience helpers for common patterns
• Real space name resolution (no more mock UUIDs)

Kubernetes Utilities (kubernetes.go)

• Multi-client initialization (standard, dynamic, metrics)
• Config detection (kubeconfig, in-cluster)
• Resource helper for nested field operations
• Namespace detection

DevOps App Framework (app.go)

• Base structure for continuous DevOps applications
• Built-in health checks and metrics
• Signal handling and graceful shutdown
• Environment variable helpers
• Retry logic with exponential backoff
• Event-driven mode with RunWithInformers() for Kubernetes events

Health Server (health.go)

• Health and readiness endpoints
• Metrics endpoint
• Status tracking

Comprehensive Health Check (health_check.go)

• Complete system health validation
• Kubernetes cluster health monitoring
• ConfigHub connection verification
• Resource availability checks
• Compliance validation for ConfigHub-only commands
• Detailed error reporting and diagnostics

Helm Integration (helm.go)

• Wrap ConfigHub's native Helm support
• Install and upgrade Helm charts as ConfigHub units
• List and manage Helm releases
• Detect drift in Helm chart versions
• Validate Helm values with ConfigHub functions
• Generate upgrade commands for corrections

Package System (package.go)

• Export ConfigHub resources to distributable packages
• Load packages from local directories or remote URLs
• Clone entire environments with one command
• Backup and restore spaces with timestamps
• Publish packages to Git repositories
• Support for versioned packages

ASCII Table Rendering (tables.go)

• Unicode box-drawing tables for terminal output
• Standardized table formats for ConfigHub resources
• Color support with ANSI escape codes
• Automatic column width calculation

Available tables:

• RenderSpacesTable() - List ConfigHub spaces
• RenderUnitsTable() - Display units with optional upstream info
• RenderSetsTable() - Show configured Sets
• RenderFiltersTable() - Display Filters with WHERE clauses
• RenderActivityTable() - Show activity timeline
• RenderStateComparisonTable() - Compare desired vs actual state
• RenderEnvironmentHierarchyTable() - Show env relationships
• RenderCostAnalysisTable() - Display cost estimates
• RenderSuccessFailureTable() - Show operation results
• RenderKubectlTable() - Generic table with custom headers

Retry Logic (retry.go)

• Exponential backoff with configurable parameters
• Context-aware cancellation support
• Retryable error pattern matching
• Comprehensive logging

Key Functions:

• NewRetryableClient() - Create client with retry support
• RunWithRetry() - Execute function with automatic retries
• RetryConfig - Configure max attempts, initial delay, max delay, multiplier

Usage

Creating a New DevOps App

package main
import (
"log"
sdk "github.com/monadic/devops-examples/devops-sdk"
)
funcmain() {
config:= sdk.DevOpsAppConfig{
Name: "my-devops-app",
Version: "1.0.0",
Description: "My DevOps automation app",
RunInterval: 5*time.Minute,
HealthPort: 8080,
}
app, err:=sdk.NewDevOpsApp(config)
iferr!=nil {
log.Fatal(err)
}
// Run your main logiciferr:=app.Run(func() error {
// Your reconciliation logic herereturnprocessResources(app)
}); err!=nil {
log.Fatal(err)
}
}
funcprocessResources(app*sdk.DevOpsApp) error {
// Use the pre-initialized clientsctx:=context.Background()
pods, err:=app.K8s.Clientset.CoreV1().Pods("default").List(ctx, metav1.ListOptions{})
// Get ConfigHub units using real API with space IDspaceID:=uuid.MustParse("your-space-id")
units, err:=app.Cub.ListUnits(sdk.ListUnitsParams{
SpaceID: spaceID,
Where: "Labels.monitor = 'true'",
})
// Analyze with Claude (now with comprehensive logging)response, err:=app.Claude.Complete("Analyze this configuration and identify issues...")
returnnil
}

Using Individual Components

Claude Client (with Logging)

claude:=sdk.NewClaudeClient(apiKey)
// Enable debug logging to see full prompts/responsesclaude.EnableDebugLogging()
// Or set environment variable: CLAUDE_DEBUG_LOG=true// Simple completion with automatic loggingresponse, err:=claude.Complete("Analyze this Kubernetes configuration for issues")
// Analyze JSON data (logs request/response automatically)analysis, err:=claude.AnalyzeJSON(
"Identify drift in these deployments and suggest fixes",
driftData,
)
// Get structured response with loggingvarresultDriftAnalysiserr:=claude.AnalyzeWithStructuredResponse(
"Analyze configuration drift and return JSON with fixes",
comparisonData,
&result,
)
// Get request statisticscount, stats:=claude.GetRequestStats()
fmt.Printf("Made %d Claude API calls\n", count)

ConfigHub Client (Real API)

cub:=sdk.NewConfigHubClient(baseURL, token)
// List units using real API with filtersunits, err:=cub.ListUnits(sdk.ListUnitsParams{
SpaceID: spaceID,
Where: "Labels.tier = 'critical'",
})
// Create a unit with upstream relationshipunit, err:=cub.CreateUnit(spaceID, sdk.CreateUnitRequest{
Slug: "my-deployment",
DisplayName: "My Application Deployment",
Data: yamlContent,
UpstreamUnitID: &baseUnitID, // For inheritanceLabels: map[string]string{"tier": "critical"},
})
// Create a space with proper requestspace, err:=cub.CreateSpace(sdk.CreateSpaceRequest{
Slug: "new-space",
DisplayName: "New Environment Space",
Labels: map[string]string{"environment": "dev"},
})
// Use Sets for bulk operationsset, err:=cub.CreateSet(spaceID, sdk.CreateSetRequest{
Slug: "critical-services",
DisplayName: "Critical Services Set",
})
// Apply changes using push-upgrade patternerr=cub.BulkPatchUnits(sdk.BulkPatchParams{
SpaceID: targetSpaceID,
Where: "SetID = '"+set.SetID.String() +"'",
Patch: patchData,
Upgrade: true, // Push-upgrade to downstream
})

High-Level Convenience Helpers

// Get space by name (no more manual UUID lookups)space, err:=cub.GetSpaceBySlug("my-project-dev")
// Create space with unique prefix (like cub space new-prefix)space, fullName, err:=cub.CreateSpaceWithUniquePrefix("drift-detector",
"Drift Detector App", map[string]string{"app": "drift-detector"})
// Result: space named "prefix-1234567890-drift-detector"// Clone units with upstream relationshipsunits, err:=cub.BulkCloneUnitsWithUpstream(
sourceSpaceID, targetSpaceID,
[]string{"deployment", "service", "rbac"},
map[string]string{"environment": "staging"},
)
// Apply units in dependency ordererr=cub.ApplyUnitsInOrder(spaceID, []string{
"namespace", "rbac", "service", "deployment",
})

Helm Chart Management

// Create Helm helperhelm:=sdk.NewHelmHelper(cub, spaceID)
// Install a Helm charterr:=helm.InstallChart("my-nginx", "bitnami/nginx", sdk.HelmOptions{
Namespace: "web",
Version: "15.5.2",
Values: []string{
"service.type=LoadBalancer",
"replicaCount=3",
},
})
// List Helm releasesreleases, err:=helm.ListHelmReleases()
for_, release:=rangereleases {
fmt.Printf("Release: %s, Chart: %s v%s\n",
release.Name, release.Chart, release.Version)
}
// Check for newer versionsrelease, _:=helm.GetHelmRelease("my-nginx")
hasUpdate, newVersion, _:=helm.CompareChartVersions(release)
ifhasUpdate {
fmt.Printf("Update available: %s -> %s\n", release.Version, newVersion)
// Upgrade the charterr=helm.UpgradeChart("my-nginx", "bitnami/nginx", sdk.HelmOptions{
Version: newVersion,
UpdateCRDs: true,
})
}
// Generate correction command for driftcmd:=helm.GenerateUpgradeCommand(release, newVersion)
fmt.Printf("To fix drift, run: %s\n", cmd)

Package Management (Experimental)

// Note: Requires CONFIGHUB_EXPERIMENTAL=1 environment variablepkg:=sdk.NewPackageHelper(cub)
// Export app configuration to packageerr:=pkg.CreatePackage("./my-app-package", sdk.PackageOptions{
SpaceID: spaceID,
Where: "Labels.app='drift-detector'",
})
// Load package from local directoryerr=pkg.LoadPackage("./my-app-package", "staging")
// Load from GitHuberr=pkg.LoadPackageFromGitHub("monadic", "packages", "drift-detector", "prod")
// Clone entire environmenterr=pkg.CloneEnvironment(prodSpaceID, "staging-clone")
// Backup space with timestampbackupPath, err:=pkg.BackupSpace(spaceID, "./backups")
fmt.Printf("Backup created at: %s\n", backupPath)
// Restore from backuperr=pkg.RestoreSpace(backupPath, "restored")
// Create versioned packageerr=pkg.CreateVersionedPackage("./release", "v1.2.0", sdk.PackageOptions{
SpaceID: spaceID,
})
// Publish package to Giterr=pkg.PublishPackage("./my-app-package",
"https://github.com/myorg/packages.git",
"Release v1.2.0")

Kubernetes Helpers

// Get configured clientsk8s, err:=sdk.NewK8sClients()
// Use different client typespods, err:=k8s.Clientset.CoreV1().Pods("").List(...)
metrics, err:=k8s.MetricsClient.MetricsV1beta1().PodMetricses("").List(...)
// Resource helpershelper:=sdk.NewResourceHelper()
value:=helper.GetResourceValue(resource, "spec.replicas")
helper.SetResourceValue(resource, "spec.replicas", 5)

Environment Variables

The SDK automatically reads these environment variables:

• CLAUDE_API_KEY: Claude API key
• CLAUDE_DEBUG_LOG: Set to "true" to enable full prompt/response logging
• CUB_TOKEN: ConfigHub authentication token
• CUB_API_URL: ConfigHub API base URL
• KUBECONFIG: Path to kubeconfig file
• NAMESPACE: Default namespace for operations

Claude Logging Levels

# Standard logging: request/response previews onlyexport CLAUDE_DEBUG_LOG=false
# Debug logging: full prompts and responsesexport CLAUDE_DEBUG_LOG=true

Example log output:

[Claude] req-1 ◀ REQUEST: Analyze this Kubernetes configuration for drift...
[Claude] req-1 → Sending API request
[Claude] req-1 ▶ RESPONSE (2.1s): I found 3 configuration drift issues...

Helper Functions

Environment Variables

// Environment variables with defaultsnamespace:=sdk.GetEnvOrDefault("NAMESPACE", "default")
required:=sdk.GetEnvOrPanic("CLAUDE_API_KEY")
enabled:=sdk.GetEnvBool("AUTO_APPLY", false)
interval:=sdk.GetEnvDuration("CHECK_INTERVAL", 5*time.Minute)
port:=sdk.GetEnvInt("PORT", 8080)

Retry Logic

// Simple retry with default configerr:=sdk.RunWithRetry(ctx, 3, func() error {
returnapiCall()
})
// Advanced retry with custom configconfig:= sdk.RetryConfig{
MaxAttempts: 5,
InitialDelay: 1*time.Second,
MaxDelay: 30*time.Second,
Multiplier: 2.0,
RetryableErrors: []string{"connection refused", "timeout"},
}
client:=sdk.NewRetryableClient(config)
err:=client.Do(ctx, func() error {
returnunreliableOperation()
})

ASCII Table Rendering

// Render ConfigHub spacesspaces, _:=cub.ListSpaces()
fmt.Println(sdk.RenderSpacesTable(spaces))
// Render units with upstream relationshipsunits, _:=cub.ListUnits(sdk.ListUnitsParams{SpaceID: spaceID})
fmt.Println(sdk.RenderUnitsTable(units, true))
// Render state comparison (drift detection)resources:= []sdk.ResourceState{
{
Name: "Deployment/backend-api",
DesiredState: "replicas: 3",
ActualState: "replicas: 5",
Drift: true,
},
}
fmt.Println(sdk.RenderStateComparisonTable(resources))
// Render cost analysisestimates:= []sdk.UnitCostEstimate{
{
UnitSlug: "backend-api",
MonthlyCost: 150.00,
ResourceType: "Deployment",
},
}
fmt.Println(sdk.RenderCostAnalysisTable(estimates))

Comprehensive Health Checking

// Create health checkerhealthChecker:=sdk.NewComprehensiveHealthCheck(
k8s.Clientset,
cub,
"default",
)
// Run health checkctx:=context.Background()
result, err:=healthChecker.RunHealthCheck(ctx)
// Check resultsifresult.Status==sdk.HealthStatusHealthy {
fmt.Println("All systems operational")
} else {
fmt.Printf("Issues detected: %v\n", result.Issues)
}
// Validate ConfigHub compliancecorrections:= []string{
"cub unit update backend --patch ...",
"cub unit apply backend --space prod",
}
isCompliant:=healthChecker.CheckConfigHubCompliance(corrections)

Example Apps Using This SDK

The SDK is used by three production-ready DevOps apps in the devops-examples repository:

1. Drift Detector

Event-driven configuration drift detection with auto-correction.

Key features:

• Kubernetes informers for real-time drift detection
• ConfigHub Sets and Filters for targeting critical services
• Claude AI for root cause analysis
• Push-upgrade pattern for multi-environment fixes
• Web dashboard on :8080

Deployment:

cd devops-examples/drift-detector
bin/install-base # Create ConfigHub structure
bin/setup-worker # Install ConfigHub worker
bin/apply-base # Deploy to Kubernetes
bin/test-workflow # Validate everything works

See QUICKSTART.md for full guide.

2. Cost Optimizer

AI-powered cost optimization with OpenCost integration.

Key features:

• Real-time cost analysis from OpenCost or AWS pricing
• Claude AI cost recommendations
• Bulk optimization across environments
• Interactive web dashboard on :8081
• Metrics server integration

Deployment:

cd devops-examples/cost-optimizer
bin/install-base # Create ConfigHub structure
bin/setup-worker # Install ConfigHub worker
bin/apply-base # Deploy to Kubernetes
bin/test-workflow # Validate everything works

See QUICKSTART.md for full guide.

3. Cost Impact Monitor

Pre-deployment cost analysis with trigger-based hooks.

Key features:

• Monitors all ConfigHub spaces for cost changes
• Pre-apply warnings for high-cost deployments
• Post-apply verification and learning
• Cross-environment cost tracking
• Web dashboard on :8083

Deployment:

cd devops-examples/cost-impact-monitor
bin/install-base # Create ConfigHub structure
bin/setup-worker # Install ConfigHub worker
bin/apply-base # Deploy to Kubernetes
bin/test-workflow # Validate everything works

See QUICKSTART.md for full guide.

Common Workflow

All examples follow the same deployment pattern:

1. Create ConfigHub structure - bin/install-base creates spaces, filters, and units
2. Set up worker - bin/setup-worker installs ConfigHub worker for applies
3. Deploy to Kubernetes - bin/apply-base sets targets and applies units
4. Validate - bin/test-workflow checks everything is working

This demonstrates the ConfigHub → Worker → Kubernetes deployment workflow that replaces traditional kubectl apply with ConfigHub-managed deployments.

SDK Features

1. Pre-initialized clients for ConfigHub, Kubernetes, and Claude AI
2. Consistent error handling and logging patterns
3. Health checks, metrics, and graceful shutdown support
4. Strongly typed API clients
5. Mockable components for testing
6. Extensible architecture for additional clients and utilities