# 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.*