first commit

web/docs/api7-configuration.md

@@ -0,0 +1,615 @@
+# Gateway Configuration
+
+Complete guide for configuring routes, services, and policies in the API Gateway.
+
+## Declarative Configuration Management
+
+The gateway supports declarative configuration management using YAML files through CLI tools.
+
+### CLI Tool Installation
+
+```bash
+# Install the gateway CLI tool
+# Installation method varies by gateway solution
+
+# Verify installation
+<cli-tool> version
+```
+
+### Configuration Structure
+
+```yaml
+services:
+  - name: <service-name>
+    upstream:
+      name: <upstream-name>
+      scheme: http|https
+      type: roundrobin|chash|least_conn|ewma
+      # Option 1: Static nodes
+      nodes:
+        - host: <hostname>
+          port: <port>
+          weight: <1-100>
+      # Option 2: Service discovery
+      discovery_type: kubernetes
+      service_name: <namespace>/<service-name>:<port-name>
+    routes:
+      - name: <route-name>
+        priority: <number>
+        uris:
+          - <path-pattern>
+        hosts:
+          - <hostname>
+        methods:
+          - GET|POST|PUT|DELETE|...
+        plugins:
+          <plugin-name>:
+            <plugin-config>
+
+ssls:
+  - snis:
+      - <domain>
+    certificates:
+      - certificate: |
+          <pem-certificate>
+        key: |
+          <pem-key>
+```
+
+## Service Discovery
+
+### Kubernetes Service Discovery
+
+**Prerequisites**:
+1. Service registry configured in Dashboard
+2. RBAC permissions for gateway service account
+3. Service ports must have `name` field
+
+**Configuration**:
+
+**Via Dashboard**:
+1. **Settings → Service Registry → Add Service Registry**
+2. Select: **Kubernetes**
+3. Configure:
+   ```
+   Name: kubernetes-cluster
+   API Server: https://kubernetes.default.svc.cluster.local:443
+   Token Path: /var/run/secrets/kubernetes.io/serviceaccount/token
+   Namespace Filter: <namespace>
+   ```
+
+**RBAC Setup**:
+```bash
+kubectl create clusterrolebinding gateway-discovery \
+  --clusterrole=view \
+  --serviceaccount=<namespace>:default
+```
+
+**Service Configuration**:
+```yaml
+upstream:
+  discovery_type: kubernetes
+  service_name: <namespace>/<service-name>:<port-name>
+  # Format: <namespace>/<service-name>:<port-name>
+```
+
+### Static Nodes (No Service Discovery)
+
+```yaml
+upstream:
+  nodes:
+    - host: web-service.<namespace>.svc.cluster.local
+      port: 80
+      weight: 100
+    - host: <cluster-ip>
+      port: 80
+      weight: 100
+```
+
+## Route Configuration
+
+### Basic Route
+
+```yaml
+routes:
+  - name: web-route
+    uris:
+      - /*
+    hosts:
+      - app.domain.com
+    methods:
+      - GET
+      - POST
+    plugins:
+      redirect:
+        http_to_https: true
+```
+
+### Path-Based Routing with Priorities
+
+```yaml
+services:
+  - name: api-service
+    upstream:
+      discovery_type: kubernetes
+      service_name: <namespace>/api-service:http
+    routes:
+      - name: api-route
+        priority: 10  # Higher priority = evaluated first
+        uris:
+          - /api
+          - /api/*
+        hosts:
+          - app.domain.com
+        plugins:
+          redirect:
+            http_to_https: true
+          proxy-rewrite:
+            regex_uri:
+              - ^/api/(.*)
+              - /$1  # Strip /api prefix
+
+  - name: web-service
+    upstream:
+      discovery_type: kubernetes
+      service_name: <namespace>/web-service:http
+    routes:
+      - name: web-route
+        priority: 1  # Lower priority = fallback
+        uris:
+          - /*
+        hosts:
+          - app.domain.com
+```
+
+**Traffic Flow**:
+- `app.domain.com/api/users` → api-service (receives `/users`)
+- `app.domain.com/anything-else` → web-service
+
+### Wildcard Host Matching
+
+```yaml
+routes:
+  - name: wildcard-route
+    uris:
+      - /*
+    hosts:
+      - "*.domain.com"
+      - domain.com
+```
+
+### Multiple Hosts
+
+```yaml
+routes:
+  - name: multi-host-route
+    uris:
+      - /*
+    hosts:
+      - api.domain.com
+      - api.domain.org
+      - api.example.com
+```
+
+## Plugins
+
+### HTTP to HTTPS Redirect
+
+```yaml
+plugins:
+  redirect:
+    http_to_https: true
+```
+
+### Proxy Rewrite (Path Manipulation)
+
+**Strip prefix**:
+```yaml
+plugins:
+  proxy-rewrite:
+    regex_uri:
+      - ^/api/(.*)
+      - /$1
+```
+
+**Add prefix**:
+```yaml
+plugins:
+  proxy-rewrite:
+    uri: /backend$uri
+```
+
+**Rewrite host**:
+```yaml
+plugins:
+  proxy-rewrite:
+    host: backend-service.<namespace>.svc.cluster.local
+```
+
+### CORS Configuration
+
+```yaml
+plugins:
+  cors:
+    allow_origins: "*"
+    allow_methods: "GET,POST,PUT,DELETE,OPTIONS"
+    allow_headers: "Content-Type,Authorization"
+    allow_credential: true
+    max_age: 3600
+```
+
+### Rate Limiting
+
+**Per IP**:
+```yaml
+plugins:
+  limit-req:
+    rate: 100
+    burst: 200
+    key: remote_addr
+    rejected_code: 429
+```
+
+**Per Consumer**:
+```yaml
+plugins:
+  limit-req:
+    rate: 1000
+    burst: 2000
+    key: consumer_name
+```
+
+### Authentication
+
+**API Key**:
+```yaml
+plugins:
+  key-auth:
+    header: X-API-Key
+```
+
+**JWT**:
+```yaml
+plugins:
+  jwt-auth:
+    key: my-secret-key
+    algorithm: HS256
+```
+
+**Basic Auth**:
+```yaml
+plugins:
+  basic-auth: {}
+```
+
+### Request/Response Transformation
+
+**Add headers**:
+```yaml
+plugins:
+  proxy-rewrite:
+    headers:
+      X-Forwarded-By: "API-Gateway"
+      X-Custom-Header: "value"
+```
+
+**Remove headers**:
+```yaml
+plugins:
+  response-rewrite:
+    headers:
+      remove:
+        - X-Internal-Header
+```
+
+### Caching
+
+```yaml
+plugins:
+  proxy-cache:
+    cache_method:
+      - GET
+      - HEAD
+    cache_http_status:
+      - 200
+      - 301
+      - 302
+    cache_ttl: 3600
+```
+
+### IP Restriction
+
+**Whitelist**:
+```yaml
+plugins:
+  ip-restriction:
+    whitelist:
+      - 192.168.1.0/24
+      - 10.0.0.0/8
+```
+
+**Blacklist**:
+```yaml
+plugins:
+  ip-restriction:
+    blacklist:
+      - 203.0.113.0/24
+```
+
+## SSL/TLS Configuration
+
+### Using Existing Kubernetes Secret
+
+```yaml
+ssls:
+  - snis:
+      - "*.domain.com"
+      - domain.com
+    certificates:
+      - certificate: |
+          -----BEGIN CERTIFICATE-----
+          <CERTIFICATE_CONTENT>
+          -----END CERTIFICATE-----
+        key: |
+          -----BEGIN PRIVATE KEY-----
+          <KEY_CONTENT>
+          -----END PRIVATE KEY-----
+```
+
+### Extract from Kubernetes Secret
+
+```bash
+# Extract certificate
+kubectl get secret tls-secret -n <namespace> -o jsonpath='{.data.tls\.crt}' | base64 -d
+
+# Extract key
+kubectl get secret tls-secret -n <namespace> -o jsonpath='{.data.tls\.key}' | base64 -d
+```
+
+## Configuration Examples
+
+### Multiple Service Routes
+
+**Configuration**:
+```yaml
+services:
+  - name: frontend-service
+    upstream:
+      name: frontend-upstream
+      scheme: http
+      type: roundrobin
+      nodes:
+        - host: frontend-service.<namespace>.svc.cluster.local
+          port: 80
+          weight: 100
+    routes:
+      - name: frontend-route
+        uris:
+          - /*
+        hosts:
+          - app.domain.com
+        plugins:
+          redirect:
+            http_to_https: true
+
+      - name: root-route
+        priority: 1
+        uris:
+          - /
+          - /~*
+        hosts:
+          - domain.com
+        plugins:
+          redirect:
+            http_to_https: true
+
+  - name: api-service
+    upstream:
+      name: api-upstream
+      scheme: http
+      type: roundrobin
+      nodes:
+        - host: api-service.<namespace>.svc.cluster.local
+          port: 80
+          weight: 100
+    routes:
+      - name: api-route
+        priority: 10
+        uris:
+          - /api
+          - /api/*
+        hosts:
+          - domain.com
+        plugins:
+          redirect:
+            http_to_https: true
+          proxy-rewrite:
+            regex_uri:
+              - ^/api/(.*)
+              - /$1
+```
+
+**Traffic Flow**:
+- `app.domain.com/*` → Frontend Service
+- `domain.com/api/*` → API Service (with `/api` prefix stripped)
+- `domain.com/*` → Frontend Service
+
+## Syncing Configuration
+
+### Via CLI Tools
+
+**Sync configuration**:
+```bash
+<cli-tool> sync -f config.yaml \
+  --server <dashboard-url> \
+  --token <api-token> \
+  --gateway-group default
+```
+
+**Dump current configuration**:
+```bash
+<cli-tool> dump \
+  --server <dashboard-url> \
+  --token <api-token> > current-config.yaml
+```
+
+**Validate configuration**:
+```bash
+<cli-tool> validate -f config.yaml
+```
+
+### Publishing Routes
+
+**⚠️ Important**: Routes synced via CLI may need to be published via Dashboard.
+
+**Steps**:
+1. Access Dashboard
+2. Navigate: **Services** → Select service
+3. Go to: **Routes** tab
+4. For each route:
+   - Click: **Publish**
+   - Select: Gateway group
+   - Confirm
+
+**Route Status**:
+- **Unpublished**: Synced but not active
+- **Published**: Active on gateway
+
+## Advanced Configurations
+
+### Multi-Environment Setup
+
+**Development Gateway Group**:
+```bash
+# Sync to dev gateway group
+<cli-tool> sync -f config.yaml \
+  --gateway-group dev \
+  --server <dashboard-url> \
+  --token <token>
+```
+
+**Production Gateway Group**:
+```bash
+# Sync to prod gateway group
+<cli-tool> sync -f config.yaml \
+  --gateway-group prod \
+  --server <dashboard-url> \
+  --token <token>
+```
+
+### Health Checks
+
+```yaml
+upstream:
+  checks:
+    active:
+      http_path: /health
+      healthy:
+        interval: 5
+        successes: 2
+      unhealthy:
+        interval: 5
+        http_failures: 3
+```
+
+### Retry Policy
+
+```yaml
+upstream:
+  retries: 3
+  retry_timeout: 10
+  pass_host: pass  # or rewrite, node
+```
+
+### Circuit Breaker
+
+```yaml
+plugins:
+  api-breaker:
+    break_response_code: 503
+    max_breaker_sec: 300
+    unhealthy:
+      http_statuses: [500, 503]
+      failures: 3
+    healthy:
+      http_statuses: [200]
+      successes: 3
+```
+
+## Monitoring Route Performance
+
+### View Metrics in Dashboard
+
+1. Navigate: **Monitoring** → **Routes**
+2. Select route to view:
+   - Request rate (req/s)
+   - Latency percentiles (P50, P95, P99)
+   - Error rate
+   - Status code distribution
+
+### Prometheus Metrics
+
+Access Prometheus:
+```bash
+kubectl port-forward -n <namespace> svc/prometheus-server 9090:9090
+```
+
+**Useful Queries**:
+```promql
+# Request rate by route
+sum(rate(http_requests_total[5m])) by (route)
+
+# Latency P95
+histogram_quantile(0.95, sum(rate(http_latency_bucket[5m])) by (le, route))
+
+# Error rate
+sum(rate(http_requests_total{code=~"5.."}[5m])) by (route)
+```
+
+## Troubleshooting
+
+### Route Returns 404
+
+**Check**:
+1. ✅ Route is published in Dashboard
+2. ✅ Host header matches route configuration exactly
+3. ✅ Path matches URI pattern
+4. ✅ Gateway pods are healthy
+
+```bash
+# Check gateway logs
+kubectl logs -n <namespace> -l app.kubernetes.io/name=gateway --tail=100
+```
+
+### Service Discovery Not Working
+
+**Check**:
+1. ✅ Service registry configured in Dashboard
+2. ✅ Service registry status is "Connected"
+3. ✅ RBAC permissions granted
+4. ✅ Service has named ports
+
+```bash
+# Verify service
+kubectl get svc -n <namespace> <service-name>
+
+# Check endpoints
+kubectl get endpoints -n <namespace> <service-name>
+```
+
+### Configuration Not Applied
+
+**Check**:
+1. ✅ CLI sync succeeded
+2. ✅ Routes are published
+3. ✅ Gateway group matches
+
+```bash
+# Dump and compare
+<cli-tool> dump --server <URL> --token <TOKEN> > current.yaml
+diff config.yaml current.yaml
+```
+
+---
+
+*Complete configuration reference for API Gateway infrastructure.*