Skip to content

Commit 9e29a62

Browse files
sarthypartysarthyparty
committed
add simplified architecture
1 parent bb036ef commit 9e29a62

File tree

4 files changed

+596
-0
lines changed

4 files changed

+596
-0
lines changed

‎docs/architecture/README.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# NGINX Gateway Fabric Architecture
2+
3+
This guide explains how NGINX Gateway Fabric works in simple terms.
4+
5+
## What is NGINX Gateway Fabric?
6+
7+
NGINX Gateway Fabric (NGF) turns Kubernetes Gateway API resources into working traffic routing. It has two main parts:
8+
9+
- **Control Plane**: Watches Kubernetes and creates NGINX configs
10+
- **Data Plane**: NGINX servers that handle your traffic
11+
12+
## Control Plane vs Data Plane
13+
14+
### Control Plane
15+
16+
The **Control Plane** is the brain:
17+
18+
- Watches for Gateway and Route changes in Kubernetes
19+
- Converts Gateway API configs into NGINX configs
20+
- Manages NGINX instances
21+
- Handles certificates and security
22+
23+
### Data Plane
24+
25+
The **Data Plane** does the work:
26+
27+
- Receives incoming traffic from users
28+
- Routes traffic to your apps
29+
- Handles SSL/TLS termination
30+
- Applies load balancing and security rules
31+
32+
## Architecture Diagrams
33+
34+
### [Configuration Flow](./configuration-flow.md)
35+
36+
How Gateway API resources become NGINX configurations
37+
38+
### [Traffic Flow](./traffic-flow.md)
39+
40+
How user requests travel through the system
41+
42+
### [Gateway Lifecycle](./gateway-lifecycle.md)
43+
44+
What happens when you create or update a Gateway
45+
46+
## Key Concepts
47+
48+
### Separation of Concerns
49+
50+
- Control and data planes run in **separate pods**
51+
- They communicate over **secure gRPC**
52+
- Each can **scale independently**
53+
- **Different security permissions** for each
54+
55+
### Gateway API Integration
56+
57+
NGF implements these Kubernetes Gateway API resources:
58+
59+
- **Gateway**: Defines entry points for traffic
60+
- **HTTPRoute**: Defines HTTP routing rules
61+
- **GRPCRoute**: Defines gRPC routing rules
62+
- **TLSRoute**: Defines TLS routing rules
63+
64+
### NGINX Agent
65+
66+
- **NGINX Agent v3** connects control and data planes
67+
- Runs inside each NGINX pod
68+
- Downloads configs from control plane
69+
- Manages NGINX lifecycle (start, reload, monitor)
70+
71+
## Security Model
72+
73+
### Control Plane Security
74+
75+
- **Full Kubernetes API access** (to watch resources)
76+
- **gRPC server** for data plane connections
77+
- **Certificate management** for secure communication
78+
79+
### Data Plane Security
80+
81+
- **No Kubernetes API access** (security isolation)
82+
- **gRPC client** connects to control plane
83+
- **Minimal permissions** (principle of least privilege)

