o8 module deploy

Deploy a module to the Kubernetes cluster.

Synopsis

o8 module deploy [MODULE_PATH] [OPTIONS]

Description

Deploy an Orchestr8 module to your Kubernetes cluster. Modules are self-contained application packages that include:

• Kubernetes manifests for deployment
• Configuration templates for different environments
• Dependencies and service requirements
• Documentation and usage guides

The deploy command handles the complete module deployment lifecycle including dependency resolution, environment-specific configuration, and ArgoCD integration.

Arguments

Argument	Description	Default
MODULE_PATH	Path to module directory	Current directory

Options

Option	Short	Description	Default
--environment	-e	Target environment (dev, staging, production)	LOCAL
--namespace	-n	Kubernetes namespace for deployment	From module spec
--values	-f	Path to custom values file	None
--dry-run		Validate deployment without applying	false
--wait		Wait for deployment to complete	false

Prerequisites

• kubectl - Kubernetes management
• Orchestr8 platform already deployed (o8 setup)
• Valid module specification in target directory

Module Structure

Modules must contain a valid Orchestr8 specification file:

my-module/
├── .o8/
│   └── module.yaml          # Module specification (preferred)
├── o8-module.yaml          # Alternative location
├── manifests/              # Kubernetes YAML files
├── config/                 # Environment configurations
└── docs/                   # Module documentation

Examples

Basic Deployment

# Deploy current directory module to development
o8 module deploy

# Deploy specific module to production
o8 module deploy ./my-app --environment production

Advanced Deployment

# Deploy with custom values file
o8 module deploy ./my-app \
  --environment production \
  --values ./production-values.yaml

# Validate deployment without applying
o8 module deploy ./my-app --dry-run

# Deploy and wait for completion
o8 module deploy ./my-app --environment staging --wait

Environment-Specific Deployment

# Development deployment
o8 module deploy ./langfuse --environment dev

# Staging with increased resources
o8 module deploy ./langfuse --environment staging  

# Production with high availability
o8 module deploy ./langfuse --environment production

Module Specification

The module specification (module.yaml) defines deployment behavior:

apiVersion: orchestr8.io/v1
kind: ModuleSpec
metadata:
  name: my-application
  version: "1.0.0"
  description: "Example application module"
spec:
  module:
    name: my-application
    version: "1.0.0"
    tier: application
  
  deployment:
    type: kubernetes
    strategy: rolling-update
    
  dependencies:
    - name: postgresql
      version: ">=13.0.0"
      
  environments:
    - name: development
      replicas: 1
      resources:
        requests:
          memory: "256Mi"
          cpu: "250m"
    - name: production  
      replicas: 3
      resources:
        requests:
          memory: "512Mi"
          cpu: "500m"
          
  networking:
    expose: true
    ports:
      - name: http
        port: 8080
        protocol: TCP
        
  storage:
    - name: data
      size: "10Gi"  
      accessMode: ReadWriteOnce

Deployment Process

1. Validation Phase

• Validates module specification format
• Checks for required files and directories
• Verifies environment configuration exists

2. Dependency Resolution

• Resolves module dependencies
• Ensures required services are available
• Creates dependency order for deployment

3. Configuration Generation

• Applies environment-specific overrides
• Generates Kubernetes manifests
• Merges custom values if provided

4. ArgoCD Integration

• Creates ArgoCD Application resource
• Configures GitOps synchronization
• Sets up monitoring and health checks

5. Deployment Execution

• Applies manifests to cluster
• Creates namespace if needed
• Monitors deployment progress

Environment Configuration

Built-in Environments

Environment	Typical Use	Resource Profile
LOCAL	Local development	Minimal resources, single replica
dev	Development testing	Low resources, debugging enabled
staging	Pre-production validation	Production-like, reduced scale
production	Live workloads	High availability, full resources

Custom Environment Values

Override default values with custom configuration:

# custom-values.yaml
replicas: 5
image:
  tag: "v2.1.0"
resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "1"
ingress:
  enabled: true
  host: myapp.example.com

Output

Successful Deployment

🚀 Deploying module: my-application
   Environment: production
   Namespace: my-application
   Version: 1.0.0

✅ Module validation passed
📦 Resolving dependencies...
   ✅ postgresql (v13.5.0) - satisfied
   
🔧 Generating configuration...
   ✅ Environment config applied
   ✅ Custom values merged
   
⚙️  Creating ArgoCD application...
   ✅ Application created: my-application
   ✅ Sync policy configured
   
🎯 Deployment initiated successfully!
   
📊 Status: o8 module status my-application
🌐 Access: https://my-application.platform.example.com

Dry Run Output

🔍 Dry run mode - no changes will be applied

📋 Deployment Plan:
   Module: my-application v1.0.0
   Environment: production
   Namespace: my-application
   Replicas: 3
   
📦 Dependencies:
   ✅ postgresql v13.5.0
   
🔧 Resources to create:
   - Deployment: my-application
   - Service: my-application  
   - Ingress: my-application
   - ConfigMap: my-application-config
   - Secret: my-application-secrets
   
✅ Validation successful - ready for deployment

Troubleshooting

Module Validation Errors

# Check module specification
o8 module validate ./my-app

# View detailed validation errors
o8 module validate ./my-app --verbose

Dependency Issues

# List available modules
o8 module list

# Check module status  
o8 module status postgresql

# Deploy missing dependencies first
o8 module deploy ./postgresql --environment production

Deployment Failures

# Check ArgoCD application status
o8 apps

# View detailed application info
kubectl get application my-application -n argocd -o yaml

# Check pod status in target namespace
kubectl get pods -n my-application
kubectl describe pod <pod-name> -n my-application

Configuration Issues

# Validate custom values file
helm template ./my-app --values custom-values.yaml

# Check generated manifests
o8 module deploy ./my-app --dry-run --environment production

Exit Codes

Code	Description
0	Module deployed successfully
1	General deployment error
2	Module validation failed
3	Dependency resolution failed
4	Kubernetes API error

Related Commands

• o8 module validate - Validate module specification
• o8 module status - Check deployment status
• o8 module list - List available modules
• o8 sync - Manually sync ArgoCD application