Deploy Svc

The Deploy Svc is a container orchestration service that automates the deployment, scaling, and management of containerized services across 1Backend infrastructure.

This page provides a comprehensive overview of Deploy Svc. For detailed API information, refer to the Deploy Svc API documentation.

Architecture & Purpose

Deploy Svc serves as the orchestration layer that bridges service definitions and running containers:

Status Warning

🚧 Deployment capabilities are currently in development. This documentation is for contributors and advanced users. For production use, deploy services manually for now.

CLI Usage

Deploy Svc provides comprehensive CLI commands for managing deployments:

Saving Deployments

# Save a deployment from YAML file
oo deployment save ./my-deployment.yaml

# Using aliases
oo depl s ./my-deployment.yaml
oo deployments save ./my-deployment.yaml

Deployment File Structure

Deployment files should be in YAML format with the following structure:

id: "depl_myservice123"
definitionId: "def_myservice456"  # Links to Registry Svc Definition
name: "user-service-v2"
description: "Handles user service requests"
replicas: 3
strategy:
  type: "RollingUpdate"
  maxUnavailable: 1
  maxSurge: 2
resources:
  cpu: "500m"       # 0.5 CPU cores
  memory: "256Mi"   # 256 MB RAM
  vram: "24GB"      # GPU memory (optional)
autoScaling:
  minReplicas: 2
  maxReplicas: 10
  cpuThreshold: 80  # Scale up at 80% CPU
targetRegions:
  - cluster: "us-west1"
    zone: "us-west1-b"
  - cluster: "local-docker"
envars:
  ENVIRONMENT: "production"
  LOG_LEVEL: "debug"
  FEATURE_FLAG_X: "true"
  DATABASE_URL: "postgres://localhost:5432/mydb"

Minimal Deployment Example

id: "depl_simple123"
definitionId: "def_myapp456"
replicas: 1

Listing Deployments

# List all deployments
oo deployment list

# List with full details (no truncation)
oo deployment list --full

# Using aliases
oo depl ls
oo deployments list --full

Example output:

ID                DEFINITION ID    STATUS      DETAILS
depl_dbOdi5eLQK   test-a           OK          
depl_dy2PDIkzqf   test-b           Error       build failed: COPY failed: file not found...
depl_user123      def_user456      Deploying   Starting container instances...

Deleting Deployments

# Delete a deployment by ID
oo deployment remove depl_myservice123

# Using aliases
oo depl rm depl_myservice123
oo deployments remove depl_myservice123

Deployment Lifecycle

Deployment States

Deploy Svc manages deployments through several states:

stateDiagram-v2
    [*] --> Pending
    Pending --> Deploying
    Deploying --> OK
    Deploying --> Error
    Error --> Deploying
    OK --> Deploying
    Deploying --> Failed
    Failed --> [*]
    OK --> [*]

Pending: Deployment created but not yet started
Deploying: Actively launching or updating containers
OK: All replicas running successfully
Error: Deployment failed but retryable
Failed: Deployment permanently failed

Deploy Loop Operation

The Deploy Svc runs a continuous reconciliation loop:

State Assessment: Compare desired vs actual deployments
Command Generation: Create start/stop/scale commands
Node Allocation: Distribute workloads across available nodes
Container Management: Execute commands via Container Svc
Registry Updates: Register instances with Registry Svc
Health Monitoring: Track instance health and restart if needed

Scaling & Resource Management

Replica Management

# Basic scaling
replicas: 5

# Auto-scaling configuration
autoScaling:
  minReplicas: 2
  maxReplicas: 20
  cpuThreshold: 75  # Scale up when average CPU > 75%

Resource Allocation

resources:
  cpu: "2"          # 2 CPU cores
  memory: "4Gi"     # 4 GB RAM
  vram: "48GB"      # GPU memory for AI workloads

Resource Format Examples

# CPU formats
cpu: "500m"      # 0.5 cores (millicores)
cpu: "1"         # 1 core
cpu: "2.5"       # 2.5 cores

# Memory formats
memory: "128Mi"  # 128 mebibytes
memory: "1Gi"    # 1 gibibyte
memory: "512M"   # 512 megabytes

# GPU VRAM (for AI workloads)
vram: "24GB"     # 24 GB GPU memory
vram: "48GB"     # High-memory GPU

Deployment Strategies

Rolling Update (Default)

strategy:
  type: "RollingUpdate"
  maxUnavailable: 1     # Max instances down during update
  maxSurge: 2          # Max extra instances during update

Rolling updates ensure zero-downtime deployments by:

