mirror of
https://github.com/andwati/telecom-platform.git
synced 2026-11-17 17:25:13 +00:00
docs: Restructure documentation with comprehensive architecture guide and new API reference
- Remove docs/API.md (237 lines) with TaaS-specific REST endpoints and SDK examples - Expand docs/ARCHITECTURE.md with detailed system overview, component architecture, data flow diagrams, scaling strategies, and RBAC security model - Add Table of Contents with 6 main sections: System Overview, Component Details, Data Flow, Scaling, Security & RBAC, Future Enhancements - Add detailed component descriptions
This commit is contained in:
-237
@@ -1,237 +0,0 @@
|
|||||||
# TaaS Platform API Documentation
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
The TaaS Platform provides a RESTful API for managing cellular connectivity programmatically. All API endpoints are available at `https://api.taas-platform.com/v1` (production) or `http://localhost:8000/v1` (development).
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
All API requests require authentication using Bearer tokens:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
|
||||||
https://api.taas-platform.com/v1/esims
|
|
||||||
```
|
|
||||||
|
|
||||||
Get your API key from the [Developer Dashboard](http://localhost:3000).
|
|
||||||
|
|
||||||
## Endpoints
|
|
||||||
|
|
||||||
### Health Check
|
|
||||||
|
|
||||||
**GET** `/health`
|
|
||||||
|
|
||||||
Check API server status.
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"status": "healthy",
|
|
||||||
"service": "api-server",
|
|
||||||
"timestamp": 1711929600
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Create eSIM
|
|
||||||
|
|
||||||
**POST** `/v1/esims`
|
|
||||||
|
|
||||||
Provision a new eSIM with cellular connectivity.
|
|
||||||
|
|
||||||
**Request:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"data_plan": "1GB",
|
|
||||||
"country_code": "US",
|
|
||||||
"carrier": "optional-carrier-name"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
||||||
"imsi": "208930000000001",
|
|
||||||
"iccid": "8933123456789012345",
|
|
||||||
"activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
|
|
||||||
"status": "provisioned",
|
|
||||||
"data_plan": "1GB",
|
|
||||||
"country_code": "US",
|
|
||||||
"created_at": "2026-04-01T12:00:00Z"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Get eSIM Details
|
|
||||||
|
|
||||||
**GET** `/v1/esims/:id`
|
|
||||||
|
|
||||||
Retrieve information about a specific eSIM.
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
||||||
"imsi": "208930000000001",
|
|
||||||
"iccid": "8933123456789012345",
|
|
||||||
"status": "active",
|
|
||||||
"data_plan": "1GB",
|
|
||||||
"created_at": "2026-04-01T12:00:00Z"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Get eSIM Usage
|
|
||||||
|
|
||||||
**GET** `/v1/esims/:id/usage`
|
|
||||||
|
|
||||||
Get data usage statistics for an eSIM.
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
||||||
"data_used": 262144000,
|
|
||||||
"data_limit": 1073741824,
|
|
||||||
"sessions": [
|
|
||||||
{
|
|
||||||
"started_at": "2026-04-01T10:00:00Z",
|
|
||||||
"ended_at": "2026-04-01T11:00:00Z",
|
|
||||||
"bytes_up": 10485760,
|
|
||||||
"bytes_down": 52428800
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"updated_at": "2026-04-01T12:00:00Z"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Terminate eSIM
|
|
||||||
|
|
||||||
**DELETE** `/v1/esims/:id`
|
|
||||||
|
|
||||||
Permanently terminate an eSIM.
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"message": "eSIM terminated successfully",
|
|
||||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Status Codes
|
|
||||||
|
|
||||||
- `200 OK` - Request successful
|
|
||||||
- `201 Created` - Resource created
|
|
||||||
- `400 Bad Request` - Invalid request parameters
|
|
||||||
- `401 Unauthorized` - Missing or invalid authentication
|
|
||||||
- `404 Not Found` - Resource not found
|
|
||||||
- `500 Internal Server Error` - Server error
|
|
||||||
|
|
||||||
## Rate Limits
|
|
||||||
|
|
||||||
- **Free Tier**: 100 requests/hour
|
|
||||||
- **Pro Tier**: 10,000 requests/hour
|
|
||||||
- **Enterprise**: Unlimited
|
|
||||||
|
|
||||||
Rate limit headers are included in all responses:
|
|
||||||
```
|
|
||||||
X-RateLimit-Limit: 100
|
|
||||||
X-RateLimit-Remaining: 99
|
|
||||||
X-RateLimit-Reset: 1711933200
|
|
||||||
```
|
|
||||||
|
|
||||||
## SDKs
|
|
||||||
|
|
||||||
### TypeScript/JavaScript
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install @taas-platform/sdk
|
|
||||||
```
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import { TaasClient } from '@taas-platform/sdk';
|
|
||||||
|
|
||||||
const client = new TaasClient({ apiKey: 'YOUR_API_KEY' });
|
|
||||||
|
|
||||||
// Create eSIM
|
|
||||||
const esim = await client.esims.create({
|
|
||||||
dataPlan: '1GB',
|
|
||||||
countryCode: 'US'
|
|
||||||
});
|
|
||||||
|
|
||||||
// Get usage
|
|
||||||
const usage = await client.esims.getUsage(esim.esimId);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Go
|
|
||||||
|
|
||||||
```bash
|
|
||||||
go get github.com/taas-platform/sdk-go
|
|
||||||
```
|
|
||||||
|
|
||||||
```go
|
|
||||||
import "github.com/taas-platform/sdk-go"
|
|
||||||
|
|
||||||
client := taas.NewClient("YOUR_API_KEY")
|
|
||||||
|
|
||||||
// Create eSIM
|
|
||||||
esim, err := client.ESims.Create(&taas.CreateESIMRequest{
|
|
||||||
DataPlan: "1GB",
|
|
||||||
CountryCode: "US",
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## Webhooks
|
|
||||||
|
|
||||||
Configure webhooks to receive real-time notifications:
|
|
||||||
|
|
||||||
### Events
|
|
||||||
|
|
||||||
- `esim.created` - New eSIM provisioned
|
|
||||||
- `esim.activated` - eSIM activated on device
|
|
||||||
- `usage.threshold` - Data usage threshold reached (50%, 75%, 90%)
|
|
||||||
- `usage.depleted` - Data plan exhausted
|
|
||||||
- `esim.terminated` - eSIM terminated
|
|
||||||
|
|
||||||
### Webhook Payload
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"event": "usage.threshold",
|
|
||||||
"timestamp": "2026-04-01T12:00:00Z",
|
|
||||||
"data": {
|
|
||||||
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
||||||
"threshold": 75,
|
|
||||||
"data_used": 805306368,
|
|
||||||
"data_limit": 1073741824
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
### Create and Activate eSIM
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Create eSIM
|
|
||||||
curl -X POST https://api.taas-platform.com/v1/esims \
|
|
||||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"data_plan": "1GB",
|
|
||||||
"country_code": "US"
|
|
||||||
}'
|
|
||||||
|
|
||||||
# 2. Show QR code to user (activation_code)
|
|
||||||
# User scans QR code on their device
|
|
||||||
|
|
||||||
# 3. Monitor usage
|
|
||||||
curl https://api.taas-platform.com/v1/esims/ESIM_ID/usage \
|
|
||||||
-H "Authorization: Bearer YOUR_API_KEY"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
- **Documentation**: https://docs.taas-platform.com
|
|
||||||
- **API Status**: https://status.taas-platform.com
|
|
||||||
- **Support Email**: support@taas-platform.com
|
|
||||||
- **GitHub Issues**: https://github.com/nutcas3/telecom-platform/issues
|
|
||||||
+199
-287
@@ -1,10 +1,21 @@
|
|||||||
# TaaS Platform Architecture
|
# Architecture
|
||||||
|
|
||||||
|
Comprehensive overview of the TaaS Platform system design, components, data flow, security, and RBAC.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [System Overview](#system-overview)
|
||||||
|
2. [Component Details](#component-details)
|
||||||
|
3. [Data Flow](#data-flow)
|
||||||
|
4. [Scaling](#scaling)
|
||||||
|
5. [Security & RBAC](#security--rbac)
|
||||||
|
6. [Future Enhancements](#future-enhancements)
|
||||||
|
|
||||||
## System Overview
|
## System Overview
|
||||||
|
|
||||||
The TaaS Platform is a multi-layer telecom infrastructure that provides cellular connectivity as a service. It implements 3GPP standards while exposing a modern, developer-friendly API.
|
The TaaS Platform is a multi-layer telecom infrastructure that provides cellular connectivity as a service, implementing 3GPP standards while exposing a modern, developer-friendly API.
|
||||||
|
|
||||||
## Architecture Layers
|
### Architecture Layers
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
@@ -46,363 +57,264 @@ The TaaS Platform is a multi-layer telecom infrastructure that provides cellular
|
|||||||
|
|
||||||
### 1. API Server (Go 1.26)
|
### 1. API Server (Go 1.26)
|
||||||
|
|
||||||
**Purpose**: Developer-facing RESTful API and business logic
|
**Purpose**: Developer-facing RESTful API and business logic.
|
||||||
|
|
||||||
**Technology**:
|
**Stack**:
|
||||||
- Language: Go 1.26 (Green Tea GC, new(expr) syntax)
|
- Gin framework
|
||||||
- Framework: Gin
|
- GORM with PostgreSQL (primary) / MongoDB (free5GC subscriber data)
|
||||||
- Database: MongoDB (subscriber data)
|
- Redis (session/cache)
|
||||||
- Cache: Redis (session management)
|
- Casbin for RBAC
|
||||||
|
- WebSocket for real-time updates
|
||||||
|
|
||||||
**Responsibilities**:
|
**Responsibilities**:
|
||||||
- eSIM creation and management
|
- eSIM lifecycle management
|
||||||
- Authentication and authorization
|
- Authentication (JWT) and authorization (Casbin)
|
||||||
- Rate limiting and quotas
|
- Rate limiting, quotas, and performance monitoring
|
||||||
- Webhook delivery
|
- Webhook delivery
|
||||||
- API documentation
|
- Health checks and alerting
|
||||||
|
|
||||||
**Endpoints**:
|
**Key Endpoints**:
|
||||||
- `POST /v1/esims` - Create eSIM
|
- `/v1/auth/*` — authentication
|
||||||
- `GET /v1/esims/:id` - Get eSIM details
|
- `/v1/esims/*` — eSIM management
|
||||||
- `GET /v1/esims/:id/usage` - Get usage stats
|
- `/v1/services/*` — service operations
|
||||||
- `DELETE /v1/esims/:id` - Terminate eSIM
|
- `/v1/monitoring/*` — metrics & alerts
|
||||||
|
- `/v1/billing/*` — invoicing
|
||||||
|
- `/ws` — WebSocket stream
|
||||||
|
- `/health`, `/ready`, `/live` — probes
|
||||||
|
|
||||||
### 2. Carrier Connector (Go 1.26)
|
### 2. Carrier Connector (Go 1.26)
|
||||||
|
|
||||||
**Purpose**: Integration with GSMA SM-DP+ servers for eSIM provisioning
|
**Purpose**: Integration with GSMA SM-DP+ servers for eSIM provisioning.
|
||||||
|
|
||||||
**Technology**:
|
|
||||||
- Language: Go 1.26
|
|
||||||
- Protocol: HTTPS (ES2+ API)
|
|
||||||
- Vendor: Thales, G+D, or Idemia
|
|
||||||
|
|
||||||
**Responsibilities**:
|
|
||||||
- Profile ordering via ES2+ protocol
|
|
||||||
- Activation code generation (LPA strings)
|
|
||||||
- Profile status tracking
|
|
||||||
- Vendor-specific adaptations
|
|
||||||
|
|
||||||
**Flow**:
|
**Flow**:
|
||||||
1. Receive eSIM order from API Server
|
1. Receive eSIM order from API Server
|
||||||
2. Call SM-DP+ vendor API with IMSI, K, OPc keys
|
2. Call SM-DP+ vendor API with IMSI, K, OPc keys (ES2+ over HTTPS)
|
||||||
3. Receive activation code (LPA:1$...)
|
3. Receive activation code (LPA:1$...)
|
||||||
4. Return to API Server for user display
|
4. Return to API Server
|
||||||
|
|
||||||
|
Supports multiple vendors: Thales, G+D, Idemia.
|
||||||
|
|
||||||
### 3. Charging Engine (Rust 1.94)
|
### 3. Charging Engine (Rust 1.94)
|
||||||
|
|
||||||
**Purpose**: Real-time credit control and billing
|
**Purpose**: Real-time credit control and billing.
|
||||||
|
|
||||||
**Technology**:
|
**Stack**:
|
||||||
- Language: Rust 1.94 (array_windows, async Tokio)
|
- Axum (async web framework)
|
||||||
- Framework: Axum
|
- Redis for in-memory credit balances
|
||||||
- Database: Redis (in-memory credit balances)
|
- Atomic INCR/DECR operations
|
||||||
|
|
||||||
**Responsibilities**:
|
**Endpoints**:
|
||||||
- Credit balance management
|
- `POST /v1/credit/:ip/check` — authorization
|
||||||
- Real-time authorization checks
|
- `POST /v1/credit/:ip/deduct` — usage deduction
|
||||||
- Usage deduction (atomic operations)
|
- `POST /v1/credit/:ip/add` — top-up
|
||||||
- Credit top-up processing
|
- `GET /v1/credit/:ip/balance` — balance query
|
||||||
|
|
||||||
**API**:
|
**Performance**: Sub-millisecond p99, horizontally scalable via Redis Cluster.
|
||||||
- `POST /v1/credit/:ip/check` - Check if user has credit
|
|
||||||
- `POST /v1/credit/:ip/deduct` - Deduct bytes used
|
|
||||||
- `POST /v1/credit/:ip/add` - Add credit
|
|
||||||
- `GET /v1/credit/:ip/balance` - Get balance
|
|
||||||
|
|
||||||
**Performance**:
|
|
||||||
- Sub-millisecond response times
|
|
||||||
- Atomic Redis operations (INCR, DECR)
|
|
||||||
- Horizontal scaling via Redis Cluster
|
|
||||||
|
|
||||||
### 4. Packet Gateway (Rust 1.94 + eBPF)
|
### 4. Packet Gateway (Rust 1.94 + eBPF)
|
||||||
|
|
||||||
**Purpose**: High-performance packet processing and traffic control
|
**Purpose**: High-performance packet processing at line rate.
|
||||||
|
|
||||||
**Technology**:
|
**Stack**:
|
||||||
- Language: Rust 1.94
|
- Aya (pure Rust eBPF)
|
||||||
- Framework: Aya (pure Rust eBPF)
|
- XDP (eXpress Data Path) hook
|
||||||
- Attach Point: XDP (eXpress Data Path)
|
- GTP-U decapsulation (UDP 2152)
|
||||||
- Protocol: GTP-U decapsulation (UDP port 2152)
|
|
||||||
|
|
||||||
**Responsibilities**:
|
|
||||||
- Parse GTP-U tunneled packets
|
|
||||||
- Extract user IP addresses
|
|
||||||
- Count bytes per subscriber
|
|
||||||
- Block traffic for users without credit
|
|
||||||
- Sync stats to Redis
|
|
||||||
|
|
||||||
**Architecture**:
|
**Architecture**:
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────┐
|
NIC → XDP Hook (kernel eBPF) → eBPF Maps → Userspace Daemon → Redis
|
||||||
│ Network Interface (eth0) │
|
|
||||||
└─────────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌─────────▼─────────┐
|
|
||||||
│ XDP Hook │ ← eBPF program runs here
|
|
||||||
│ (Kernel) │
|
|
||||||
└─────────┬─────────┘
|
|
||||||
│
|
|
||||||
┌─────────▼─────────┐
|
|
||||||
│ eBPF Maps │
|
|
||||||
│ - Packet Stats │
|
|
||||||
│ - Credit Status │
|
|
||||||
└─────────┬─────────┘
|
|
||||||
│
|
|
||||||
┌─────────▼─────────┐
|
|
||||||
│ Userspace Daemon │ ← Rust application
|
|
||||||
│ (Reads maps, │
|
|
||||||
│ syncs to Redis) │
|
|
||||||
└───────────────────┘
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Packet Processing**:
|
**Packet flow**:
|
||||||
1. Packet arrives at NIC
|
1. Packet arrives at NIC
|
||||||
2. XDP hook inspects Ethernet → IP → UDP → GTP-U headers
|
2. XDP inspects Ethernet → IP → UDP → GTP-U headers
|
||||||
3. Extract inner IP packet (actual user data)
|
3. Extract inner IP (user data), look up credit in eBPF map
|
||||||
4. Look up credit status in eBPF map
|
4. If credit > 0: `XDP_PASS`; else: `XDP_DROP`
|
||||||
5. If credit > 0: `XDP_PASS`, else: `XDP_DROP`
|
5. Userspace daemon syncs byte counters to Redis every 1s
|
||||||
6. Update packet statistics in eBPF map
|
|
||||||
7. Userspace daemon reads stats, syncs to Redis
|
|
||||||
|
|
||||||
### 5. 5G Core Network (free5GC)
|
### 5. 5G Core Network (free5GC v4.2.1)
|
||||||
|
|
||||||
**Purpose**: 3GPP-compliant 5G standalone core
|
3GPP-compliant 5G standalone core with all network functions (AMF, SMF, UPF, PCF, UDM, UDR, AUSF, NRF).
|
||||||
|
|
||||||
**Technology**:
|
**Integration**:
|
||||||
- Project: free5GC v4.2.1
|
|
||||||
- Language: Go
|
|
||||||
- Database: MongoDB
|
|
||||||
- Deployment: Kubernetes or bare metal
|
|
||||||
|
|
||||||
**Network Functions**:
|
|
||||||
- **AMF** (Access and Mobility Management)
|
|
||||||
- **SMF** (Session Management)
|
|
||||||
- **UPF** (User Plane Function)
|
|
||||||
- **PCF** (Policy Control)
|
|
||||||
- **UDM** (Unified Data Management)
|
|
||||||
- **UDR** (Unified Data Repository)
|
|
||||||
- **AUSF** (Authentication Server)
|
|
||||||
- **NRF** (NF Repository)
|
|
||||||
|
|
||||||
**Integration Points**:
|
|
||||||
- API Server writes subscriber data to MongoDB
|
- API Server writes subscriber data to MongoDB
|
||||||
- UPF forwards GTP-U traffic to Packet Gateway
|
- UPF forwards GTP-U to Packet Gateway
|
||||||
- AMF handles UE authentication using stored keys (K, OPc)
|
- AMF authenticates using stored K/OPc keys
|
||||||
|
|
||||||
### 6. Web Dashboard (Next.js 15)
|
### 6. Web Dashboard (Next.js 15)
|
||||||
|
|
||||||
**Purpose**: Developer portal and management interface
|
- App Router, TypeScript, Tailwind CSS
|
||||||
|
- TanStack Query for data fetching
|
||||||
|
- Real-time updates via WebSocket
|
||||||
|
- Error boundaries and loading states
|
||||||
|
|
||||||
**Technology**:
|
**Pages**: eSIM management, services, monitoring, billing, config, chaos engineering, plugins, automation.
|
||||||
- Framework: Next.js 15 (App Router)
|
|
||||||
- Language: TypeScript
|
|
||||||
- Styling: Tailwind CSS
|
|
||||||
- Data Fetching: TanStack Query
|
|
||||||
|
|
||||||
**Features**:
|
|
||||||
- eSIM creation and management
|
|
||||||
- Real-time usage charts (Recharts)
|
|
||||||
- API key management
|
|
||||||
- Webhook configuration
|
|
||||||
- Billing and invoices
|
|
||||||
|
|
||||||
## Data Flow
|
## Data Flow
|
||||||
|
|
||||||
### eSIM Creation Flow
|
### eSIM Creation
|
||||||
|
|
||||||
```
|
```
|
||||||
1. Developer → API Server
|
1. Developer → API Server: POST /v1/esims { data_plan: "1GB" }
|
||||||
POST /v1/esims { data_plan: "1GB" }
|
2. API Server → IMSI Allocator: generate 15-digit IMSI
|
||||||
|
3. API Server → Key Generator: K + OPc
|
||||||
2. API Server → IMSI Allocator
|
4. API Server → MongoDB: insert subscriptionData
|
||||||
Generate unique 15-digit IMSI
|
5. API Server → Carrier Connector: order via ES2+
|
||||||
|
6. Carrier Connector → SM-DP+: HTTPS POST (IMSI, K, OPc)
|
||||||
3. API Server → Key Generator
|
7. SM-DP+ → Carrier Connector: activation code (LPA:1$...)
|
||||||
Generate K (subscriber key)
|
8. API Server → Developer: eSIM + activation code
|
||||||
Generate OPc (operator key)
|
9. End User scans QR → SM-DP+: profile download
|
||||||
|
10. Device → free5GC AMF: 5G AKA registration
|
||||||
4. API Server → MongoDB (free5GC)
|
11. free5GC → Packet Gateway: GTP-U tunnel established
|
||||||
Insert subscriber data:
|
|
||||||
- subscriptionData.authenticationData (K, OPc)
|
|
||||||
- subscriptionData.provisionedData (IMSI, AMBR)
|
|
||||||
|
|
||||||
5. API Server → Carrier Connector
|
|
||||||
Order eSIM profile via ES2+
|
|
||||||
|
|
||||||
6. Carrier Connector → SM-DP+ Vendor
|
|
||||||
HTTPS POST with IMSI, K, OPc
|
|
||||||
|
|
||||||
7. SM-DP+ → Carrier Connector
|
|
||||||
Return activation code (LPA string)
|
|
||||||
|
|
||||||
8. API Server → Developer
|
|
||||||
Return eSIM details + activation code
|
|
||||||
|
|
||||||
9. Developer → End User
|
|
||||||
Display QR code with LPA string
|
|
||||||
|
|
||||||
10. End User's Device → SM-DP+
|
|
||||||
Scan QR, download eSIM profile
|
|
||||||
|
|
||||||
11. Device → free5GC AMF
|
|
||||||
Registration procedure (5G AKA)
|
|
||||||
|
|
||||||
12. free5GC → Packet Gateway
|
|
||||||
Establish GTP-U tunnel for data
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Real-Time Usage Flow
|
### Real-Time Usage
|
||||||
|
|
||||||
```
|
```
|
||||||
1. User Device sends data
|
1. User device sends data
|
||||||
↓
|
|
||||||
2. free5GC UPF encapsulates in GTP-U
|
2. free5GC UPF encapsulates in GTP-U
|
||||||
↓
|
3. Packet Gateway (eBPF XDP):
|
||||||
3. Packet Gateway (eBPF XDP)
|
- Decapsulate, extract user IP
|
||||||
- Decapsulate GTP-U
|
- Check credit in eBPF map
|
||||||
- Extract user IP
|
4. If credit > 0: XDP_PASS + increment byte counter
|
||||||
- Check credit status in eBPF map
|
5. Userspace daemon: read eBPF maps → Redis (1s interval)
|
||||||
↓
|
6. Charging Engine: deduct from credit balance
|
||||||
4. If credit > 0:
|
7. Packet Gateway: reload credit status from Redis → eBPF map
|
||||||
- Pass packet (XDP_PASS)
|
8. If credit = 0: XDP_DROP (user traffic stops)
|
||||||
- Increment byte counter in eBPF map
|
|
||||||
↓
|
|
||||||
5. Userspace daemon (Rust)
|
|
||||||
- Reads eBPF maps every 1 second
|
|
||||||
- Writes stats to Redis
|
|
||||||
↓
|
|
||||||
6. Charging Engine
|
|
||||||
- Reads usage from Redis
|
|
||||||
- Deducts from credit balance
|
|
||||||
- Updates credit status
|
|
||||||
↓
|
|
||||||
7. Packet Gateway
|
|
||||||
- Reads new credit status from Redis
|
|
||||||
- Updates eBPF map
|
|
||||||
↓
|
|
||||||
8. If credit reaches 0:
|
|
||||||
- eBPF drops packets (XDP_DROP)
|
|
||||||
- User's internet stops
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Scaling Architecture
|
## Scaling
|
||||||
|
|
||||||
### Horizontal Scaling
|
### Horizontal (Stateless)
|
||||||
|
|
||||||
**Stateless Components** (can be replicated):
|
|
||||||
- API Server: 3+ replicas behind load balancer
|
- API Server: 3+ replicas behind load balancer
|
||||||
- Carrier Connector: 2+ replicas
|
- Carrier Connector: 2+ replicas
|
||||||
- Charging Engine: 2+ replicas
|
- Charging Engine: 2+ replicas
|
||||||
- Web Dashboard: CDN + multiple origins
|
- Web Dashboard: CDN + multiple origins
|
||||||
|
|
||||||
**Stateful Components** (require special handling):
|
### Stateful
|
||||||
- MongoDB: Replica set (1 primary, 2 secondaries)
|
|
||||||
- Redis: Cluster mode or Sentinel
|
|
||||||
- Packet Gateway: One instance per physical server (eBPF)
|
|
||||||
- free5GC: Kubernetes deployment with dedicated UPF nodes
|
|
||||||
|
|
||||||
### Performance Metrics
|
- MongoDB: replica set (1 primary, 2 secondaries)
|
||||||
|
- PostgreSQL: primary + streaming replicas
|
||||||
|
- Redis: Cluster or Sentinel
|
||||||
|
- Packet Gateway: one per physical server (eBPF kernel binding)
|
||||||
|
- free5GC: K8s deployment with dedicated UPF nodes
|
||||||
|
|
||||||
**Throughput**:
|
### Performance Targets
|
||||||
- API Server: 10,000 requests/second
|
|
||||||
- Charging Engine: 50,000 credit checks/second
|
|
||||||
- Packet Gateway: 10 Gbps+ per server (eBPF)
|
|
||||||
- free5GC UPF: 5 Gbps per instance
|
|
||||||
|
|
||||||
**Latency**:
|
| Component | Throughput | Latency (p99) |
|
||||||
- API Server: <50ms p99
|
|-----------|-----------|----------------|
|
||||||
- Charging Engine: <1ms p99 (Redis)
|
| API Server | 10,000 req/s | <100ms |
|
||||||
- Packet Gateway: <1µs (eBPF in kernel)
|
| Charging Engine | 50,000 checks/s | <1ms |
|
||||||
- eSIM Provisioning: <2 seconds end-to-end
|
| Packet Gateway | 10+ Gbps/server | <1µs (kernel) |
|
||||||
|
| free5GC UPF | 5 Gbps/instance | — |
|
||||||
|
| eSIM provisioning | — | <2s end-to-end |
|
||||||
|
|
||||||
## Security
|
## Security & RBAC
|
||||||
|
|
||||||
### Authentication & Authorization
|
### Authentication
|
||||||
- API keys with HMAC signatures
|
|
||||||
- JWT tokens for web dashboard
|
- **JWT** tokens for web dashboard and API
|
||||||
- OAuth 2.0 for third-party integrations
|
- **API keys** with HMAC signatures for programmatic access
|
||||||
- Rate limiting per API key
|
- **OAuth 2.0** for third-party integrations
|
||||||
|
- **Refresh tokens** for long-lived sessions
|
||||||
|
|
||||||
|
JWT middleware (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/auth.go`) validates tokens on all protected routes.
|
||||||
|
|
||||||
|
### RBAC with Casbin
|
||||||
|
|
||||||
|
Sophisticated policy-based access control using Casbin with a GORM adapter for persistent policies.
|
||||||
|
|
||||||
|
**Request flow**:
|
||||||
|
```
|
||||||
|
Request → AuthMiddleware (JWT) → CasbinRBAC (policy check) → Handler
|
||||||
|
```
|
||||||
|
|
||||||
|
**Model** (in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/rbac/casbin.go`):
|
||||||
|
|
||||||
|
```
|
||||||
|
[request_definition]
|
||||||
|
r = sub, obj, act
|
||||||
|
|
||||||
|
[policy_definition]
|
||||||
|
p = sub, obj, act
|
||||||
|
|
||||||
|
[role_definition]
|
||||||
|
g = _, _
|
||||||
|
|
||||||
|
[policy_effect]
|
||||||
|
e = some(where (p.eft == allow))
|
||||||
|
|
||||||
|
[matchers]
|
||||||
|
m = g(r.sub, p.sub) && keyMatch(r.obj, p.obj) && (r.act == p.act || p.act == "*")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Default policies**:
|
||||||
|
|
||||||
|
| Role | Permissions |
|
||||||
|
|------|-------------|
|
||||||
|
| `admin` | All resources, all actions |
|
||||||
|
| `operator` | Services, monitoring, deployments (GET/POST) |
|
||||||
|
| `viewer` | Read-only on all resources |
|
||||||
|
|
||||||
|
**Usage in routes**:
|
||||||
|
```go
|
||||||
|
users := protected.Group("/users")
|
||||||
|
if casbinSvc != nil {
|
||||||
|
users.Use(middleware.RequireCasbinPermission(casbinSvc, "/v1/users", "GET"))
|
||||||
|
} else {
|
||||||
|
users.Use(middleware.RequireRole("admin")) // fallback
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Policy management**:
|
||||||
|
```go
|
||||||
|
casbinSvc.AddPolicy("operator", "/v1/services/*", "GET")
|
||||||
|
casbinSvc.AddRoleForUser("user123", "operator")
|
||||||
|
allowed, err := casbinSvc.CheckPermission(userID, "/v1/services", "GET")
|
||||||
|
```
|
||||||
|
|
||||||
### Data Encryption
|
### Data Encryption
|
||||||
- TLS 1.3 for all API endpoints
|
|
||||||
- MongoDB encryption at rest
|
|
||||||
- Redis TLS connections
|
|
||||||
- eBPF packet inspection (no decryption)
|
|
||||||
|
|
||||||
### Secrets Management
|
- TLS 1.3 for all API endpoints
|
||||||
- Kubernetes Secrets for production
|
- MongoDB/PostgreSQL encryption at rest
|
||||||
- HashiCorp Vault for sensitive keys
|
- Redis TLS connections
|
||||||
- Environment variables for local dev
|
- Secrets via Kubernetes Secrets or HashiCorp Vault
|
||||||
- No hardcoded credentials
|
- No hardcoded credentials
|
||||||
|
|
||||||
## Deployment
|
### Security Headers
|
||||||
|
|
||||||
### Development
|
Applied globally via middleware:
|
||||||
```bash
|
|
||||||
make all # Build all components
|
```
|
||||||
make db-setup # Set up MongoDB + Redis
|
X-Content-Type-Options: nosniff
|
||||||
make dev # Start all services
|
X-Frame-Options: DENY
|
||||||
|
X-XSS-Protection: 1; mode=block
|
||||||
|
Strict-Transport-Security: max-age=31536000; includeSubDomains
|
||||||
```
|
```
|
||||||
|
|
||||||
### Docker Compose
|
Plus request size limit (10MB), request timeout (30s), and CORS configuration.
|
||||||
```bash
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
### Kubernetes
|
### Rate Limiting
|
||||||
```bash
|
|
||||||
kubectl apply -f deployments/kubernetes/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Production Checklist
|
Tiered limits protect against abuse (see `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/ratelimit.go`):
|
||||||
- [ ] MongoDB replica set configured
|
|
||||||
- [ ] Redis Cluster or Sentinel enabled
|
|
||||||
- [ ] TLS certificates installed
|
|
||||||
- [ ] Monitoring (Prometheus, Grafana)
|
|
||||||
- [ ] Logging (ELK Stack or Loki)
|
|
||||||
- [ ] Backup strategy implemented
|
|
||||||
- [ ] Disaster recovery plan documented
|
|
||||||
- [ ] Load testing completed (10x expected traffic)
|
|
||||||
|
|
||||||
## Monitoring
|
| Tier | Limit/min | Burst |
|
||||||
|
|------|-----------|-------|
|
||||||
### Metrics (Prometheus)
|
| Auth | 10 | 5 |
|
||||||
- `api_requests_total` - Total API requests
|
| Read | 200 | 50 |
|
||||||
- `esim_creations_total` - eSIMs created
|
| Admin | 50 | 10 |
|
||||||
- `data_usage_bytes_total` - Total data usage
|
| Default | 100 | 20 |
|
||||||
- `charging_checks_duration_seconds` - Credit check latency
|
|
||||||
- `packet_gateway_packets_total` - Packets processed
|
|
||||||
|
|
||||||
### Alerts
|
|
||||||
- High error rate (>1%)
|
|
||||||
- Low credit balances (<10% of users)
|
|
||||||
- MongoDB replica lag (>10 seconds)
|
|
||||||
- Redis memory usage (>90%)
|
|
||||||
- Packet gateway packet loss (>0.1%)
|
|
||||||
|
|
||||||
## Future Enhancements
|
## Future Enhancements
|
||||||
|
|
||||||
1. **Multi-Region Deployment**
|
1. **Multi-region deployment** — AWS multi-region with Route 53 global LB and data residency compliance.
|
||||||
- Deploy in multiple AWS regions
|
2. **Advanced analytics** — predictive usage forecasting, anomaly detection.
|
||||||
- Global load balancing with Route 53
|
3. **Additional carriers** — multi-vendor SM-DP+ with fallback.
|
||||||
- Data residency compliance
|
4. **IoT optimization** — SGP.32 (IoT eSIM), NB-IoT/LTE-M, power-saving features.
|
||||||
|
5. **Developer tools** — expanded CLI, Terraform provider, GitHub Actions integration.
|
||||||
|
|
||||||
2. **Advanced Analytics**
|
## Related Docs
|
||||||
- Real-time dashboards with WebSockets
|
|
||||||
- Predictive usage forecasting
|
|
||||||
- Anomaly detection (unusual data patterns)
|
|
||||||
|
|
||||||
3. **Additional Carriers**
|
- [`GETTING_STARTED.md`](./GETTING_STARTED.md) — Setup, API reference, SDKs
|
||||||
- Support for multiple SM-DP+ vendors
|
- [`OPERATIONS.md`](./OPERATIONS.md) — Deployment, monitoring, performance tuning
|
||||||
- Dynamic carrier selection based on region
|
|
||||||
- Fallback mechanisms
|
|
||||||
|
|
||||||
4. **IoT Optimization**
|
|
||||||
- SGP.32 support (IoT eSIM standard)
|
|
||||||
- LPWAN protocol support (NB-IoT, LTE-M)
|
|
||||||
- Power-saving features
|
|
||||||
|
|
||||||
5. **Developer Tools**
|
|
||||||
- CLI tool for API interaction
|
|
||||||
- Terraform provider
|
|
||||||
- GitHub Actions integration
|
|
||||||
|
|||||||
@@ -1,454 +0,0 @@
|
|||||||
# Deployment Guide
|
|
||||||
|
|
||||||
This guide covers deploying the TaaS Platform in different environments.
|
|
||||||
|
|
||||||
## Table of Contents
|
|
||||||
|
|
||||||
1. [Local Development](#local-development)
|
|
||||||
2. [Docker Deployment](#docker-deployment)
|
|
||||||
3. [Kubernetes Deployment](#kubernetes-deployment)
|
|
||||||
4. [Production Considerations](#production-considerations)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Local Development
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Go 1.26+
|
|
||||||
- Rust 1.94+
|
|
||||||
- Node.js 22+
|
|
||||||
- MongoDB 7.0+
|
|
||||||
- Redis 7+
|
|
||||||
- pnpm
|
|
||||||
|
|
||||||
### Quick Start
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Clone repository
|
|
||||||
git clone https://github.com/nutcas3/telecom-platform.git
|
|
||||||
cd telecom-platform
|
|
||||||
|
|
||||||
# 2. Run setup script
|
|
||||||
chmod +x scripts/dev-setup.sh
|
|
||||||
./scripts/dev-setup.sh
|
|
||||||
|
|
||||||
# 3. Set up databases
|
|
||||||
make db-setup
|
|
||||||
|
|
||||||
# 4. Build all components
|
|
||||||
make all
|
|
||||||
|
|
||||||
# 5. Start services (in separate terminals)
|
|
||||||
# Terminal 1: API Server
|
|
||||||
./dist/api-server
|
|
||||||
|
|
||||||
# Terminal 2: Carrier Connector
|
|
||||||
./dist/carrier-connector
|
|
||||||
|
|
||||||
# Terminal 3: Charging Engine
|
|
||||||
./target/release/charging-engine
|
|
||||||
|
|
||||||
# Terminal 4: Web Dashboard
|
|
||||||
cd apps/web-dashboard && pnpm dev
|
|
||||||
```
|
|
||||||
|
|
||||||
### Environment Variables
|
|
||||||
|
|
||||||
Create `.env` files in each service directory:
|
|
||||||
|
|
||||||
**apps/api-server/.env:**
|
|
||||||
```env
|
|
||||||
MONGODB_URI=mongodb://localhost:27017/free5gc
|
|
||||||
REDIS_URI=redis://localhost:6379
|
|
||||||
API_PORT=8000
|
|
||||||
GIN_MODE=debug
|
|
||||||
```
|
|
||||||
|
|
||||||
**apps/charging-engine/.env:**
|
|
||||||
```env
|
|
||||||
REDIS_URI=redis://127.0.0.1/
|
|
||||||
SERVER_PORT=8080
|
|
||||||
RUST_LOG=info
|
|
||||||
```
|
|
||||||
|
|
||||||
**apps/web-dashboard/.env.local:**
|
|
||||||
```env
|
|
||||||
NEXT_PUBLIC_API_URL=http://localhost:8000
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Docker Deployment
|
|
||||||
|
|
||||||
### Build Images
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Build all Docker images
|
|
||||||
make docker-build
|
|
||||||
|
|
||||||
# Or build individually
|
|
||||||
docker build -f deployments/docker/api-server.Dockerfile -t taas-api-server .
|
|
||||||
docker build -f deployments/docker/charging-engine.Dockerfile -t taas-charging-engine .
|
|
||||||
docker build -f deployments/docker/web-dashboard.Dockerfile -t taas-web-dashboard .
|
|
||||||
```
|
|
||||||
|
|
||||||
### Run with Docker Compose
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Start all services
|
|
||||||
docker-compose up -d
|
|
||||||
|
|
||||||
# View logs
|
|
||||||
docker-compose logs -f
|
|
||||||
|
|
||||||
# Stop all services
|
|
||||||
docker-compose down
|
|
||||||
|
|
||||||
# Stop and remove volumes
|
|
||||||
docker-compose down -v
|
|
||||||
```
|
|
||||||
|
|
||||||
### Service URLs
|
|
||||||
|
|
||||||
After starting with docker-compose:
|
|
||||||
|
|
||||||
- **API Server**: http://localhost:8000
|
|
||||||
- **Charging Engine**: http://localhost:8080
|
|
||||||
- **Web Dashboard**: http://localhost:3000
|
|
||||||
- **MongoDB**: mongodb://localhost:27017
|
|
||||||
- **Redis**: redis://localhost:6379
|
|
||||||
|
|
||||||
### Troubleshooting
|
|
||||||
|
|
||||||
**MongoDB connection issues:**
|
|
||||||
```bash
|
|
||||||
# Check if MongoDB is running
|
|
||||||
docker-compose ps mongodb
|
|
||||||
|
|
||||||
# View MongoDB logs
|
|
||||||
docker-compose logs mongodb
|
|
||||||
|
|
||||||
# Connect to MongoDB shell
|
|
||||||
docker exec -it taas-mongodb mongosh
|
|
||||||
```
|
|
||||||
|
|
||||||
**Redis connection issues:**
|
|
||||||
```bash
|
|
||||||
# Test Redis connection
|
|
||||||
docker exec -it taas-redis redis-cli ping
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Kubernetes Deployment
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Kubernetes cluster (v1.28+)
|
|
||||||
- kubectl configured
|
|
||||||
- Persistent storage provisioner
|
|
||||||
- LoadBalancer service support (or Ingress controller)
|
|
||||||
|
|
||||||
### Deploy to Kubernetes
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Create namespace
|
|
||||||
kubectl create namespace taas-platform
|
|
||||||
|
|
||||||
# 2. Deploy all manifests
|
|
||||||
kubectl apply -f deployments/kubernetes/
|
|
||||||
|
|
||||||
# 3. Verify deployments
|
|
||||||
kubectl get pods -n taas-platform
|
|
||||||
|
|
||||||
# Expected output:
|
|
||||||
# NAME READY STATUS RESTARTS AGE
|
|
||||||
# mongodb-xxx 1/1 Running 0 2m
|
|
||||||
# redis-xxx 1/1 Running 0 2m
|
|
||||||
# api-server-xxx 1/1 Running 0 1m
|
|
||||||
# charging-engine-xxx 1/1 Running 0 1m
|
|
||||||
```
|
|
||||||
|
|
||||||
### Access Services
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Get API Server external IP
|
|
||||||
kubectl get svc api-server -n taas-platform
|
|
||||||
|
|
||||||
# Port forward for local access
|
|
||||||
kubectl port-forward -n taas-platform svc/api-server 8000:8000
|
|
||||||
kubectl port-forward -n taas-platform svc/charging-engine 8080:8080
|
|
||||||
```
|
|
||||||
|
|
||||||
### Scaling
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Scale API Server
|
|
||||||
kubectl scale deployment api-server -n taas-platform --replicas=5
|
|
||||||
|
|
||||||
# Scale Charging Engine
|
|
||||||
kubectl scale deployment charging-engine -n taas-platform --replicas=3
|
|
||||||
|
|
||||||
# Enable autoscaling
|
|
||||||
kubectl autoscale deployment api-server -n taas-platform \
|
|
||||||
--min=3 --max=10 --cpu-percent=70
|
|
||||||
```
|
|
||||||
|
|
||||||
### Monitoring
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# View logs
|
|
||||||
kubectl logs -f deployment/api-server -n taas-platform
|
|
||||||
|
|
||||||
# Describe pod for issues
|
|
||||||
kubectl describe pod <pod-name> -n taas-platform
|
|
||||||
|
|
||||||
# Get events
|
|
||||||
kubectl get events -n taas-platform --sort-by='.lastTimestamp'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Update Deployment
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Update image
|
|
||||||
kubectl set image deployment/api-server \
|
|
||||||
api-server=taas-api-server:v2.0.0 \
|
|
||||||
-n taas-platform
|
|
||||||
|
|
||||||
# Check rollout status
|
|
||||||
kubectl rollout status deployment/api-server -n taas-platform
|
|
||||||
|
|
||||||
# Rollback if needed
|
|
||||||
kubectl rollout undo deployment/api-server -n taas-platform
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Production Considerations
|
|
||||||
|
|
||||||
### High Availability
|
|
||||||
|
|
||||||
**MongoDB Replica Set:**
|
|
||||||
```yaml
|
|
||||||
# Use MongoDB Operator or StatefulSet
|
|
||||||
apiVersion: apps/v1
|
|
||||||
kind: StatefulSet
|
|
||||||
metadata:
|
|
||||||
name: mongodb
|
|
||||||
spec:
|
|
||||||
replicas: 3
|
|
||||||
serviceName: mongodb
|
|
||||||
# ... (see MongoDB Operator docs)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Redis Cluster:**
|
|
||||||
```bash
|
|
||||||
# Deploy Redis in cluster mode
|
|
||||||
helm install redis bitnami/redis-cluster \
|
|
||||||
--namespace taas-platform \
|
|
||||||
--set cluster.nodes=6 \
|
|
||||||
--set cluster.replicas=1
|
|
||||||
```
|
|
||||||
|
|
||||||
### Security
|
|
||||||
|
|
||||||
**Secrets Management:**
|
|
||||||
```bash
|
|
||||||
# Create Kubernetes secrets
|
|
||||||
kubectl create secret generic mongodb-secret \
|
|
||||||
--from-literal=username=admin \
|
|
||||||
--from-literal=password='STRONG_PASSWORD' \
|
|
||||||
-n taas-platform
|
|
||||||
|
|
||||||
kubectl create secret generic api-keys \
|
|
||||||
--from-literal=jwt-secret='JWT_SECRET' \
|
|
||||||
-n taas-platform
|
|
||||||
```
|
|
||||||
|
|
||||||
**Network Policies:**
|
|
||||||
```yaml
|
|
||||||
apiVersion: networking.k8s.io/v1
|
|
||||||
kind: NetworkPolicy
|
|
||||||
metadata:
|
|
||||||
name: api-server-policy
|
|
||||||
namespace: taas-platform
|
|
||||||
spec:
|
|
||||||
podSelector:
|
|
||||||
matchLabels:
|
|
||||||
app: api-server
|
|
||||||
policyTypes:
|
|
||||||
- Ingress
|
|
||||||
- Egress
|
|
||||||
ingress:
|
|
||||||
- from:
|
|
||||||
- podSelector:
|
|
||||||
matchLabels:
|
|
||||||
app: web-dashboard
|
|
||||||
ports:
|
|
||||||
- protocol: TCP
|
|
||||||
port: 8000
|
|
||||||
egress:
|
|
||||||
- to:
|
|
||||||
- podSelector:
|
|
||||||
matchLabels:
|
|
||||||
app: mongodb
|
|
||||||
ports:
|
|
||||||
- protocol: TCP
|
|
||||||
port: 27017
|
|
||||||
```
|
|
||||||
|
|
||||||
### Monitoring Stack
|
|
||||||
|
|
||||||
**Prometheus & Grafana:**
|
|
||||||
```bash
|
|
||||||
# Install using Helm
|
|
||||||
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
|
||||||
helm install prometheus prometheus-community/kube-prometheus-stack \
|
|
||||||
-n monitoring --create-namespace
|
|
||||||
```
|
|
||||||
|
|
||||||
**Application Metrics:**
|
|
||||||
- Add `/metrics` endpoint to each service
|
|
||||||
- Use Prometheus client libraries
|
|
||||||
- Create Grafana dashboards
|
|
||||||
|
|
||||||
### Backup Strategy
|
|
||||||
|
|
||||||
**MongoDB Backups:**
|
|
||||||
```bash
|
|
||||||
# Daily backups with mongodump
|
|
||||||
kubectl create cronjob mongodb-backup \
|
|
||||||
--image=mongo:7.0 \
|
|
||||||
--schedule="0 2 * * *" \
|
|
||||||
-- mongodump --uri=$MONGODB_URI --out=/backup
|
|
||||||
```
|
|
||||||
|
|
||||||
**Redis Persistence:**
|
|
||||||
```bash
|
|
||||||
# Enable AOF in Redis config
|
|
||||||
kubectl edit configmap redis-config -n taas-platform
|
|
||||||
# Set: appendonly yes
|
|
||||||
```
|
|
||||||
|
|
||||||
### Resource Limits
|
|
||||||
|
|
||||||
**Recommended limits per service:**
|
|
||||||
|
|
||||||
| Service | CPU Request | CPU Limit | Memory Request | Memory Limit |
|
|
||||||
|---------|-------------|-----------|----------------|--------------|
|
|
||||||
| API Server | 100m | 500m | 128Mi | 512Mi |
|
|
||||||
| Charging Engine | 100m | 1000m | 128Mi | 512Mi |
|
|
||||||
| Packet Gateway | 250m | 2000m | 256Mi | 1Gi |
|
|
||||||
| MongoDB | 250m | 1000m | 512Mi | 2Gi |
|
|
||||||
| Redis | 100m | 500m | 256Mi | 2Gi |
|
|
||||||
|
|
||||||
### Load Testing
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Install k6
|
|
||||||
brew install k6 # macOS
|
|
||||||
# or: sudo apt-get install k6
|
|
||||||
|
|
||||||
# Run load test
|
|
||||||
k6 run scripts/loadtest.js
|
|
||||||
```
|
|
||||||
|
|
||||||
**Sample load test script:**
|
|
||||||
```javascript
|
|
||||||
import http from 'k6/http';
|
|
||||||
import { check, sleep } from 'k6';
|
|
||||||
|
|
||||||
export const options = {
|
|
||||||
stages: [
|
|
||||||
{ duration: '2m', target: 100 }, // Ramp up
|
|
||||||
{ duration: '5m', target: 100 }, // Stay at 100 users
|
|
||||||
{ duration: '2m', target: 200 }, // Ramp to 200
|
|
||||||
{ duration: '5m', target: 200 }, // Stay at 200
|
|
||||||
{ duration: '2m', target: 0 }, // Ramp down
|
|
||||||
],
|
|
||||||
};
|
|
||||||
|
|
||||||
export default function () {
|
|
||||||
const res = http.get('http://api-server:8000/health');
|
|
||||||
check(res, { 'status is 200': (r) => r.status === 200 });
|
|
||||||
sleep(1);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Disaster Recovery
|
|
||||||
|
|
||||||
**Backup Locations:**
|
|
||||||
- MongoDB backups: S3 bucket (cross-region replication)
|
|
||||||
- Redis RDB snapshots: S3 bucket
|
|
||||||
- Configuration: Git repository
|
|
||||||
- Secrets: HashiCorp Vault or AWS Secrets Manager
|
|
||||||
|
|
||||||
**Recovery Time Objective (RTO):** <1 hour
|
|
||||||
**Recovery Point Objective (RPO):** <15 minutes
|
|
||||||
|
|
||||||
**Recovery Procedure:**
|
|
||||||
1. Spin up new Kubernetes cluster
|
|
||||||
2. Restore MongoDB from latest backup
|
|
||||||
3. Restore Redis from snapshot
|
|
||||||
4. Deploy all services from Git
|
|
||||||
5. Update DNS to point to new cluster
|
|
||||||
6. Verify functionality
|
|
||||||
|
|
||||||
### CI/CD Pipeline
|
|
||||||
|
|
||||||
**GitHub Actions example:**
|
|
||||||
```yaml
|
|
||||||
name: Deploy
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [main]
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-and-deploy:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v3
|
|
||||||
|
|
||||||
- name: Build Docker images
|
|
||||||
run: make docker-build
|
|
||||||
|
|
||||||
- name: Push to registry
|
|
||||||
run: |
|
|
||||||
docker tag taas-api-server registry.example.com/taas-api-server:${{ github.sha }}
|
|
||||||
docker push registry.example.com/taas-api-server:${{ github.sha }}
|
|
||||||
|
|
||||||
- name: Deploy to Kubernetes
|
|
||||||
run: |
|
|
||||||
kubectl set image deployment/api-server \
|
|
||||||
api-server=registry.example.com/taas-api-server:${{ github.sha }} \
|
|
||||||
-n taas-platform
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cost Optimization
|
|
||||||
|
|
||||||
**Cloud Provider Recommendations:**
|
|
||||||
- Use spot/preemptible instances for non-critical services
|
|
||||||
- Enable autoscaling to match load
|
|
||||||
- Use reserved instances for predictable workloads
|
|
||||||
- Store backups in cheaper storage classes (S3 Glacier)
|
|
||||||
|
|
||||||
**Estimated Monthly Costs (AWS):**
|
|
||||||
- 3x t3.medium (API Server): $90
|
|
||||||
- 2x t3.medium (Charging Engine): $60
|
|
||||||
- 1x t3.large (MongoDB): $75
|
|
||||||
- 1x t3.small (Redis): $19
|
|
||||||
- Load Balancer: $25
|
|
||||||
- Data transfer: Variable
|
|
||||||
- **Total**: ~$270/month (base infrastructure)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
For deployment issues:
|
|
||||||
- Check logs: `kubectl logs -f <pod-name>`
|
|
||||||
- Review events: `kubectl get events`
|
|
||||||
- Join community: [Discussions](https://github.com/taas-platform/discussions)
|
|
||||||
- Email: devops@taas-platform.com
|
|
||||||
@@ -0,0 +1,299 @@
|
|||||||
|
# Getting Started
|
||||||
|
|
||||||
|
This guide helps you get the Telecom-as-a-Service (TaaS) platform running locally and make your first API call.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Docker & Docker Compose
|
||||||
|
- Go 1.26+
|
||||||
|
- Rust 1.94+
|
||||||
|
- Node.js 22+
|
||||||
|
- MongoDB 7.0+ / PostgreSQL 15+
|
||||||
|
- Redis 7+
|
||||||
|
- pnpm
|
||||||
|
- Make
|
||||||
|
|
||||||
|
## Quick Start (Docker Compose)
|
||||||
|
|
||||||
|
The fastest path to a running platform:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/nutcas3/telecom-platform.git
|
||||||
|
cd telecom-platform
|
||||||
|
|
||||||
|
# Install deps and start core services
|
||||||
|
make install-deps
|
||||||
|
docker-compose up -d mongodb redis
|
||||||
|
make free5gc-start
|
||||||
|
docker-compose up -d api-server charging-engine carrier-connector
|
||||||
|
|
||||||
|
# Start the dashboard
|
||||||
|
make dev-ui
|
||||||
|
|
||||||
|
# Verify everything is running
|
||||||
|
make verify
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service URLs
|
||||||
|
|
||||||
|
| Service | URL |
|
||||||
|
|---------|-----|
|
||||||
|
| Web Dashboard | http://localhost:3000 |
|
||||||
|
| API Server | http://localhost:8000 |
|
||||||
|
| Charging Engine | http://localhost:8080 |
|
||||||
|
| MongoDB | mongodb://localhost:27017 |
|
||||||
|
| Redis | redis://localhost:6379 |
|
||||||
|
|
||||||
|
## Local Development (Without Docker)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Setup
|
||||||
|
chmod +x scripts/dev-setup.sh
|
||||||
|
./scripts/dev-setup.sh
|
||||||
|
make db-setup
|
||||||
|
make all
|
||||||
|
|
||||||
|
# 2. Start services (separate terminals)
|
||||||
|
./dist/api-server
|
||||||
|
./dist/carrier-connector
|
||||||
|
./target/release/charging-engine
|
||||||
|
cd apps/web-dashboard && pnpm dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
**`apps/api-server/.env`:**
|
||||||
|
```env
|
||||||
|
MONGODB_URI=mongodb://localhost:27017/free5gc
|
||||||
|
REDIS_URI=redis://localhost:6379
|
||||||
|
API_PORT=8000
|
||||||
|
GIN_MODE=debug
|
||||||
|
JWT_SECRET=your-dev-secret
|
||||||
|
```
|
||||||
|
|
||||||
|
**`apps/charging-engine/.env`:**
|
||||||
|
```env
|
||||||
|
REDIS_URI=redis://127.0.0.1/
|
||||||
|
SERVER_PORT=8080
|
||||||
|
RUST_LOG=info
|
||||||
|
```
|
||||||
|
|
||||||
|
**`apps/web-dashboard/.env.local`:**
|
||||||
|
```env
|
||||||
|
NEXT_PUBLIC_API_URL=http://localhost:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
## Your First API Call
|
||||||
|
|
||||||
|
### 1. Authenticate
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Register
|
||||||
|
curl -X POST http://localhost:8000/v1/auth/register \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"username": "admin",
|
||||||
|
"email": "[email protected]",
|
||||||
|
"password": "password123",
|
||||||
|
"first_name": "Admin",
|
||||||
|
"last_name": "User"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# Login
|
||||||
|
TOKEN=$(curl -s -X POST http://localhost:8000/v1/auth/login \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"email":"[email protected]","password":"password123"}' \
|
||||||
|
| jq -r .token)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Create an eSIM
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:8000/v1/esims \
|
||||||
|
-H "Authorization: Bearer $TOKEN" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"data_plan": "1GB",
|
||||||
|
"country_code": "US"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
Response:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"esim_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"imsi": "208930000000001",
|
||||||
|
"iccid": "8933123456789012345",
|
||||||
|
"activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
|
||||||
|
"status": "provisioned"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Check Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl http://localhost:8000/v1/esims/$ESIM_ID/usage \
|
||||||
|
-H "Authorization: Bearer $TOKEN"
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Reference
|
||||||
|
|
||||||
|
### Base URL
|
||||||
|
|
||||||
|
- Production: `https://api.taas-platform.com/v1`
|
||||||
|
- Development: `http://localhost:8000/v1`
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
All protected endpoints require a Bearer token:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "Authorization: Bearer $TOKEN" ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Core Endpoints
|
||||||
|
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/health` | System health |
|
||||||
|
| GET | `/ready` | Readiness probe |
|
||||||
|
| GET | `/live` | Liveness probe |
|
||||||
|
| POST | `/v1/auth/register` | Create user |
|
||||||
|
| POST | `/v1/auth/login` | Obtain tokens |
|
||||||
|
| POST | `/v1/auth/refresh` | Refresh access token |
|
||||||
|
| POST | `/v1/esims` | Create eSIM |
|
||||||
|
| GET | `/v1/esims/:id` | Get eSIM |
|
||||||
|
| GET | `/v1/esims/:id/usage` | Get usage |
|
||||||
|
| DELETE | `/v1/esims/:id` | Terminate eSIM |
|
||||||
|
| GET | `/v1/services` | List services |
|
||||||
|
| GET | `/v1/monitoring/metrics` | System metrics |
|
||||||
|
| GET | `/v1/monitoring/alerts` | Active alerts |
|
||||||
|
| GET | `/v1/billing/invoices` | List invoices |
|
||||||
|
| GET | `/v1/config` | Get config |
|
||||||
|
| GET | `/metrics/performance` | Performance stats |
|
||||||
|
| GET | `/ws` | WebSocket real-time updates |
|
||||||
|
|
||||||
|
### Status Codes
|
||||||
|
|
||||||
|
| Code | Meaning |
|
||||||
|
|------|---------|
|
||||||
|
| 200 | Success |
|
||||||
|
| 201 | Created |
|
||||||
|
| 400 | Bad request |
|
||||||
|
| 401 | Unauthorized |
|
||||||
|
| 403 | Forbidden |
|
||||||
|
| 404 | Not found |
|
||||||
|
| 429 | Rate limited |
|
||||||
|
| 500 | Server error |
|
||||||
|
| 503 | Service unavailable |
|
||||||
|
|
||||||
|
### Rate Limits
|
||||||
|
|
||||||
|
| Tier | Limit | Burst |
|
||||||
|
|------|-------|-------|
|
||||||
|
| Auth endpoints | 10/min | 5 |
|
||||||
|
| Read endpoints | 200/min | 50 |
|
||||||
|
| Admin endpoints | 50/min | 10 |
|
||||||
|
| Default | 100/min | 20 |
|
||||||
|
|
||||||
|
Response headers include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
|
||||||
|
|
||||||
|
## SDKs
|
||||||
|
|
||||||
|
### TypeScript
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @taas-platform/sdk
|
||||||
|
```
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { TaasClient } from '@taas-platform/sdk';
|
||||||
|
|
||||||
|
const client = new TaasClient({ apiKey: process.env.TAAS_API_KEY });
|
||||||
|
const esim = await client.esims.create({ dataPlan: '1GB', countryCode: 'US' });
|
||||||
|
const usage = await client.esims.getUsage(esim.esimId);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Go
|
||||||
|
|
||||||
|
```bash
|
||||||
|
go get github.com/taas-platform/sdk-go
|
||||||
|
```
|
||||||
|
|
||||||
|
```go
|
||||||
|
import "github.com/taas-platform/sdk-go"
|
||||||
|
|
||||||
|
client := taas.NewClient(os.Getenv("TAAS_API_KEY"))
|
||||||
|
esim, err := client.ESims.Create(&taas.CreateESIMRequest{
|
||||||
|
DataPlan: "1GB",
|
||||||
|
CountryCode: "US",
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
## Webhooks
|
||||||
|
|
||||||
|
Configure webhooks to receive real-time events:
|
||||||
|
|
||||||
|
| Event | Trigger |
|
||||||
|
|-------|---------|
|
||||||
|
| `esim.created` | New eSIM provisioned |
|
||||||
|
| `esim.activated` | eSIM activated on device |
|
||||||
|
| `usage.threshold` | 50%/75%/90% of data used |
|
||||||
|
| `usage.depleted` | Data plan exhausted |
|
||||||
|
| `esim.terminated` | eSIM terminated |
|
||||||
|
|
||||||
|
**Payload example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "usage.threshold",
|
||||||
|
"timestamp": "2026-04-01T12:00:00Z",
|
||||||
|
"data": {
|
||||||
|
"esim_id": "550e8400-...",
|
||||||
|
"threshold": 75,
|
||||||
|
"data_used": 805306368,
|
||||||
|
"data_limit": 1073741824
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make help # List all targets
|
||||||
|
make all # Build everything
|
||||||
|
make verify # Check services
|
||||||
|
make free5gc-logs # View free5GC logs
|
||||||
|
make docker-build # Build Docker images
|
||||||
|
make clean # Remove build artifacts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Services won't start
|
||||||
|
```bash
|
||||||
|
docker-compose logs [service-name]
|
||||||
|
docker-compose restart [service-name]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Port conflicts
|
||||||
|
Ensure ports 3000, 8000, 8080, 27017, 6379 are free.
|
||||||
|
|
||||||
|
### Permission issues
|
||||||
|
```bash
|
||||||
|
chmod +x scripts/*.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Database connection errors
|
||||||
|
- Verify MongoDB/PostgreSQL is running: `docker-compose ps`
|
||||||
|
- Check connection strings in `.env`
|
||||||
|
- For PostgreSQL: confirm `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` are set
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
- **Architecture**: See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for system design, RBAC, and security.
|
||||||
|
- **Operations**: See [`OPERATIONS.md`](./OPERATIONS.md) for deployment, monitoring, and performance tuning.
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
- Issues: https://github.com/nutcas3/telecom-platform/issues
|
||||||
|
- Discussions: https://github.com/nutcas3/telecom-platform/discussions
|
||||||
@@ -0,0 +1,425 @@
|
|||||||
|
# Operations
|
||||||
|
|
||||||
|
Deployment, monitoring, performance tuning, and production operations for the TaaS Platform.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Docker Deployment](#docker-deployment)
|
||||||
|
2. [Kubernetes Deployment](#kubernetes-deployment)
|
||||||
|
3. [Production Considerations](#production-considerations)
|
||||||
|
4. [Performance & Optimization](#performance--optimization)
|
||||||
|
5. [Monitoring & Alerting](#monitoring--alerting)
|
||||||
|
6. [CI/CD](#cicd)
|
||||||
|
7. [Backup & Disaster Recovery](#backup--disaster-recovery)
|
||||||
|
|
||||||
|
## Docker Deployment
|
||||||
|
|
||||||
|
### Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make docker-build
|
||||||
|
# Or individually
|
||||||
|
docker build -f deployments/docker/api-server.Dockerfile -t taas-api-server .
|
||||||
|
docker build -f deployments/docker/charging-engine.Dockerfile -t taas-charging-engine .
|
||||||
|
docker build -f deployments/docker/web-dashboard.Dockerfile -t taas-web-dashboard .
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker-compose up -d
|
||||||
|
docker-compose logs -f
|
||||||
|
docker-compose down # Stop
|
||||||
|
docker-compose down -v # Stop + remove volumes
|
||||||
|
```
|
||||||
|
|
||||||
|
### Troubleshooting
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# MongoDB
|
||||||
|
docker-compose ps mongodb
|
||||||
|
docker-compose logs mongodb
|
||||||
|
docker exec -it taas-mongodb mongosh
|
||||||
|
|
||||||
|
# Redis
|
||||||
|
docker exec -it taas-redis redis-cli ping
|
||||||
|
```
|
||||||
|
|
||||||
|
## Kubernetes Deployment
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- Kubernetes v1.28+
|
||||||
|
- `kubectl` configured
|
||||||
|
- Persistent storage provisioner
|
||||||
|
- LoadBalancer or Ingress controller
|
||||||
|
|
||||||
|
### Deploy
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl create namespace taas-platform
|
||||||
|
kubectl apply -f deployments/kubernetes/
|
||||||
|
kubectl get pods -n taas-platform
|
||||||
|
```
|
||||||
|
|
||||||
|
### Access
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl get svc api-server -n taas-platform
|
||||||
|
kubectl port-forward -n taas-platform svc/api-server 8000:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Scale
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl scale deployment api-server -n taas-platform --replicas=5
|
||||||
|
kubectl autoscale deployment api-server -n taas-platform \
|
||||||
|
--min=3 --max=10 --cpu-percent=70
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rolling Updates
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl set image deployment/api-server \
|
||||||
|
api-server=ghcr.io/nutcas3/telecom-platform/api-server:v2.0.0 \
|
||||||
|
-n taas-platform
|
||||||
|
kubectl rollout status deployment/api-server -n taas-platform
|
||||||
|
kubectl rollout undo deployment/api-server -n taas-platform # rollback
|
||||||
|
```
|
||||||
|
|
||||||
|
### Logs & Events
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl logs -f deployment/api-server -n taas-platform
|
||||||
|
kubectl describe pod <pod-name> -n taas-platform
|
||||||
|
kubectl get events -n taas-platform --sort-by='.lastTimestamp'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Production Considerations
|
||||||
|
|
||||||
|
### High Availability
|
||||||
|
|
||||||
|
**PostgreSQL / MongoDB replica sets**:
|
||||||
|
```yaml
|
||||||
|
apiVersion: apps/v1
|
||||||
|
kind: StatefulSet
|
||||||
|
metadata:
|
||||||
|
name: mongodb
|
||||||
|
spec:
|
||||||
|
replicas: 3
|
||||||
|
serviceName: mongodb
|
||||||
|
# See MongoDB Operator docs for full config
|
||||||
|
```
|
||||||
|
|
||||||
|
**Redis Cluster**:
|
||||||
|
```bash
|
||||||
|
helm install redis bitnami/redis-cluster \
|
||||||
|
--namespace taas-platform \
|
||||||
|
--set cluster.nodes=6 \
|
||||||
|
--set cluster.replicas=1
|
||||||
|
```
|
||||||
|
|
||||||
|
### Secrets Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl create secret generic db-secret \
|
||||||
|
--from-literal=username=admin \
|
||||||
|
--from-literal=password='STRONG_PASSWORD' \
|
||||||
|
-n taas-platform
|
||||||
|
|
||||||
|
kubectl create secret generic api-keys \
|
||||||
|
--from-literal=jwt-secret="$(openssl rand -base64 32)" \
|
||||||
|
-n taas-platform
|
||||||
|
```
|
||||||
|
|
||||||
|
For production, prefer HashiCorp Vault or AWS Secrets Manager over raw K8s secrets.
|
||||||
|
|
||||||
|
### Network Policies
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: networking.k8s.io/v1
|
||||||
|
kind: NetworkPolicy
|
||||||
|
metadata:
|
||||||
|
name: api-server-policy
|
||||||
|
namespace: taas-platform
|
||||||
|
spec:
|
||||||
|
podSelector:
|
||||||
|
matchLabels:
|
||||||
|
app: api-server
|
||||||
|
policyTypes: [Ingress, Egress]
|
||||||
|
ingress:
|
||||||
|
- from:
|
||||||
|
- podSelector:
|
||||||
|
matchLabels:
|
||||||
|
app: web-dashboard
|
||||||
|
ports:
|
||||||
|
- protocol: TCP
|
||||||
|
port: 8000
|
||||||
|
egress:
|
||||||
|
- to:
|
||||||
|
- podSelector:
|
||||||
|
matchLabels:
|
||||||
|
app: mongodb
|
||||||
|
ports:
|
||||||
|
- protocol: TCP
|
||||||
|
port: 27017
|
||||||
|
```
|
||||||
|
|
||||||
|
### Resource Limits
|
||||||
|
|
||||||
|
| Service | CPU Request | CPU Limit | Mem Request | Mem Limit |
|
||||||
|
|---------|------------:|----------:|------------:|----------:|
|
||||||
|
| API Server | 100m | 500m | 128Mi | 512Mi |
|
||||||
|
| Charging Engine | 100m | 1000m | 128Mi | 512Mi |
|
||||||
|
| Packet Gateway | 250m | 2000m | 256Mi | 1Gi |
|
||||||
|
| MongoDB | 250m | 1000m | 512Mi | 2Gi |
|
||||||
|
| PostgreSQL | 250m | 1000m | 512Mi | 2Gi |
|
||||||
|
| Redis | 100m | 500m | 256Mi | 2Gi |
|
||||||
|
|
||||||
|
## Performance & Optimization
|
||||||
|
|
||||||
|
### Rate Limiting
|
||||||
|
|
||||||
|
In-memory sliding window with per-IP tracking. Configured via `middleware.RateLimitByEndpoint()` in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/middleware/ratelimit.go`.
|
||||||
|
|
||||||
|
| Tier | Limit/min | Burst | Applies To |
|
||||||
|
|------|-----------|-------|------------|
|
||||||
|
| Auth | 10 | 5 | `/v1/auth/login`, `/v1/auth/register` |
|
||||||
|
| Read | 200 | 50 | `/v1/services`, `/v1/monitoring/metrics` |
|
||||||
|
| Admin | 50 | 10 | `/v1/users`, `/v1/config` |
|
||||||
|
| Default | 100 | 20 | Everything else |
|
||||||
|
|
||||||
|
### Caching
|
||||||
|
|
||||||
|
Layered in-memory LRU cache with TTL (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/cache/cache.go`):
|
||||||
|
|
||||||
|
| Namespace | TTL | Max Items | Use |
|
||||||
|
|-----------|-----|-----------|-----|
|
||||||
|
| `default` | 5 min | 1000 | General purpose |
|
||||||
|
| `users` | 10 min | 500 | User data |
|
||||||
|
| `services` | 2 min | 200 | Service info |
|
||||||
|
| `metrics` | 1 min | 1000 | Monitoring data |
|
||||||
|
|
||||||
|
```go
|
||||||
|
cache := cache.GetDefaultCache()
|
||||||
|
cache.Set("key", value, 5*time.Minute)
|
||||||
|
value, found := cache.Get("key")
|
||||||
|
```
|
||||||
|
|
||||||
|
The cached database wrapper (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/database/cached.go`) provides `CachedFind`, `CachedFirst`, `InvalidateCache`.
|
||||||
|
|
||||||
|
### Connection Pooling
|
||||||
|
|
||||||
|
Tuned in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/database/database.go:50-54`:
|
||||||
|
|
||||||
|
```go
|
||||||
|
sqlDB.SetMaxIdleConns(25) // minimum idle
|
||||||
|
sqlDB.SetMaxOpenConns(100) // maximum open
|
||||||
|
sqlDB.SetConnMaxLifetime(time.Hour)
|
||||||
|
sqlDB.SetConnMaxIdleTime(30 * time.Minute)
|
||||||
|
```
|
||||||
|
|
||||||
|
`db.PoolStats()` exposes live pool metrics for dashboards and alerts.
|
||||||
|
|
||||||
|
### Performance Middleware
|
||||||
|
|
||||||
|
Tracks response times, error rates, and slow requests (>100ms threshold). Adds:
|
||||||
|
|
||||||
|
- `X-Response-Time` header
|
||||||
|
- `X-Request-ID` correlation ID
|
||||||
|
- Security headers (CSP, HSTS, X-Frame-Options)
|
||||||
|
- Request size limit (10MB) and timeout (30s)
|
||||||
|
|
||||||
|
**Metrics endpoint**: `GET /metrics/performance`
|
||||||
|
|
||||||
|
### Performance Targets
|
||||||
|
|
||||||
|
| Metric | Target |
|
||||||
|
|--------|--------|
|
||||||
|
| API response time (p50) | <50ms |
|
||||||
|
| API response time (p99) | <100ms |
|
||||||
|
| Uptime | 99.9% |
|
||||||
|
| Error rate | <1% |
|
||||||
|
| Test coverage | >80% |
|
||||||
|
|
||||||
|
### Load Testing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
brew install k6
|
||||||
|
k6 run scripts/loadtest.js
|
||||||
|
```
|
||||||
|
|
||||||
|
Sample script:
|
||||||
|
```javascript
|
||||||
|
import http from 'k6/http';
|
||||||
|
import { check, sleep } from 'k6';
|
||||||
|
|
||||||
|
export const options = {
|
||||||
|
stages: [
|
||||||
|
{ duration: '2m', target: 100 },
|
||||||
|
{ duration: '5m', target: 100 },
|
||||||
|
{ duration: '2m', target: 200 },
|
||||||
|
{ duration: '5m', target: 200 },
|
||||||
|
{ duration: '2m', target: 0 },
|
||||||
|
],
|
||||||
|
};
|
||||||
|
|
||||||
|
export default function () {
|
||||||
|
const res = http.get('http://api-server:8000/health');
|
||||||
|
check(res, { 'status is 200': (r) => r.status === 200 });
|
||||||
|
sleep(1);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Monitoring & Alerting
|
||||||
|
|
||||||
|
### Health Checks
|
||||||
|
|
||||||
|
Three probe endpoints (`@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/monitoring/health.go`):
|
||||||
|
|
||||||
|
| Endpoint | Purpose |
|
||||||
|
|----------|---------|
|
||||||
|
| `/health` | Aggregated component health |
|
||||||
|
| `/ready` | Kubernetes readiness probe |
|
||||||
|
| `/live` | Kubernetes liveness probe |
|
||||||
|
|
||||||
|
Monitored components: **database**, **Prometheus**, **Kubernetes**, **system** (memory, goroutines, GC).
|
||||||
|
|
||||||
|
### Alert Rules
|
||||||
|
|
||||||
|
Default rules in `@/Users/nutcase/Downloads/telecom-platform-starter/apps/api-server/internal/monitoring/alerting.go`:
|
||||||
|
|
||||||
|
| Rule | Threshold | Severity |
|
||||||
|
|------|-----------|----------|
|
||||||
|
| System Health | Degraded/Unhealthy | Warning |
|
||||||
|
| High Memory | >80% | Warning |
|
||||||
|
| High Goroutines | >1000 | Warning |
|
||||||
|
| DB Connection Utilization | >80% | Warning |
|
||||||
|
|
||||||
|
### Alert Notifiers
|
||||||
|
|
||||||
|
- **WebSocket** — real-time dashboard
|
||||||
|
- **Log** — structured logs
|
||||||
|
- **Composite** — multiple channels simultaneously
|
||||||
|
|
||||||
|
### Prometheus Metrics
|
||||||
|
|
||||||
|
Key exported metrics:
|
||||||
|
- `api_requests_total` — total request count
|
||||||
|
- `esim_creations_total` — eSIMs created
|
||||||
|
- `data_usage_bytes_total` — cumulative data usage
|
||||||
|
- `charging_checks_duration_seconds` — credit check latency histogram
|
||||||
|
- `packet_gateway_packets_total` — packets processed
|
||||||
|
|
||||||
|
### Prometheus + Grafana Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
||||||
|
helm install prometheus prometheus-community/kube-prometheus-stack \
|
||||||
|
-n monitoring --create-namespace
|
||||||
|
```
|
||||||
|
|
||||||
|
### WebSocket Real-Time Events
|
||||||
|
|
||||||
|
`GET /ws` streams:
|
||||||
|
- Service status updates
|
||||||
|
- System metrics
|
||||||
|
- Alert notifications
|
||||||
|
|
||||||
|
## CI/CD
|
||||||
|
|
||||||
|
### GitHub Actions
|
||||||
|
|
||||||
|
Two workflows in `.github/workflows/`:
|
||||||
|
|
||||||
|
**`ci.yml`** — runs on every push/PR:
|
||||||
|
- Go tests with PostgreSQL service container
|
||||||
|
- `go vet` and `golangci-lint`
|
||||||
|
- Web dashboard lint + typecheck + build
|
||||||
|
- Docker image builds (on main)
|
||||||
|
- Trivy security scan
|
||||||
|
|
||||||
|
**`deploy.yml`** — runs on main pushes and version tags:
|
||||||
|
- Build + push images to GHCR
|
||||||
|
- Deploy to staging (main branch)
|
||||||
|
- Deploy to production (version tags)
|
||||||
|
|
||||||
|
Manual trigger via `workflow_dispatch` with environment input.
|
||||||
|
|
||||||
|
### Local Testing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Go tests with coverage
|
||||||
|
cd apps/api-server
|
||||||
|
go test ./... -v -race -coverprofile=coverage.out
|
||||||
|
go tool cover -html=coverage.out
|
||||||
|
|
||||||
|
# Benchmarks
|
||||||
|
go test -bench=. ./internal/middleware/
|
||||||
|
go test -bench=. ./internal/monitoring/
|
||||||
|
|
||||||
|
# Linting
|
||||||
|
golangci-lint run --timeout 5m
|
||||||
|
go vet ./...
|
||||||
|
go fix ./...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Backup & Disaster Recovery
|
||||||
|
|
||||||
|
### MongoDB Backup (CronJob)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl create cronjob mongodb-backup \
|
||||||
|
--image=mongo:7.0 \
|
||||||
|
--schedule="0 2 * * *" \
|
||||||
|
-- mongodump --uri=$MONGODB_URI --out=/backup
|
||||||
|
```
|
||||||
|
|
||||||
|
### Redis Persistence
|
||||||
|
|
||||||
|
Enable AOF for durability:
|
||||||
|
```bash
|
||||||
|
kubectl edit configmap redis-config -n taas-platform
|
||||||
|
# Set: appendonly yes
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recovery Objectives
|
||||||
|
|
||||||
|
- **RTO** (Recovery Time Objective): <1 hour
|
||||||
|
- **RPO** (Recovery Point Objective): <15 minutes
|
||||||
|
|
||||||
|
### Recovery Procedure
|
||||||
|
|
||||||
|
1. Spin up new Kubernetes cluster
|
||||||
|
2. Restore database from latest backup (cross-region replicated)
|
||||||
|
3. Restore Redis from RDB snapshot or rebuild from DB
|
||||||
|
4. Deploy all services from Git (`kubectl apply -f deployments/kubernetes/`)
|
||||||
|
5. Update DNS to new cluster
|
||||||
|
6. Run `make verify` to confirm functionality
|
||||||
|
|
||||||
|
### Backup Locations
|
||||||
|
|
||||||
|
- **MongoDB/PostgreSQL**: S3 bucket with cross-region replication
|
||||||
|
- **Redis**: S3 RDB snapshots
|
||||||
|
- **Configuration**: Git repository
|
||||||
|
- **Secrets**: HashiCorp Vault / AWS Secrets Manager
|
||||||
|
|
||||||
|
## Cost Optimization
|
||||||
|
|
||||||
|
- Use spot/preemptible instances for non-critical services
|
||||||
|
- Enable autoscaling to match load
|
||||||
|
- Reserved instances for predictable workloads
|
||||||
|
- Store old backups in S3 Glacier
|
||||||
|
|
||||||
|
**Sample monthly costs (AWS, base infrastructure)**:
|
||||||
|
- 3× t3.medium (API Server): $90
|
||||||
|
- 2× t3.medium (Charging Engine): $60
|
||||||
|
- 1× t3.large (MongoDB): $75
|
||||||
|
- 1× t3.small (Redis): $19
|
||||||
|
- Load Balancer: $25
|
||||||
|
- **Total**: ~$270/month + data transfer
|
||||||
|
|
||||||
|
## Related Docs
|
||||||
|
|
||||||
|
- [`GETTING_STARTED.md`](./GETTING_STARTED.md) — Setup and API reference
|
||||||
|
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — System design, RBAC, security
|
||||||
@@ -1,121 +0,0 @@
|
|||||||
# Quick Start Guide
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
This guide will help you get the Telecom-as-a-Service platform running in minutes.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
- Docker & Docker Compose
|
|
||||||
- Make command
|
|
||||||
- Terminal access
|
|
||||||
|
|
||||||
## 1. Initial Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone the repository (if not already done)
|
|
||||||
git clone https://github.com/nutcas3/telecom-platform.git
|
|
||||||
cd telecom-platform
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
make install-deps
|
|
||||||
```
|
|
||||||
|
|
||||||
## 2. Start Core Services
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Start databases and core services
|
|
||||||
docker-compose up -d mongodb redis
|
|
||||||
|
|
||||||
# Start free5GC core network
|
|
||||||
make free5gc-start
|
|
||||||
|
|
||||||
# Start application services
|
|
||||||
docker-compose up -d api-server charging-engine carrier-connector
|
|
||||||
```
|
|
||||||
|
|
||||||
## 3. Start Development Server
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Start web dashboard
|
|
||||||
make dev-ui
|
|
||||||
```
|
|
||||||
|
|
||||||
## 4. Verify Deployment
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Check all services status
|
|
||||||
make verify
|
|
||||||
|
|
||||||
# Test free5GC configuration
|
|
||||||
make free5gc-test
|
|
||||||
```
|
|
||||||
|
|
||||||
## 5. Access Services
|
|
||||||
|
|
||||||
- **Web Dashboard**: http://localhost:3000
|
|
||||||
- **API Server**: http://localhost:8000
|
|
||||||
- **Charging Engine**: http://localhost:8080
|
|
||||||
|
|
||||||
## 6. Common Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# View free5GC logs
|
|
||||||
make free5gc-logs
|
|
||||||
|
|
||||||
# Stop all services
|
|
||||||
docker-compose down
|
|
||||||
|
|
||||||
# Rebuild services
|
|
||||||
make docker-build
|
|
||||||
|
|
||||||
# Clean everything
|
|
||||||
make clean
|
|
||||||
```
|
|
||||||
|
|
||||||
## Service Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
Internet
|
|
||||||
|
|
|
||||||
[Web Dashboard] - [API Server] - [Carrier Connector]
|
|
||||||
| | |
|
|
||||||
| [Charging Engine] |
|
|
||||||
| | |
|
|
||||||
+-----------[free5GC Core]-----+
|
|
||||||
|
|
|
||||||
[MongoDB] [Redis]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### Services Not Starting
|
|
||||||
```bash
|
|
||||||
# Check logs
|
|
||||||
docker-compose logs [service-name]
|
|
||||||
|
|
||||||
# Restart specific service
|
|
||||||
docker-compose restart [service-name]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Port Conflicts
|
|
||||||
Ensure ports 3000, 8000, 8080, 27017, 6379 are available.
|
|
||||||
|
|
||||||
### Permission Issues
|
|
||||||
```bash
|
|
||||||
# Fix script permissions
|
|
||||||
chmod +x scripts/*.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. Explore the API documentation at `/docs/API.md`
|
|
||||||
2. Configure your first subscriber in the web dashboard
|
|
||||||
3. Test the charging engine with sample data
|
|
||||||
4. Deploy to Kubernetes using the provided manifests
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
- Check `make help` for all available commands
|
|
||||||
- Review `docs/DEPLOYMENT.md` for production deployment
|
|
||||||
- Check `todos.md` for development roadmap
|
|
||||||
Reference in New Issue
Block a user