‎docs/architecture/configuration-flow.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Configuration Flow
2+
3+
This diagram shows how Gateway API resources become NGINX configurations.
4+
5+
## Simple Overview
6+
7+
```mermaid
8+
%%{init: {'theme':'dark', 'themeVariables': {'fontSize': '16px', 'darkMode': true, 'primaryColor': '#4f46e5', 'primaryTextColor': '#e5e7eb', 'primaryBorderColor': '#6b7280', 'lineColor': '#9ca3af', 'secondaryColor': '#1f2937', 'tertiaryColor': '#374151', 'background': '#111827', 'mainBkg': '#1f2937', 'secondBkg': '#374151', 'tertiaryTextColor': '#d1d5db'}}}%%
9+
graph TB
10+
%% User Actions
11+
USER[👤 User] --> K8S
12+
13+
%% Kubernetes API Layer
14+
subgraph "Kubernetes API"
15+
K8S[🔵 API Server]
16+
GW[Gateway]
17+
ROUTE[HTTPRoute]
18+
SVC[Service]
19+
end
20+
21+
%% Control Plane
22+
subgraph "Control Plane Pod"
23+
NGF[🎯 NGF Controller]
24+
end
25+
26+
%% Data Plane
27+
subgraph "Data Plane Pod"
28+
AGENT[🔧 NGINX Agent]
29+
NGINX[🌐 NGINX]
30+
CONF[nginx.conf]
31+
end
32+
33+
%% Flow
34+
K8S --> NGF
35+
GW --> NGF
36+
ROUTE --> NGF
37+
SVC --> NGF
38+
39+
NGF --> AGENT
40+
AGENT --> CONF
41+
CONF --> NGINX
42+
43+
%% Dark-friendly styling
44+
style USER fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#1f2937
45+
style NGF fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#ffffff
46+
style NGINX fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff
47+
style K8S fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#ffffff
48+
```
49+
50+
## Step-by-Step Process
51+
52+
### 1. User Creates Resources
53+
54+
```yaml
55+
# User applies Gateway API resources
56+
apiVersion: gateway.networking.k8s.io/v1
57+
kind: Gateway
58+
metadata:
59+
name: my-gateway
60+
```
61+
62+
### 2. Kubernetes Stores Resources
63+
64+
- Gateway, HTTPRoute, Service resources stored in etcd
65+
- Kubernetes API Server notifies watchers of changes
66+
67+
### 3. NGF Controller Processes Changes
68+
69+
```text
70+
NGF Controller:
71+
├── Watches Gateway API resources
72+
├── Validates configurations
73+
├── Builds internal config graph
74+
└── Generates NGINX configuration
75+
```
76+
77+
### 4. Configuration Sent to Data Plane
78+
79+
```text
80+
Control Plane → Data Plane:
81+
├── gRPC connection (secure)
82+
├── nginx.conf file contents
83+
├── SSL certificates
84+
└── Other config files
85+
```
86+
87+
### 5. NGINX Agent Updates Configuration
88+
89+
```text
90+
NGINX Agent:
91+
├── Receives config from control plane
92+
├── Validates NGINX syntax
93+
├── Writes files to disk
94+
├── Tests configuration
95+
└── Reloads NGINX (if valid)
96+
```
97+
98+
## Detailed Configuration Flow
99+
100+
```mermaid
101+
%%{init: {'theme':'dark', 'themeVariables': {'fontSize': '14px', 'darkMode': true, 'primaryColor': '#4f46e5', 'primaryTextColor': '#e5e7eb', 'primaryBorderColor': '#6b7280', 'lineColor': '#9ca3af', 'secondaryColor': '#1f2937', 'tertiaryColor': '#374151', 'background': '#111827', 'actorBkg': '#374151', 'actorBorder': '#6b7280', 'actorTextColor': '#e5e7eb', 'activationBkgColor': '#4f46e5', 'activationBorderColor': '#3730a3', 'signalColor': '#9ca3af', 'signalTextColor': '#e5e7eb', 'labelBoxBkgColor': '#1f2937', 'labelBoxBorderColor': '#6b7280', 'labelTextColor': '#e5e7eb', 'loopTextColor': '#e5e7eb', 'noteBkgColor': '#374151', 'noteBorderColor': '#6b7280', 'noteTextColor': '#e5e7eb'}}}%%
102+
sequenceDiagram
103+
participant User
104+
participant API as K8s API
105+
participant NGF as NGF Controller
106+
participant Agent as NGINX Agent
107+
participant NGINX
108+
109+
User->>API: Apply Gateway/Route
110+
API->>NGF: Watch notification
111+
NGF->>NGF: Validate resources
112+
NGF->>NGF: Build config graph
113+
NGF->>NGF: Generate nginx.conf
114+
NGF->>Agent: Send config (gRPC)
115+
Agent->>Agent: Write config files
116+
Agent->>NGINX: Test config
117+
Agent->>NGINX: Reload (if valid)
118+
Agent->>NGF: Report status
119+
NGF->>API: Update resource status
120+
```
121+
122+
## What Gets Generated?
123+
124+
### NGINX Configuration Files
125+
126+
- **nginx.conf**: Main configuration
127+
- **servers.conf**: Virtual server definitions
128+
- **upstreams.conf**: Backend service definitions
129+
- **maps.conf**: Request routing maps
130+
131+
### Example Generated Config
132+
133+
```nginx
134+
# Generated from Gateway API resources
135+
server {
136+
listen 80;
137+
server_name api.example.com;
138+
139+
location /users {
140+
proxy_pass http://user-service;
141+
}
142+
143+
location /orders {
144+
proxy_pass http://order-service;
145+
}
146+
}
147+
```
148+
149+
## Error Handling
150+
151+
### Invalid Configuration
152+
153+
1. **NGF validates** Gateway API resources
154+
2. **NGINX Agent tests** generated config
155+
3. **Rollback** if configuration is invalid
156+
4. **Status updates** report errors to Kubernetes
157+
158+
### Recovery Process
159+
160+
- Keep last known good configuration
161+
- Report errors in resource status
162+
- Retry configuration updates
163+
- Graceful degradation when possible

0 commit comments

Comments
 (0)