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:

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:

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

Create Secret Manually

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

# 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

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:

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.

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

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:

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

# Check if secret exists
kubectl get secret -n api7ee

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

Invalid credentials

# 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

# 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
• Kubernetes Secrets
• API7 Enterprise Documentation