Skip to main content

Module System

Orchestr8's module system provides a standardized way to package, deploy, and manage applications in Kubernetes environments. Each module represents a self-contained application or service with its own configuration, dependencies, and lifecycle.

What is a Module?​

An Orchestr8 module is a deployable unit that contains:

  • Application Code: Container images and runtime configuration
  • Kubernetes Manifests: Deployment, Service, ConfigMap, etc.
  • Helm Charts: Templated configurations for different environments
  • Security Policies: RBAC, Network Policies, Pod Security Standards
  • Monitoring Config: Prometheus metrics, Grafana dashboards, alerts

Module Structure​

my-service/
├── o8-module.yaml           # Module specification
├── charts/                  # Helm chart
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
├── config/                  # Configuration files
│   ├── rbac.yaml
│   ├── network-policy.yaml
│   └── monitoring.yaml
├── environments/            # Environment-specific values
│   ├── dev.yaml
│   ├── staging.yaml
│   └── production.yaml
└── argocd-app.yaml         # ArgoCD Application definition

Module Specification​

Each module includes an o8-module.yaml specification file:

apiVersion: orchestr8.io/v1
kind: Module
metadata:
  name: my-service
  version: "1.0.0"
  description: "Example microservice with API and database"

spec:
  # Module metadata
  team: platform-team
  owner: john.doe@company.com
  category: backend-service
  
  # Dependencies
  dependencies:
    - postgresql
    - redis
    - monitoring-stack
  
  # Security requirements
  security:
    podSecurityStandard: restricted
    networkIsolation: true
    secretsManager: external-secrets
  
  # Resource requirements
  resources:
    requests:
      memory: "256Mi"
      cpu: "100m"
    limits:
      memory: "512Mi"
      cpu: "500m"
  
  # Networking
  networking:
    ports:
      - name: http
        port: 8080
        protocol: TCP
    ingress:
      enabled: true
      host: my-service.example.com
  
  # Monitoring
  monitoring:
    metrics: true
    healthChecks:
      liveness: /health/live
      readiness: /health/ready
    alerts:
      - name: HighErrorRate
        condition: error_rate > 5%
        severity: warning

Module Lifecycle​

1. Development​

# Initialize new module
o8 module init my-service --template microservice

# Validate module structure
o8 module validate ./my-service

# Test locally
o8 module test ./my-service --environment local

2. Deployment​

# Deploy to development
o8 module deploy ./my-service --environment dev

# Promote to staging
o8 module promote my-service --from dev --to staging

# Production deployment (with approval)
o8 module deploy ./my-service --environment prod --approve

3. Management​

# Check status
o8 module status my-service --environment prod

# Scale module
o8 module scale my-service --replicas 3

# View logs
o8 module logs my-service --environment prod --tail 100

Security Model​

Namespace Isolation​

Each module deploys to its own dedicated namespace:

apiVersion: v1
kind: Namespace
metadata:
  name: my-service
  labels:
    orchestr8.io/module: my-service
    orchestr8.io/team: platform-team

Network Policies​

Modules are isolated by default with explicit allow rules:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: my-service-network-policy
  namespace: my-service
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # Allow traffic from ingress controllers
    - from:
        - namespaceSelector:
            matchLabels:
              name: istio-system
  egress:
    # Allow DNS resolution
    - to: []
      ports:
        - protocol: UDP
          port: 53
    # Allow communication with dependencies
    - to:
        - namespaceSelector:
            matchLabels:
              orchestr8.io/module: postgresql

RBAC Configuration​

Service accounts with minimal required permissions:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-service
  namespace: my-service
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: my-service
  namespace: my-service
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["get", "list"]

Environment Management​

Environment-Specific Configuration​

Each environment can override default values:

# environments/production.yaml
replicaCount: 3

resources:
  limits:
    memory: "1Gi"
    cpu: "1000m"

ingress:
  host: my-service.company.com
  tls:
    enabled: true
    secretName: my-service-tls

monitoring:
  alerts:
    - name: HighLatency
      condition: p95_latency > 500ms
      severity: critical

Promotion Pipeline​

Modules progress through environments with validation:

Dependency Management​

Declaring Dependencies​

Modules can declare dependencies on other modules:

spec:
  dependencies:
    - name: postgresql
      version: ">=12.0.0"
      namespace: postgresql
    - name: redis
      version: "^6.0"
      optional: true

Dependency Resolution​

Orchestr8 ensures dependencies are deployed first:

# Install module with dependencies
o8 module deploy ./my-service --with-dependencies

# Check dependency graph
o8 module deps my-service --visualize

Module Templates​

Built-in Templates​

Orchestr8 provides templates for common patterns:

# Microservice with REST API
o8 module init api-service --template microservice

# Frontend application
o8 module init web-app --template frontend

# Background worker
o8 module init worker --template job

# Database with backup
o8 module init database --template database

Custom Templates​

Organizations can create custom templates:

# templates/company-api/o8-module.yaml
apiVersion: orchestr8.io/v1
kind: ModuleTemplate
metadata:
  name: company-api
spec:
  variables:
    - name: service_name
      description: "Name of the API service"
      required: true
    - name: database_required
      description: "Whether service needs database"
      default: true
      type: boolean
  
  files:
    - source: "templates/deployment.yaml"
      target: "charts/templates/deployment.yaml"
    - source: "templates/service.yaml"
      target: "charts/templates/service.yaml"

Monitoring and Observability​

Automatic Instrumentation​

Modules automatically get monitoring capabilities:

# Auto-generated ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-service
spec:
  selector:
    matchLabels:
      app: my-service
  endpoints:
    - port: metrics
      path: /metrics

Health Checks​

Built-in health check configuration:

# Kubernetes probe configuration
livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

Best Practices​

Module Design​

  1. Single Responsibility: Each module should have one clear purpose
  2. Stateless Design: Prefer stateless applications where possible
  3. Configuration Management: Use environment variables and ConfigMaps
  4. Health Endpoints: Always implement health check endpoints

Security​

  1. Least Privilege: Request minimum required permissions
  2. Secret Management: Use External Secrets or SealedSecrets
  3. Network Isolation: Define explicit network policies
  4. Container Security: Use distroless or minimal base images

Performance​

  1. Resource Requests: Always define resource requests and limits
  2. Horizontal Scaling: Design for horizontal pod autoscaling
  3. Caching: Implement appropriate caching strategies
  4. Database Connections: Use connection pooling

Operations​

  1. Logging: Use structured logging (JSON format)
  2. Metrics: Expose Prometheus metrics
  3. Tracing: Implement distributed tracing
  4. Documentation: Keep module documentation up to date

Next Steps​