Infrastructure as Code (IaC) implementation guide

[!NOTE] For the latest implementation status, please refer to Functional Implementation Status (Remaining Functionality).

Implementation notes (artifacts): See docs/implementation/ARTIFACT_MANIFESTS.md for the artifact_manifest.json output by the training script and recommended CLI flags.

Implementation date: December 20, 2025 Version: v0.1.0 Author: Masahiro Aoki

overview

EvoSpikeNet's environment management has been implemented as Infrastructure as Code (IaC), achieving 100% environmental reproducibility. We implement a comprehensive IaC system that integrates Terraform, Ansible, Kubernetes, and Docker Compose.

Implementation details

1. Terraform integration

1.1 Main files

• terraform/main.tf: Main configuration file
• Docker provider settings
• Network, volume and container management
• Automatic generation of environment variables

• Health check script generation

• terraform/terraform.tfvars: Variables by environment

• Development environment (CPU, port 8000/8050)
• Staging environment (GPU, ports 8100/8150)

• Production environment (GPU, ports 8200/8250)

• terraform/templates/: Template file

• env.tpl: Environment variable template
• docker-compose-override.tpl: Docker Compose override
• health_check.tpl: Health check script

1.2 How to use

# Initializing Terraform
cd terraform
terraform init

# Check execution plan
terraform plan

# Deploying the environment (dev)
terraform apply -var-file=terraform.tfvars

# Delete environment
terraform destroy

1.3 Customizing variables

# terraform.tfvars
environment            = "dev"
device                 = "cpu"
enable_gpu             = false
api_port               = 8000
frontend_port          = 8050
postgres_password      = "secure_password"
api_keys               = "key1,key2,key3"

2. Ansible integration

2.1 Main files

• ansible/playbook.yml: Main playbook
• Install system dependencies
• Setting up Docker, Docker Compose, and Terraform
• Clone and configure project
• Setting up the Python environment

• Create data directory

• ansible/inventory.ini: Inventory definition

• Local environment
• Development server
• Staging server

• Production server

• ansible/ansible.cfg: Ansible settings

2.2 How to use

# Setting up the local environment
cd ansible
ansible-playbook -i inventory.ini playbook.yml --limit local

# Remote server setup
ansible-playbook -i inventory.ini playbook.yml --limit development

# Setting up the production environment (be careful!)
ansible-playbook -i inventory.ini playbook.yml --limit production

2.3 Customizing Inventory

[development]
dev-server ansible_host=YOUR_IP ansible_user=YOUR_USER

[production]
prod-server-1 ansible_host=YOUR_IP ansible_user=YOUR_USER
prod-server-2 ansible_host=YOUR_IP ansible_user=YOUR_USER

3. Kubernetes integration

3.1 Main components

Defined in k8s/deployment.yaml:

1. Namespace: Dedicated evospikenet namespace
2. ConfigMap: Setting environment variables
3. Secret: Management of confidential data
4. PostgreSQL StatefulSet: Database persistence
5. API Deployment: 3 replicas, autoscaling supported
6. Frontend Deployment: 2 replicas
7. Services: Internal/External Communication
8. HorizontalPodAutoscaler: CPU/memory-based autoscaling
9. Ingress: External access control

3.2 How to use

# Deploy to Kubernetes
kubectl apply -f k8s/deployment.yaml

# Check status
kubectl get all -n evospikenet

# Log confirmation
kubectl logs -n evospikenet -l app=api

# scaling
kubectl scale deployment api -n evospikenet --replicas=5

# delete
kubectl delete namespace evospikenet

3.3 Autoscaling settings

# HPA setting example
minReplicas: 3
maxReplicas: 10
metrics:
  - CPU: 70%
  - Memory: 80%

4. Environment setup script

4.1 scripts/setup_environment.sh

Scripts that perform comprehensive environment setup and verification.

Features: - Dependency checks (Python, Docker, Git, etc.) - Python version verification (≥3.9) - Check the existence of required files - Disk space check (≥10GB) - Create virtual environment and install dependencies - Generate .env file - Setting up pre-commit hooks - Create Docker network - Generate environmental reports

4.2 How to use

# Full setup (interactive)
./scripts/setup_environment.sh dev

# Validation only
./scripts/setup_environment.sh dev true

# staging environment
./scripts/setup_environment.sh staging

4.3 Verification items

✅ Python ≥3.9 ✅ Docker daemon starting ✅ Docker Compose available ✅ Git installed ✅ Necessary files exist ✅ Sufficient disk space (≥10GB) ✅ Necessary ports available

