Skip to content

Infrastructure Documentation

This directory contains operational documentation for the CAMARADES infrastructure, managed via Terraform.

Documentation Philosophy

"Documentation lives where the action happens."

This repo contains documentation for infrastructure operations - tasks that involve editing Terraform configurations in the camarades-infrastructure repository.

What's Documented Here

Infrastructure Operations

  • Terraform Usage: How to work with Terraform state, plan, apply
  • Cluster Configuration: GKE cluster settings and design rationale
  • Disaster Recovery: Procedures for recovering from infrastructure failures
  • Cost Optimization: Infrastructure cost management strategies

NOT Documented Here

Documentation Index

Guides

Procedures (Planned)

  • Cost Optimization - Managing infrastructure costs (TODO)
  • Disaster Recovery - Cluster recovery procedures (TODO)
  • Troubleshooting - Common infrastructure issues (TODO)

Multi-Repository Documentation Strategy

The SyRF platform spans three repositories:

Repository Purpose Documentation
syrf Application code syrf/docs/
cluster-gitops Deployment config cluster-gitops/docs/
camarades-infrastructure Infrastructure IaC camarades-infrastructure/docs/ ← You are here

Architecture & Decisions: - ADR-003: Cluster Architecture - System Architecture

Deployment Operations: - How to Deploy Services - Promotion Workflow

Service Documentation: - API Service - Web Service

Documentation Decision Flow

Question: "Where do I document infrastructure changes?"

Is it about...
├─ Terraform usage, state management, infrastructure procedures?
│  └─ camarades-infrastructure/docs/ (this repo)
├─ GKE cluster design decisions or architecture?
│  └─ syrf/docs/decisions/ (ADRs in main repo)
├─ How to deploy applications or update image tags?
│  └─ cluster-gitops/docs/ (deployment operations)
└─ Application code or service-specific configuration?
   └─ syrf/src/services/{service}/README.md

Contributing

To add or update infrastructure documentation:

  1. Create or update markdown files in this directory
  2. Follow the naming convention: kebab-case.md
  3. Include clear headings and examples
  4. Link to related documentation in other repos using full GitHub URLs
  5. Update this README's index when adding new docs

Unified Documentation Site

All documentation from across the three repositories is aggregated into a single MkDocs site published at docs.syrf.org.uk. Changes to this directory automatically appear in the "Infrastructure" section of that site.