Starting new instances alongside old ones
Gradually shifting traffic to new instances
Removing old instances once new ones are healthy

Recreate Strategy

strategy:
  type: "Recreate"

Recreate strategy stops all instances before starting new ones:

Simpler but causes downtime
Useful for stateful services requiring exclusive access
Faster for development environments

Real-World Usage Examples

1. Web Application Deployment

id: "depl_webapp_prod"
definitionId: "def_webapp_v2"
name: "webapp-production"
description: "Production web application"
replicas: 5
strategy:
  type: "RollingUpdate"
  maxUnavailable: 1
  maxSurge: 2
resources:
  cpu: "1"
  memory: "512Mi"
autoScaling:
  minReplicas: 3
  maxReplicas: 15
  cpuThreshold: 70
targetRegions:
  - cluster: "us-east1"
  - cluster: "us-west1"
envars:
  NODE_ENV: "production"
  DATABASE_URL: "postgres://prod-db:5432/webapp"
  REDIS_URL: "redis://prod-cache:6379"
  LOG_LEVEL: "info"

2. AI Model Service

id: "depl_ai_model"
definitionId: "def_llama_70b"
name: "llama-70b-service"
description: "Large language model inference service"
replicas: 2
resources:
  cpu: "8"
  memory: "32Gi"
  vram: "80GB"    # High-end GPU requirement
autoScaling:
  minReplicas: 1
  maxReplicas: 4
  cpuThreshold: 85
targetRegions:
  - cluster: "gpu-cluster-a100"
    zone: "gpu-zone-1"
envars:
  MODEL_NAME: "llama-70b"
  BATCH_SIZE: "4"
  MAX_TOKENS: "4096"
  GPU_MEMORY_FRACTION: "0.95"

3. Microservice with Database

id: "depl_user_service"
definitionId: "def_user_api"
name: "user-service"
description: "User management microservice"
replicas: 3
strategy:
  type: "RollingUpdate"
  maxUnavailable: 0    # Zero downtime
  maxSurge: 1
resources:
  cpu: "500m"
  memory: "256Mi"
autoScaling:
  minReplicas: 2
  maxReplicas: 8
  cpuThreshold: 75
envars:
  DATABASE_HOST: "user-db.internal"
  DATABASE_PORT: "5432"
  DATABASE_NAME: "users"
  JWT_SECRET: "{{secret:jwt-secret}}"
  REDIS_URL: "redis://user-cache:6379"

4. Development Environment

id: "depl_dev_api"
definitionId: "def_api_dev"
name: "api-development"
description: "Development API server"
replicas: 1          # Single instance for dev
strategy:
  type: "Recreate"   # Simpler for development
resources:
  cpu: "250m"        # Minimal resources
  memory: "128Mi"
envars:
  NODE_ENV: "development"
  DEBUG: "true"
  HOT_RELOAD: "true"
  LOG_LEVEL: "debug"

Node Allocation & Targeting

Cluster Targeting

targetRegions:
  - cluster: "production-cluster"
    zone: "zone-a"
  - cluster: "gpu-cluster"      # For GPU workloads
  - cluster: "local-docker"     # For local development

Allocation Algorithm

The Deploy Svc allocator considers:

Node Capacity: CPU, memory, and GPU availability
Resource Requirements: Deployment resource needs
Load Distribution: Balanced workload distribution
Affinity Rules: Cluster and zone preferences
Health Status: Only healthy nodes receive workloads

Integration with Other Services

Registry Svc Integration

Deploy Svc works closely with Registry Svc:

sequenceDiagram
    participant DS as Deploy Svc
    participant RS as Registry Svc
    participant CS as Container Svc
    participant Node as Node
    
    DS->>RS: List available nodes
    DS->>RS: Get service definitions
    DS->>CS: Start container on node
    CS->>Node: Launch container
    DS->>RS: Register service instance
    RS-->>DS: Instance registered

Container Svc Integration

Deploy Svc orchestrates containers via Container Svc:

Container Lifecycle: Start, stop, and restart containers
Image Management: Build images from repositories
Port Mapping: Configure network access
Volume Mounting: Handle persistent storage

Definition Dependency

Deployments reference Service Definitions from Registry Svc:

# First, create a definition
oo definition save ./my-service-def.yaml

# Then, deploy it
oo deployment save ./my-deployment.yaml

Environment Variables & Configuration

Static Configuration

envars:
  NODE_ENV: "production"
  LOG_LEVEL: "info"
  API_TIMEOUT: "30s"
  MAX_CONNECTIONS: "100"

Dynamic Configuration

