616 lines
11 KiB
Markdown
616 lines
11 KiB
Markdown
# 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.*
|