5. Makefile integration

5.1 IaC related commands

# Environment setup
make env-setup

# Validation only
make env-validate

# Terraform operations
make terraform-init      # Initialization
make terraform-plan      # Execution plan display
make terraform-apply     # Applicable
make terraform-destroy   # destruction

# Ansible setup
make ansible-setup

# Kubernetes deployment
make k8s-deploy

# Docker operations
make docker-build        # image build
make docker-up           # Service startup
make docker-down         # Service outage
make docker-logs         # Log display

# health check
make health-check

6. Achieving 100% reproducibility

6.1 Elements that support 100% reproducibility

1. Fixed version:
2. Python package: requirements.txt
3. Docker images: Explicit tag specification
4. Terraform provider: version constraints

5. System package: Ansible management

6. Centralized management of settings:

7. Terraform: Infrastructure configuration
8. Ansible: System settings
9. Docker Compose: Service configuration

10. ConfigMap/Secret: Application settings

11. Automation:

12. Environment verification script
13. Setup script
14. Health check

15. CI/CD integration

16. Documentation:

17. Self-documented IaC configuration
18. Template comments
19. Detailed README

6.2 Environment Types

Environment	Application	GPU	API Port	Front End Port
Development	Development	CPU	8000	8050
Staging	Validation	GPU	8100	8150
Production	Production operation	GPU	8200	8250

7. Deployment flow

7.1 New environment construction

# 1. Repository clone
git clone https://github.com/your-org/EvoSpikeNet.git
cd EvoSpikeNet

# 2. Environmental verification
make env-validate

# 3. Environment setup
make env-setup

# 4. Terraform initialization
make terraform-init

# 5. Terraform application
make terraform-apply

# 6. Service startup
make docker-up

# 7. Health check
make health-check

7.2 Update existing environment

# 1. Code update
git pull

# 2. Update dependencies
pip install -r requirements.txt

# 3. Infrastructure update
make terraform-plan
make terraform-apply

# 4. Service restart
make docker-down
make docker-up

# 5. Health check
make health-check

8. Troubleshooting

Problem: Terraform apply fails

Cause: Docker network conflict

Solution:```bash

Delete existing network

docker network rm evospikenet_dev_network

Reapplying Terraform

make terraform-apply

#### Problem: Port conflict

**Cause**: Port is already in use

**Solution**:```hcl
# Change port in terraform.tfvars
api_port = 8001
frontend_port = 8051

Problem: Python dependency error

Cause: Virtual environment inconsistency

Solution:```bash

Re-creating the virtual environment

rm -rf venv make env-setup

### 9. Security considerations

#### 9.1 Sensitive Data Management

```bash
# Exclude .env files from Git
echo ".env*" >> .gitignore

# Also excludes Terraform states
echo "*.tfstate*" >> .gitignore

# Encrypting secrets (production)
ansible-vault encrypt ansible/secrets.yml

9.2 Access Control

# Managed with Kubernetes Secrets
apiVersion: v1
kind: Secret
metadata:
  name: evospikenet-secrets
type: Opaque
stringData:
  EVOSPIKENET_API_KEYS: "encrypted_keys"

10. CI/CD integration

10.1 GitHub Actions Examples

name: Deploy Infrastructure

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2

      - name: Terraform Init
        run: cd terraform && terraform init

      - name: Terraform Plan
        run: cd terraform && terraform plan

      - name: Terraform Apply
        run: cd terraform && terraform apply -auto-approve

11. Metrics and Monitoring

11.1 Environmental Health Metrics

• API response time
• Service startup time
• Resource utilization
• error rate
• Deployment success rate

11.2 Health check items

✅ API Health (http://localhost:8000/api/health) ✅ Frontend Health (http://localhost:8050/) ✅ PostgreSQL connection ✅ Milvus connection ✅ Elasticsearch connection ✅ Zenoh Router connection

summary

With the IaC implementation, EvoSpikeNet achieved the following:

• ✅ 100% environment reproducibility: The same configuration can be reproduced in any environment
• ✅ Automation: Setup and verification with one command
• ✅ Multi-environment support: Clear separation of Dev/Staging/Production
• ✅ Scalability: Supports Kubernetes for large-scale deployment
• ✅ Security: Proper management of sensitive data
• ✅ Documented: Self-documented IaC configuration
• ✅ CI/CD compatible: Ready for automatic deployment integration
• ✅ Monitoring Integration: Health checks and metrics collection

This allows developers to focus on feature development without worrying about environment setup.