# System Architecture

## System Overview

infra-provider is a comprehensive infrastructure management system for TiDB Cloud that manages the lifecycle of TiDB Cloud product components. It consists of a group of Kubernetes controllers organized as a monorepo, providing functionality for cluster provisioning, resource management, monitoring, and chaos engineering.

## Architecture Diagram

```mermaid
graph TD
    A[Kubernetes API] --> B[Cluster Controller]
    B --> C[TiDB Cluster CR]
    B --> D[Dataplane Provisioning]
    
    A --> E[Chaos Provider]
    E --> F[Chaos Engineering]
    
    A --> G[Quota Exporter]
    G --> H[Cloud Quota Metrics]
    
    A --> I[Infra Exporter]
    I --> J[Infra API Metrics]
    
    A --> K[Cluster Prober]
    K --> L[Continuous Probing]
    
    A --> M[Cluster Proxy]
    M --> N[Dataplane Proxy]
    
    A --> O[Config Manager]
    O --> P[GitOps Controller]
    
    subgraph "Infrastructure Components"
        Q[Kubernetes Cluster]
        R[Cloud Providers]
        S[Monitoring System]
    end
```

## Component Descriptions

### infra-provider

- **Purpose**: Manage TiDB Cloud infrastructure components lifecycle
- **Responsibilities**:
  - Provision and manage TiDB clusters
  - Handle cloud resource management
  - Monitor infrastructure health
  - Perform chaos engineering tests
  - Export metrics for observability
  - Provide cluster proxy functionality
  - Manage configuration through GitOps

- **Dependencies**:
  - Kubernetes cluster
  - Cloud providers (AWS, GCP, Azure)
  - Prometheus for metrics collection

- **Type**: Infrastructure/Platform

### Cluster Controller

- **Purpose**: Manage TiDB Cluster lifecycle
- **Responsibilities**:
  - Provision TiDB clusters in the dataplane
  - Manage cluster scaling
  - Handle cluster updates and maintenance
  - Monitor cluster health and status

- **Type**: Kubernetes Controller

### Chaos Provider

- **Purpose**: Implement chaos engineering
- **Responsibilities**:
  - Inject chaos into the system
  - Test system resilience and stability
  - Monitor chaos experiment results
  - Provide chaos experiment management

- **Type**: Infrastructure/Testing

### Quota Exporter

- **Purpose**: Export cloud quota metrics
- **Responsibilities**:
  - Collect cloud quota usage data
  - Export metrics for Prometheus scraping
  - Monitor quota usage trends
  - Alert on quota limits approaching

- **Type**: Metrics Exporter

### Infra Exporter

- **Purpose**: Export infrastructure API metrics
- **Responsibilities**:
  - Collect metrics from infrastructure API
  - Export metrics for Prometheus scraping
  - Monitor API performance
  - Identify potential issues and bottlenecks

- **Type**: Metrics Exporter

### Cluster Prober

- **Purpose**: Continuously monitor cluster health
- **Responsibilities**:
  - Probe cluster components for liveness
  - Monitor connection health
  - Identify and report failures
  - Provide early warning of potential issues

- **Type**: Monitoring/Testing

### Cluster Proxy

- **Purpose**: Proxy communication to dataplane services
- **Responsibilities**:
  - Provide lightweight HTTP proxy
  - Manage communication to dataplane services
  - Handle request routing and filtering
  - Monitor proxy performance

- **Type**: Proxy/Networking

### Config Manager

- **Purpose**: Manage configuration through GitOps
- **Responsibilities**:
  - Implement GitOps controller webhook
  - Manage configuration changes
  - Enforce configuration compliance
  - Provide audit trail of configuration changes

- **Type**: Configuration Management

## Data Flow

```mermaid
sequenceDiagram
    participant K8s as Kubernetes API
    participant CC as Cluster Controller
    participant DC as Dataplane
    participant CP as Cluster Prober
    participant CE as Chaos Provider
    participant ME as Metrics Exporters
    
    K8s->>CC: TiDB Cluster CR Change
    CC->>DC: Provision/Update/Delete Cluster
    DC-->>CC: Operation Result
    
    K8s->>CP: Periodic Probe Request
    CP->>DC: Probe Cluster Health
    DC-->>CP: Probe Results
    
    K8s->>CE: Chaos Experiment CR
    CE->>DC: Inject Chaos
    DC-->>CE: Experiment Results
    
    ME->>DC: Metrics Collection
    ME->>K8s: Metrics Export
```

## Integration Points

### External APIs
- **Kubernetes API Server**: For managing custom resources
- **Cloud Provider APIs**: For provisioning cloud resources
- **Prometheus API**: For metrics scraping

### Databases
- **etcd**: For Kubernetes resource storage

### Third-party Services
- **Prometheus**: Metrics collection and storage
- **Alertmanager**: Alerting and notification
- **Grafana**: Metrics visualization

## Infrastructure Components

- **Kubernetes Cluster**: Primary deployment platform
- **Cloud Providers**: AWS, GCP, Azure for infrastructure resources
- **Networking**: VPC, subnets, security groups
- **Storage**: Cloud storage for data and backups

## Deployment Model

- **Monorepo Architecture**: All components managed in a single repository
- **Argo CD Deployment**: GitOps-based deployment
- **Kubernetes Controllers**: Custom controllers running in clusters
- **Prometheus Exporters**: Metrics collection agents
- **Webhooks**: Admission webhooks for resource validation and mutation