@deftai/directive-content 0.55.0

package/deployments/agentuity/via-vpc.md

@@ -0,0 +1,607 @@
+# Deploy via Private VPC / On-Premises
+
+Deploy Agentuity agents to your own infrastructure for maximum control, security, and compliance. Run in your private cloud, VPC, or on-premises data center with the same Agentuity developer experience.
+
+## Overview
+
+Agentuity supports deployment to:
+- **Private VPC**: AWS VPC, Azure VNet, GCP VPC
+- **On-Premises**: Your own data centers
+- **Hybrid**: Mix of cloud and on-prem
+- **Air-Gapped**: Completely disconnected environments
+
+All using the same SDK, same CLI, same developer experience as Agentuity Cloud.
+
+## Use Cases
+
+- **Enterprise Security**: Keep data within your security perimeter
+- **Regulatory Compliance**: Meet data residency requirements (GDPR, HIPAA, SOC 2)
+- **Data Sovereignty**: Ensure data never leaves specific geographic regions
+- **Hybrid Architecture**: Connect cloud agents with on-prem data sources
+- **Air-Gapped Environments**: Deploy in disconnected networks
+
+## Prerequisites
+
+### Infrastructure Requirements
+
+- **Kubernetes Cluster**: K8s 1.24+ (EKS, AKS, GKE, or self-hosted)
+- **Container Registry**: Private registry for agent images
+- **Load Balancer**: For ingress traffic
+- **Storage**: Persistent storage for agent state
+- **Networking**: VPN or Direct Connect (for hybrid)
+
+### Software Requirements
+
+- `kubectl` configured for your cluster
+- `helm` 3.0+ for chart installation
+- Agentuity CLI installed
+- Docker or container runtime
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         Your VPC / Data Center          │
+│                                         │
+│  ┌──────────────────────────────────┐  │
+│  │   Agentuity Control Plane         │  │
+│  │   (Agent Management, Monitoring)  │  │
+│  └──────────────────────────────────┘  │
+│                 │                        │
+│  ┌──────────────┴──────────────────┐   │
+│  │   Agent Runtime Cluster          │   │
+│  │  ┌─────┐  ┌─────┐  ┌─────┐      │   │
+│  │  │Agent│  │Agent│  │Agent│      │   │
+│  │  │  1  │  │  2  │  │  3  │      │   │
+│  │  └─────┘  └─────┘  └─────┘      │   │
+│  └──────────────────────────────────┘  │
+│                 │                        │
+│  ┌──────────────┴──────────────────┐   │
+│  │   Built-in Services              │   │
+│  │   (Storage, DB, Queue)           │   │
+│  └──────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+         │
+         ▼
+  Agentuity Console
+  (Optional, for monitoring)
+```
+
+## Deployment Methods
+
+### Method 1: Helm Chart (Recommended)
+
+#### 1. Add Agentuity Helm Repository
+
+```bash
+helm repo add agentuity https://charts.agentuity.com
+helm repo update
+```
+
+#### 2. Create Values File
+
+```yaml
+# agentuity-values.yaml
+
+# Deployment mode
+mode: vpc  # or 'on-prem', 'hybrid'
+
+# Cluster configuration
+cluster:
+  name: my-agentuity-cluster
+  region: us-east-1  # For VPC deployments
+
+# Agent runtime
+runtime:
+  replicas: 3
+  resources:
+    requests:
+      memory: "2Gi"
+      cpu: "1"
+    limits:
+      memory: "4Gi"
+      cpu: "2"
+
+# Storage configuration
+storage:
+  type: persistent  # or 's3', 'azure-blob', 'gcs'
+  size: 100Gi
+  storageClass: fast-ssd
+
+# Database
+database:
+  type: postgres
+  host: your-postgres.internal
+  port: 5432
+  database: agentuity
+  # Credentials via secrets
+
+# Networking
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - agents.yourcompany.internal
+  tls:
+    enabled: true
+    secretName: agentuity-tls
+
+# Security
+security:
+  networkPolicy:
+    enabled: true
+  podSecurityPolicy:
+    enabled: true
+  rbac:
+    enabled: true
+
+# Monitoring
+monitoring:
+  prometheus:
+    enabled: true
+  grafana:
+    enabled: true
+
+# Agentuity Console connection (optional)
+console:
+  enabled: false  # Set true to connect to Agentuity Console
+  endpoint: https://console.agentuity.com
+  apiKey: ${AGENTUITY_API_KEY}
+```
+
+#### 3. Install Agentuity
+
+```bash
+# Create namespace
+kubectl create namespace agentuity
+
+# Install with Helm
+helm install agentuity agentuity/agentuity \
+  --namespace agentuity \
+  --values agentuity-values.yaml
+
+# Check installation
+kubectl get pods -n agentuity
+```
+
+### Method 2: Terraform
+
+```hcl
+# main.tf
+
+module "agentuity_vpc" {
+  source = "agentuity/vpc-deployment/aws"
+  version = "1.0.0"
+
+  cluster_name = "agentuity-prod"
+  vpc_id = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+  
+  instance_type = "m5.xlarge"
+  min_size = 3
+  max_size = 10
+
+  database_config = {
+    engine = "postgres"
+    instance_class = "db.r5.large"
+    allocated_storage = 100
+  }
+
+  storage_config = {
+    type = "ebs"
+    size = 500
+    iops = 3000
+  }
+
+  tags = {
+    Environment = "production"
+    ManagedBy = "terraform"
+  }
+}
+```
+
+```bash
+terraform init
+terraform plan
+terraform apply
+```
+
+### Method 3: Docker Compose (Development/Single Node)
+
+```yaml
+# docker-compose.yml
+
+version: '3.8'
+
+services:
+  agentuity-runtime:
+    image: agentuity/runtime:latest
+    ports:
+      - "3500:3500"
+    environment:
+      - AGENTUITY_MODE=on-prem
+      - DATABASE_URL=postgres://user:pass@postgres:5432/agentuity
+      - REDIS_URL=redis://redis:6379
+    volumes:
+      - ./agents:/app/agents
+      - agent-data:/data
+    depends_on:
+      - postgres
+      - redis
+
+  postgres:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: agentuity
+      POSTGRES_USER: agentuity
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+
+volumes:
+  agent-data:
+  postgres-data:
+  redis-data:
+```
+
+```bash
+docker-compose up -d
+```
+
+## Configuration
+
+### Network Configuration
+
+#### VPC Peering (AWS)
+
+```bash
+# Create VPC peering connection
+aws ec2 create-vpc-peering-connection \
+  --vpc-id vpc-agentuity \
+  --peer-vpc-id vpc-production
+
+# Update route tables
+aws ec2 create-route \
+  --route-table-id rtb-agentuity \
+  --destination-cidr-block 10.0.0.0/16 \
+  --vpc-peering-connection-id pcx-xxxxx
+```
+
+#### Private Link (AWS)
+
+```yaml
+# VPC Endpoint Service
+privateLink:
+  enabled: true
+  serviceId: vpce-svc-xxxxx
+  allowedPrincipals:
+    - arn:aws:iam::123456789:root
+```
+
+#### VPN Configuration (On-Prem)
+
+```bash
+# Configure site-to-site VPN
+# Connect on-prem network to Agentuity cluster
+# Ensure proper routing for agent traffic
+```
+
+### Security Configuration
+
+#### Network Policies
+
+```yaml
+# network-policy.yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: agentuity-agent-policy
+  namespace: agentuity
+spec:
+  podSelector:
+    matchLabels:
+      app: agentuity-agent
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+      - podSelector:
+          matchLabels:
+            app: agentuity-gateway
+      ports:
+        - protocol: TCP
+          port: 8080
+  egress:
+    - to:
+      - podSelector:
+          matchLabels:
+            app: postgres
+      ports:
+        - protocol: TCP
+          port: 5432
+```
+
+#### Service Mesh (Optional)
+
+```bash
+# Install Istio for advanced traffic management
+istioctl install --set profile=default
+
+# Enable for Agentuity namespace
+kubectl label namespace agentuity istio-injection=enabled
+```
+
+### Storage Configuration
+
+#### Persistent Volumes
+
+```yaml
+# pv.yaml
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: agentuity-agent-storage
+spec:
+  capacity:
+    storage: 100Gi
+  accessModes:
+    - ReadWriteMany
+  persistentVolumeReclaimPolicy: Retain
+  storageClassName: fast-ssd
+  nfs:
+    server: nfs.internal.company.com
+    path: /exports/agentuity
+```
+
+## Agent Deployment
+
+### Deploy Agent to VPC
+
+```bash
+# Configure CLI for VPC deployment
+agentuity config set endpoint https://agents.yourcompany.internal
+agentuity config set mode vpc
+
+# Deploy agent
+cd my-agent
+agentuity deploy --target vpc
+
+# Agent deploys to your VPC cluster
+```
+
+### Multi-Environment
+
+```bash
+# Configure multiple environments
+agentuity config add-context production \
+  --endpoint https://agents-prod.internal \
+  --mode vpc
+
+agentuity config add-context staging \
+  --endpoint https://agents-staging.internal \
+  --mode vpc
+
+# Switch contexts
+agentuity config use-context production
+
+# Deploy
+agentuity deploy
+```
+
+## Hybrid Deployment
+
+### Cloud Control Plane + VPC Agents
+
+```yaml
+# agentuity.yaml
+mode: hybrid
+
+# Control plane in Agentuity Cloud
+controlPlane:
+  type: cloud
+  endpoint: https://console.agentuity.com
+
+# Agents run in your VPC
+agentRuntime:
+  type: vpc
+  cluster: arn:aws:eks:us-east-1:123456789:cluster/agentuity
+  
+# Secure tunnel for communication
+tunnel:
+  type: wireguard
+  endpoint: vpn.yourcompany.com
+```
+
+### Agent-to-Agent Communication
+
+```typescript
+// Agents in VPC can call agents in Cloud
+import { createAgent } from '@agentuity/runtime';
+
+const vpcAgent = createAgent('vpc-agent', {
+  handler: async (ctx) => {
+    // Call cloud-hosted agent
+    const result = await ctx.callAgent('cloud-agent', {
+      data: 'sensitive data stays in VPC'
+    });
+    return result;
+  }
+});
+```
+
+## Monitoring & Operations
+
+### Observability
+
+```yaml
+# Enable observability stack
+monitoring:
+  prometheus:
+    enabled: true
+    retention: 30d
+    
+  grafana:
+    enabled: true
+    dashboards:
+      - agentuity-agents
+      - agentuity-infrastructure
+      
+  loki:
+    enabled: true  # Log aggregation
+    
+  tempo:
+    enabled: true  # Distributed tracing
+```
+
+### Alerts
+
+```yaml
+# alerts.yaml
+groups:
+  - name: agentuity-agents
+    rules:
+      - alert: HighAgentErrorRate
+        expr: rate(agent_errors[5m]) > 0.05
+        annotations:
+          summary: "High error rate for {{ $labels.agent }}"
+          
+      - alert: AgentDown
+        expr: up{job="agentuity-agent"} == 0
+        for: 1m
+        annotations:
+          summary: "Agent {{ $labels.instance }} is down"
+```
+
+### Backup & Disaster Recovery
+
+```bash
+# Backup agent state
+kubectl exec -n agentuity agentuity-0 -- \
+  /opt/agentuity/bin/backup create
+
+# Schedule automatic backups
+kubectl apply -f - <<EOF
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: agentuity-backup
+spec:
+  schedule: "0 2 * * *"  # Daily at 2 AM
+  jobTemplate:
+    spec:
+      template:
+        spec:
+          containers:
+          - name: backup
+            image: agentuity/backup:latest
+            args: ["--target", "s3://backups/agentuity"]
+EOF
+```
+
+## Compliance & Security
+
+### Data Residency
+
+```yaml
+# Ensure data stays in specific region
+dataResidency:
+  region: eu-west-1
+  enforceStrict: true
+  allowedRegions:
+    - eu-west-1
+    - eu-central-1
+```
+
+### Encryption
+
+```yaml
+# Enable encryption at rest
+encryption:
+  atRest:
+    enabled: true
+    provider: aws-kms  # or azure-keyvault, google-kms
+    keyId: arn:aws:kms:...
+    
+  inTransit:
+    enabled: true
+    minTLSVersion: "1.3"
+```
+
+### Audit Logging
+
+```yaml
+# Enable comprehensive audit logs
+auditLog:
+  enabled: true
+  destination: s3://audit-logs/agentuity
+  events:
+    - agent_deploy
+    - agent_invoke
+    - config_change
+    - secret_access
+```
+
+## Troubleshooting
+
+### Agent Won't Deploy
+
+```bash
+# Check cluster connectivity
+kubectl cluster-info
+
+# Verify Agentuity pods
+kubectl get pods -n agentuity
+
+# Check logs
+kubectl logs -n agentuity deployment/agentuity-runtime
+
+# Test network connectivity
+kubectl run -it --rm debug --image=busybox --restart=Never -- \
+  wget -O- http://agentuity-runtime:3500/health
+```
+
+### Performance Issues
+
+```bash
+# Check resource usage
+kubectl top pods -n agentuity
+
+# Scale up
+kubectl scale deployment/agentuity-runtime \
+  --replicas=5 -n agentuity
+
+# Check database performance
+kubectl exec -it postgres-0 -n agentuity -- \
+  psql -c "SELECT * FROM pg_stat_activity;"
+```
+
+## Best Practices
+
+1. **Network Isolation**: Use network policies to restrict traffic
+2. **Secrets Management**: Use Vault or cloud secret managers
+3. **Resource Limits**: Set appropriate CPU/memory limits
+4. **Monitoring**: Enable comprehensive observability
+5. **Backup**: Regular backups of agent state and config
+6. **Updates**: Keep Agentuity runtime updated
+7. **Documentation**: Document your VPC architecture
+
+## Next Steps
+
+- **Connect to Cloud Console**: Optional monitoring dashboard
+- **Multi-Region**: Deploy across multiple regions
+- **Disaster Recovery**: Set up DR environment
+- **CI/CD**: See `via-github-actions.md` for automation
+- **Multi-Cloud**: See `via-gravity-network.md` for multi-cloud
+
+## References
+
+- [VPC Deployment Guide](https://agentuity.dev/deployment/vpc)
+- [Kubernetes Best Practices](https://agentuity.dev/deployment/kubernetes)
+- [Security Hardening](https://agentuity.dev/security)
+- [Enterprise Support](https://agentuity.com/enterprise)

package/deployments/aws/README.md

@@ -0,0 +1,38 @@
+# AWS Deployment Module
+
+Deft guidance for deploying applications to Amazon Web Services.
+
+## Status
+
+- ! Optional module
+- ~ Good for Deft usage
+
+## Overview
+
+AWS offers comprehensive deployment options from serverless to full infrastructure control.
+
+## Deployment Methods
+
+| File | Method | Best For |
+|------|--------|----------|
+| `via-lambda.md` | AWS Lambda / SAM | Serverless functions, event-driven APIs (default for serverless) |
+| `via-app-runner.md` | AWS App Runner | Simple containerized web apps, minimal configuration (default for containers) |
+| `via-ecs-fargate.md` | ECS Fargate | Production containers, complex apps, full orchestration |
+| `via-elastic-beanstalk.md` | Elastic Beanstalk | Traditional PaaS, multi-language support, managed infrastructure |
+
+## Quick Decision Guide
+
+- **Default serverless**: `via-lambda.md` — SAM or Serverless Framework for functions and APIs
+- **Default containers**: `via-app-runner.md` — simplest path from code/image to HTTPS endpoint
+- **Complex containers**: `via-ecs-fargate.md` — when you need load balancers, VPC, advanced orchestration
+- **Traditional apps**: `via-elastic-beanstalk.md` — PaaS for Python, Node.js, Java, .NET, PHP, Ruby, Go
+
+## References
+
+- [AWS Deployment Options](https://aws.amazon.com/products/compute/)
+- [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/)
+- [AWS App Runner Documentation](https://docs.aws.amazon.com/apprunner/)
+- [AWS Elastic Beanstalk Documentation](https://docs.aws.amazon.com/elasticbeanstalk/)
+- [AWS ECS Documentation](https://docs.aws.amazon.com/ecs/)
+- [AWS EKS Documentation](https://docs.aws.amazon.com/eks/)
+- [AWS Amplify Documentation](https://docs.amplify.aws/)