envars:
  # Reference secrets (when Secret Svc integration available)
  DATABASE_PASSWORD: "{{secret:db-password}}"
  API_KEY: "{{secret:external-api-key}}"
  
  # Environment-specific values
  ENVIRONMENT: "{{env:DEPLOY_ENV}}"
  BUILD_VERSION: "{{env:BUILD_NUMBER}}"

Monitoring & Observability

Deployment Status Monitoring

# Watch deployment progress
oo deployment list --full

# Check specific deployment
oo deployment list | grep depl_myservice123

Health Check Integration

Deploy Svc monitors service health through:

Container Health: Container runtime status
Service Heartbeats: Regular health check responses
Resource Usage: CPU, memory, and GPU utilization
Network Connectivity: Service reachability

Automatic Recovery

When services fail, Deploy Svc automatically:

Detects Failures: Via health checks and heartbeats
Generates Commands: Create restart/replace commands
Allocates Resources: Find available nodes
Restarts Services: Launch replacement containers
Updates Registry: Register new instances

Performance Optimization

Resource Efficiency

# Optimize resource allocation
resources:
  cpu: "500m"        # Right-size CPU allocation
  memory: "256Mi"    # Prevent memory waste
  
# Configure appropriate scaling
autoScaling:
  minReplicas: 2     # Maintain minimum availability
  maxReplicas: 8     # Cap maximum resources
  cpuThreshold: 70   # Scale before hitting limits

Deployment Speed

# Fast deployment strategy
strategy:
  type: "RollingUpdate"
  maxUnavailable: 0   # Zero downtime
  maxSurge: 3         # Parallel deployments

Troubleshooting

Common Issues

Deployment Stuck in "Deploying"

# Check node availability
oo node list

# Verify definition exists
oo definition list

# Check container logs
oo get /container-svc/container/summary?name=my-service

"Error" Status with Build Failures

# Check definition for correct paths
cat my-definition.yaml

# Verify repository access
oo get /source-svc/checkout --url="https://github.com/user/repo.git"

Resource Allocation Failures

# Reduce resource requirements
resources:
  cpu: "250m"      # Reduced from "1"
  memory: "128Mi"  # Reduced from "512Mi"

Debug Commands

# List all nodes and their capacity
oo node list

# Check instance health
oo instance list

# View deployment details
oo deployment list --full

API Reference Summary

Endpoint	Method	Purpose
`/deploy-svc/deployment`	PUT	Save/update deployment
`/deploy-svc/deployments`	POST	List deployments
`/deploy-svc/deployment`	DELETE	Delete deployment

Registry Svc: Service definitions and instance registry
Container Svc: Container runtime management
Config Svc: Configuration management
Secret Svc: Secure configuration storage

Roadmap & Future Features

The Deploy Svc is actively evolving with planned features:

Near-term Enhancements

Blue-Green Deployments: Zero-downtime deployment strategy
Canary Releases: Gradual traffic shifting
Resource Quotas: Per-service resource limits
Health Check Configuration: Custom health check endpoints

Long-term Vision

Multi-Cloud Support: Deploy across cloud providers
Advanced Scheduling: Affinity and anti-affinity rules
Persistent Volumes: Stateful service support
Service Mesh Integration: Advanced networking features

For production deployments, monitor the project roadmap and consider manual deployment approaches until Deploy Svc reaches production readiness.

Architecture & Purpose​

Status Warning​

CLI Usage​

Saving Deployments​

Deployment File Structure​

Minimal Deployment Example​

Listing Deployments​

Deleting Deployments​

Deployment Lifecycle​

Deployment States​

Deploy Loop Operation​

Scaling & Resource Management​

Replica Management​

Resource Allocation​

Resource Format Examples​

Deployment Strategies​

Rolling Update (Default)​

Recreate Strategy​

Real-World Usage Examples​

1. Web Application Deployment​

2. AI Model Service​

3. Microservice with Database​

4. Development Environment​

Node Allocation & Targeting​

Cluster Targeting​

Allocation Algorithm​

Integration with Other Services​

Registry Svc Integration​

Container Svc Integration​

Definition Dependency​

Environment Variables & Configuration​

Static Configuration​

Dynamic Configuration​

Monitoring & Observability​

Deployment Status Monitoring​

Health Check Integration​

Automatic Recovery​

Performance Optimization​

Resource Efficiency​

Deployment Speed​

Troubleshooting​

Common Issues​

Deployment Stuck in "Deploying"​

"Error" Status with Build Failures​

Resource Allocation Failures​

Debug Commands​

API Reference Summary​

Related Services​

Roadmap & Future Features​

Near-term Enhancements​

Long-term Vision​