demos/api7-demo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move documentation to MkDocs and add comprehensive guides
All checks were successful
Helm Chart Build / lint-only (push) Has been skipped
Details
Helm Chart Build / build-helm (push) Successful in 9s
Details
Build and Deploy / build-api (push) Successful in 44s
Details
Build and Deploy / build-web (push) Successful in 1m10s
Details

Browse Source 
Reorganized documentation to be part of MkDocs site with three new
comprehensive guides covering API7 Gateway configuration.

Changes:

1. Documentation Structure:
   - Moved SECRET-MANAGEMENT.md from helm/ to web/docs/
   - Created service-discovery.md with complete guide
   - Created ingress-routing.md with routing architecture
   - Moved externalsecret examples to web/docs/examples/

2. New Documentation - Service Discovery:
   - How service discovery works (architecture diagram)
   - Benefits vs static configuration
   - Configuration examples
   - RBAC requirements
   - Advanced use cases (auto-scaling, rolling updates)
   - Load balancing algorithms
   - Monitoring and troubleshooting
   - Best practices

3. New Documentation - Ingress & Routing:
   - Complete traffic flow architecture
   - Ingress configuration explained
   - Gateway routing rules and priority
   - URI matching patterns (prefix, exact, regex)
   - TLS/SSL with cert-manager
   - Advanced routing scenarios:
     * Multiple domains
     * Path-based routing
     * Header-based routing
     * Method-based routing
   - Configuration examples (microservices, WebSocket, canary)
   - Monitoring and debugging
   - Troubleshooting common issues

4. MkDocs Navigation:
   - Updated mkdocs.yml with new pages in Configuration section
   - Added: Ingress & Routing
   - Added: Service Discovery
   - Added: Secret Management

5. Examples Directory:
   - Created web/docs/examples/ for configuration examples
   - Moved ExternalSecret examples with multiple providers:
     * AWS Secrets Manager
     * HashiCorp Vault
     * Azure Key Vault
     * GCP Secret Manager

All documentation now integrated into MkDocs site with proper
navigation, cross-references, and Material theme styling.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
d.viti
2025-10-09 16:00:29 +02:00
parent 694709ae9a
commit c5b597c7c1
6 changed files with 1118 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
helm/api7ee-demo-k8s/SECRET-MANAGEMENT.md
View File

@@ -1,233 +0,0 @@
# 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/)

93
helm/api7ee-demo-k8s/templates/externalsecret-api7.yaml.example
View File

@@ -1,93 +0,0 @@
# Example ExternalSecret for API7 Gateway credentials
# This file is not deployed by default - it serves as an example.
#
# To use External Secrets Operator:
# 1. Install External Secrets Operator in your cluster
# 2. Configure a SecretStore (e.g., AWS Secrets Manager, Vault, etc.)
# 3. Rename this file to remove .example extension
# 4. Set api7.gateway.existingSecret to the secret name below
# 5. Adjust the backend configuration to match your SecretStore
#
# Documentation: https://external-secrets.io/
{{- if false }} # Change to 'if .Values.api7.gateway.useExternalSecret' to enable
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: {{ include "api7ee.fullname" . }}-api7-admin-external
labels:
{{- include "api7ee.labels" . | nindent 4 }}
app.kubernetes.io/component: api7
spec:
# Refresh interval for fetching secrets from external provider
refreshInterval: 1h
# Reference to SecretStore
secretStoreRef:
name: vault-backend # Name of your SecretStore
kind: SecretStore # or ClusterSecretStore
# Target Secret configuration
target:
name: {{ include "api7ee.fullname" . }}-api7-admin
creationPolicy: Owner
template:
type: Opaque
data:
# Map external secret keys to Kubernetes secret keys
admin-url: "{{ `{{ .adminUrl }}` }}"
admin-key: "{{ `{{ .adminKey }}` }}"
gateway-group: "{{ `{{ .group }}` }}"
# Data to fetch from external provider
data:
- secretKey: adminUrl
remoteRef:
key: api7/gateway # Path in external secret store
property: admin_url # Property name
- secretKey: adminKey
remoteRef:
key: api7/gateway
property: admin_key
- secretKey: group
remoteRef:
key: api7/gateway
property: gateway_group
---
# Example for AWS Secrets Manager
# apiVersion: external-secrets.io/v1beta1
# kind: SecretStore
# metadata:
# name: aws-secretsmanager
# spec:
# provider:
# aws:
# service: SecretsManager
# region: us-east-1
# auth:
# jwt:
# serviceAccountRef:
# name: external-secrets-sa
---
# Example for HashiCorp Vault
# apiVersion: external-secrets.io/v1beta1
# kind: SecretStore
# metadata:
# name: vault-backend
# spec:
# provider:
# vault:
# server: "https://vault.example.com"
# path: "secret"
# version: "v2"
# auth:
# kubernetes:
# mountPath: "kubernetes"
# role: "api7-role"
# serviceAccountRef:
# name: {{ include "api7ee.serviceAccountName" . }}
{{- end }}