Configure K8s overlays for development environment

[Hyperkit-dev]

🎯 Layer 1: Intent Parsing

What needs to be done?

Task Title:

Configure K8s overlays for development environment

Area: infra | Repos: infra/

Primary Goal:

Set up Kubernetes configuration overlays (Kustomize) for the development environment to enable environment-specific configurations while maintaining a base configuration

User Story / Context:

As a developer, I want K8s overlays configured for the development environment so that I can deploy and test HyperAgent services locally with appropriate resource limits and configurations

Business Impact:

Enables efficient local development and testing. Supports Phase 1 Foundation goals for infrastructure setup. Reduces developer onboarding time.

Task Metadata:

• Sprint: Sprint 1
• Related Epic/Project: GitHub Project 9 - Phase 1 Foundation
• Issue Type: Feature
• Area: Infra
• Related Documentation:
  • Platform Blueprint - Complete platform specification
  • System Architecture - Infrastructure design
  • Execution Strategy - Deployment strategy

---

📚 Layer 2: Knowledge Retrieval

What information do I need?

Required Skills / Knowledge:

• DevOps/Infra (Kubernetes, Kustomize)
• Container orchestration
• Environment configuration management

Estimated Effort:

M (Medium - 3-5 days)

Knowledge Resources:

• Review .cursor/skills/ for relevant patterns (devops-engineer)
• Check .cursor/llm/docs/ for implementation examples
• Read Platform Blueprint: docs/draft.md
• Read System Architecture: docs/planning/4-System-Architecture-Design.md
• Read Execution Strategy: docs/reference/spec/execute.md
• Study tech docs / ADRs in docs/adrs/ directory
• Review Kustomize documentation and best practices

Architecture Context:

According to the Platform Blueprint, HyperAgent uses a microservice architecture. Kustomize overlays will manage environment-specific configurations for orchestrator, agents, and core services.

System Architecture Diagram:

graph TB
    subgraph "Base Configuration"
        Base[Base K8s Manifests<br/>Common Config]
    end
    
    subgraph "Overlays"
        Dev[Development Overlay]
        Staging[Staging Overlay]
        Prod[Production Overlay]
    end
    
    subgraph "Environments"
        DevEnv[Dev Cluster]
        StagingEnv[Staging Cluster]
        ProdEnv[Prod Cluster]
    end
    
    Base --> Dev
    Base --> Staging
    Base --> Prod
    
    Dev --> DevEnv
    Staging --> StagingEnv
    Prod --> ProdEnv

Loading

Code Examples & Patterns:

Kustomize Overlay Example:

# kustomization.yaml (dev overlay)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- ../../base

replicas:
- name: orchestrator
  count: 1

patchesStrategicMerge:
- resource-limits.yaml
- dev-config.yaml

configMapGenerator:
- name: app-config
  behavior: merge
  literals:
  - ENV=development
  - LOG_LEVEL=debug

---

⚠️ Layer 3: Constraint Analysis

What constraints and dependencies exist?

Known Dependencies:

• Base Kubernetes manifests must exist
• Development Kubernetes cluster must be available
• Container images must be built

Technical Constraints:

Scope limited to development environment overlay configuration. Base manifests and cluster setup tracked separately.

Current Blockers:

None identified (update as work progresses)

Risk Assessment & Mitigations:

Risk of misconfigured resource limits causing performance issues. Mitigation: Start with conservative limits, monitor resource usage, adjust based on actual needs.

Resource Constraints:

• Deadline: Feb 5–17 (Sprint 1)
• Effort Estimate: M (Medium - 3-5 days)

---

💡 Layer 4: Solution Generation

How should this be implemented?

Solution Approach:

Create Kustomize overlay structure:

1. Base configuration with common manifests
2. Development overlay with:
   • Reduced replica counts
   • Lower resource limits
   • Development-specific environment variables
   • Local service endpoints
   • Debug logging enabled
3. Configure patches for resource limits, config maps, and secrets
4. Document overlay usage and customization

Design Considerations:

• Follow established patterns from .cursor/skills/devops-engineer
• Maintain consistency with existing infrastructure code
• Consider scalability and maintainability
• Ensure proper resource limits for dev environment
• Plan for testing and validation
• Support easy switching between environments

Acceptance Criteria (Solution Validation):

• Base Kustomize configuration created
• Development overlay configured with appropriate settings
• Resource limits and requests defined
• Environment-specific config maps and secrets configured
• Services deployable to dev cluster using overlay
• Documentation updated with overlay usage instructions
• Code reviewed and approved

---

📋 Layer 5: Execution Planning

What are the concrete steps?

Implementation Steps:

1. Review base Kubernetes manifests structure
2. Design overlay directory structure
3. Create base kustomization.yaml
4. Create development overlay directory
5. Configure development-specific patches
6. Set resource limits and requests for dev
7. Configure development environment variables
8. Test deployment using overlay
9. Document overlay structure and usage
10. Code review and approval

Environment Setup:
Repos / Services:

• Infra / IaC repo: hyperagent/infra/
• Development Kubernetes cluster

Required Environment Variables:

• KUBECONFIG= (Development cluster configuration)
• DOCKER_REGISTRY_URL= (Container registry URL)

Access & Credentials:

• Kubernetes cluster access: kubeconfig file
• Access request: Contact @devops or project lead

---

✅ Layer 6: Output Formatting & Validation

How do we ensure quality delivery?

Ownership & Collaboration:

• Owner: @JustineDevs
• Reviewer: @ArhonJay
• Access Request: @JustineDevs or @ArhonJay
• Deadline: Feb 5–17 (Sprint 1)
• Communication: Daily stand-up updates, GitHub issue comments

Quality Gates:

• Code follows project style guide (see .cursor/rules/rules.mdc)
• All tests pass (unit, integration, e2e)
• No critical lint/security issues
• Documentation updated (README, code comments, ADRs if needed)
• Meets all acceptance criteria from Layer 4
• Follows production standards (see .cursor/rules/production.mdc)

Review Checklist:

• Code review approved by @ArhonJay
• CI/CD pipeline passes (GitHub Actions)
• Overlay successfully deploys to dev cluster
• Security scan passes (no critical vulnerabilities)
• Documentation complete and accurate

Delivery Status:

• Initial Status: To Do
• Progress Tracking: Use issue comments for updates
• Sign-off: Approved by @Hyperionkit on [YYYY-MM-DD]
• PR Link: [Link to merged PR(s)]

Related Issues:

• Related to infrastructure setup and deployment configuration

Documentation References:

• Platform Blueprint
• System Architecture
• Execution Strategy
• Project Phases