k8s

Documentation

This directory contains comprehensive documentation for the Kubernetes platform. The documentation is organized by topic to help you find what you need quickly.

Note: This documentation focuses on platform components and assumes you have already provisioned your Kubernetes clusters and cloud infrastructure. Infrastructure provisioning guides using Kubernetes-native tools (e.g., Crossplane) will be added in the future.

Quick Start

New to the platform? Start here:

• Getting Started Guide - Step-by-step walkthrough for bootstrapping the platform
• FAQ - Common questions and answers
• Troubleshooting Guide - Solutions to common issues

Architecture & Design

Understanding the platform architecture:

• Architecture Decision Records (ADRs) - Documented rationale for major architectural choices
  • ADR-001: Argo CD App-of-Apps Pattern
  • ADR-002: Thanos for Metrics Aggregation
  • ADR-003: Envoy Gateway Over Traditional Ingress
  • ADR-004: Sealed Secrets for Secret Management
  • ADR-005: Centralized Ops Cluster Topology
  • ADR-006: Multi-Cluster GitOps Approach

Platform Components

Deep-dive guides for major platform pillars:

Observability

• Observability Guide - Metrics (Thanos), Logs (Elastic Stack), Traces (Jaeger)
• Elasticsearch Best Practices - Node roles, mTLS, heap sizing, ILM, GC tuning
• Alert Catalog - Available alerts and their purposes

Traffic Management

• Traffic Management Guide - Envoy Gateway, TLS certificates, DNS automation

GitOps & Operations

• Argo CD Best Practices - HA setup, custom labels, Redis, Gateway exposure, metrics

Security & Compliance

• Policy & Compliance Guide - Kyverno policies, Checkov scanning, audit→enforce strategy

Operational Guides

Day-to-day operations and troubleshooting:

• Troubleshooting Guide - Common issues and solutions
• FAQ - Frequently asked questions
• Alert Catalog - Understanding platform alerts

Documentation by Use Case

I want to…

…bootstrap the platform for the first time → Getting Started Guide

…understand why certain technologies were chosen → Architecture Decision Records

…set up observability (metrics, logs, traces) → Observability Guide

…configure ingress and TLS → Traffic Management Guide

…implement security policies → Policy & Compliance Guide

…troubleshoot an issue → Troubleshooting Guide

…optimize Elasticsearch → Elasticsearch Best Practices

…configure Argo CD properly → Argo CD Best Practices

…understand available alerts → Alert Catalog

…find answers to common questions → FAQ

Documentation Structure

docs/
├── README.md (this file)
├── getting-started.md          # Bootstrap walkthrough
├── observability.md             # Metrics, logs, traces
├── traffic-management.md        # Gateway API, TLS, DNS
├── compliance.md                 # Kyverno, Checkov
├── argocd-best-practices.md     # Argo CD configuration
├── elastic-best-practices.md    # Elasticsearch optimization
├── troubleshooting.md           # Common issues
├── faq.md                       # Questions & answers
├── alert-catalog.md             # Alert definitions
└── adr/                         # Architecture Decision Records
    ├── README.md
    └── [6 ADR files]

Contributing to Documentation

Found an issue or want to improve the documentation?

1. Check if there’s an existing documentation issue
2. Open a new documentation issue
3. Submit a pull request with your improvements

See CONTRIBUTING.md for guidelines.

Related Resources

• Main README - Platform overview and inventory
• AGENTS.md - Repository conventions and structure
• SECURITY.md - Security policy and practices
• CONTRIBUTING.md - How to contribute

This site is open source. Improve this page.