api7-demo/web/docs/secret-management.md

# Secret Management for API7 Gateway

This document explains how to manage API7 Gateway credentials securely.

## Overview

API7 Gateway requires the following credentials:
- **Admin URL**: Dashboard admin API endpoint
- **Admin Key**: Authentication token for admin API
- **Gateway Group**: Logical grouping of gateway instances

## Configuration Options

### Option 1: Inline Configuration (Development Only)

**⚠️ NOT RECOMMENDED for production**

Credentials are stored directly in `values.yaml`:

```yaml
api7:
  gateway:
    existingSecret: ""  # Leave empty
    adminUrl: https://api7ee3-0-1759339083-dashboard:7443
    adminKey: "your-admin-key"
    group: default
```

The chart will create a Kubernetes Secret automatically.

### Option 2: Existing Secret (Recommended)

**✅ RECOMMENDED for production**

Create a Secret manually or using a secret management tool, then reference it:

```yaml
api7:
  gateway:
    existingSecret: "api7-credentials"  # Name of your secret
    existingSecretKeys:
      adminUrl: admin-url
      adminKey: admin-key
      group: gateway-group
```

#### Create Secret Manually

```bash
kubectl create secret generic api7-credentials \
  --from-literal=admin-url=https://api7ee3-0-1759339083-dashboard:7443 \
  --from-literal=admin-key=YOUR_ADMIN_KEY \
  --from-literal=gateway-group=default \
  -n api7ee
```

#### Get Admin Key from API7 Enterprise

```bash
# Get admin key from API7 Enterprise installation
kubectl get secret -n api7ee api7ee3-0-1759339083 \
  -o jsonpath='{.data.admin_key}' | base64 -d
```

### Option 3: External Secrets Operator

**✅ RECOMMENDED for production with centralized secret management**

Use External Secrets Operator to sync secrets from external providers like:
- AWS Secrets Manager
- HashiCorp Vault
- Azure Key Vault
- GCP Secret Manager
- And more...

#### Step 1: Install External Secrets Operator

```bash
helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets -n external-secrets-system --create-namespace
```

#### Step 2: Configure SecretStore

Example for HashiCorp Vault:

```yaml
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
  namespace: api7ee
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      path: "secret"
      version: "v2"
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "api7-role"
          serviceAccountRef:
            name: api7ee-demo-api7ee-demo-k8s
```

#### Step 3: Create ExternalSecret

See `templates/externalsecret-api7.yaml.example` for a complete example.

```yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api7-credentials-external
  namespace: api7ee
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: SecretStore
  target:
    name: api7-credentials
    creationPolicy: Owner
  data:
    - secretKey: admin-url
      remoteRef:
        key: api7/gateway
        property: admin_url
    - secretKey: admin-key
      remoteRef:
        key: api7/gateway
        property: admin_key
    - secretKey: gateway-group
      remoteRef:
        key: api7/gateway
        property: gateway_group
```

#### Step 4: Configure Helm Values

```yaml
api7:
  gateway:
    existingSecret: "api7-credentials"  # Created by ExternalSecret
```

## Secret Keys

The Secret must contain these keys (default names):

| Key | Description | Example |
|-----|-------------|---------|
| `admin-url` | Dashboard admin API URL | `https://api7ee3-0-1759339083-dashboard:7443` |
| `admin-key` | Dashboard admin API key | `edd1c9f034335f136f87ad84b625c8f1` |
| `gateway-group` | Gateway group name | `default` |

### Custom Key Names

If your Secret uses different key names, configure them:

```yaml
api7:
  gateway:
    existingSecret: "my-custom-secret"
    existingSecretKeys:
      adminUrl: dashboard_url    # Your custom key name
      adminKey: api_token        # Your custom key name
      group: group_name          # Your custom key name
```

## Security Best Practices

1. **Never commit secrets to Git**
   - Use `.gitignore` for values files containing secrets
   - Use secret management tools for production

2. **Use RBAC to restrict secret access**
   - Limit which ServiceAccounts can read secrets
   - Use namespace isolation

3. **Rotate credentials regularly**
   - Update admin keys periodically
   - Use External Secrets Operator for automatic rotation

4. **Enable audit logging**
   - Monitor secret access in Kubernetes audit logs
   - Alert on unauthorized access attempts

5. **Use encryption at rest**
   - Enable Kubernetes secret encryption
   - Use external KMS for additional security

## Troubleshooting

### Secret not found

```bash
# Check if secret exists
kubectl get secret -n api7ee

# Describe the secret
kubectl describe secret api7-credentials -n api7ee
```

### Invalid credentials

```bash
# View secret data (base64 encoded)
kubectl get secret api7-credentials -n api7ee -o yaml

# Decode and verify values
kubectl get secret api7-credentials -n api7ee \
  -o jsonpath='{.data.admin-key}' | base64 -d
```

### ADC sync job fails

```bash
# Check job logs
kubectl logs -n api7ee job/api7ee-demo-api7ee-demo-k8s-adc-sync

# Common issues:
# - Wrong admin URL (check DNS resolution)
# - Invalid admin key (verify key is correct)
# - TLS certificate issues (use tlsSkipVerify: true for self-signed)
```

## References

- [External Secrets Operator Documentation](https://external-secrets.io/)
- [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/)
- [API7 Enterprise Documentation](https://docs.api7.ai/enterprise/)