From f5a4071b71c3d7ae476cc340c4ae8d73c4286449 Mon Sep 17 00:00:00 2001 From: "d.viti" Date: Thu, 9 Oct 2025 15:29:32 +0200 Subject: [PATCH] Improve values.yaml documentation and configuration structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enhanced values.yaml with comprehensive documentation and better organization: Documentation improvements: - Added detailed inline comments for all API7 Gateway configuration sections - Documented Ingress routing behavior (gateway vs direct service routing) - Explained Service Discovery benefits and requirements - Added detailed plugin configuration documentation (rate limiting, CORS, auth) - Included usage examples and production recommendations Configuration enhancements: - Added gateway.gatewayNamespace for better organization - Added TLS certificate configuration options (duration, renewBefore, algorithm, size) - Added ADC resource limits configuration - Improved CORS and rate limiting documentation with parameter explanations - Added consumer/authentication documentation Template updates: - Updated certificate.yaml to use configurable TLS parameters - Updated job-adc-sync.yaml to use configurable ADC resources The values.yaml now serves as comprehensive documentation for all API7 Gateway features and configuration options, making it easier for users to understand and customize their deployment. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../templates/certificate.yaml | 8 +- .../templates/job-adc-sync.yaml | 9 +- helm/api7ee-demo-k8s/values.yaml | 222 ++++++++++++------ 3 files changed, 162 insertions(+), 77 deletions(-) diff --git a/helm/api7ee-demo-k8s/templates/certificate.yaml b/helm/api7ee-demo-k8s/templates/certificate.yaml index 2114c5a..e869f6b 100644 --- a/helm/api7ee-demo-k8s/templates/certificate.yaml +++ b/helm/api7ee-demo-k8s/templates/certificate.yaml @@ -16,15 +16,15 @@ spec: - {{ . | quote }} {{- end }} privateKey: - algorithm: RSA + algorithm: {{ .Values.api7.tls.privateKey.algorithm | default "RSA" }} encoding: PKCS1 - size: 2048 + size: {{ .Values.api7.tls.privateKey.size | default 2048 }} rotationPolicy: {{ .Values.api7.tls.privateKey.rotationPolicy | default "Always" }} usages: - digital signature - key encipherment - server auth - client auth - duration: 2160h # 90 days - renewBefore: 720h # 30 days before expiry + duration: {{ .Values.api7.tls.duration | default "2160h" }} + renewBefore: {{ .Values.api7.tls.renewBefore | default "720h" }} {{- end }} diff --git a/helm/api7ee-demo-k8s/templates/job-adc-sync.yaml b/helm/api7ee-demo-k8s/templates/job-adc-sync.yaml index 047b260..d4291af 100644 --- a/helm/api7ee-demo-k8s/templates/job-adc-sync.yaml +++ b/helm/api7ee-demo-k8s/templates/job-adc-sync.yaml @@ -63,13 +63,10 @@ spec: - name: adc-config mountPath: /config readOnly: true + {{- if .Values.api7.adc.resources }} resources: - limits: - cpu: 500m - memory: 256Mi - requests: - cpu: 100m - memory: 128Mi + {{- toYaml .Values.api7.adc.resources | nindent 12 }} + {{- end }} volumes: - name: adc-config configMap: diff --git a/helm/api7ee-demo-k8s/values.yaml b/helm/api7ee-demo-k8s/values.yaml index 8c5ecb7..674b0da 100644 --- a/helm/api7ee-demo-k8s/values.yaml +++ b/helm/api7ee-demo-k8s/values.yaml @@ -126,32 +126,49 @@ api: initialDelaySeconds: 10 periodSeconds: 5 -# Ingress configuration +# Ingress Configuration +# Routes external traffic to the API7 Gateway, which then applies routing rules, +# plugins (rate limiting, CORS, authentication), and forwards to backend services ingress: enabled: true - className: "nginx" + className: "nginx" # Ingress controller class (nginx, traefik, etc.) + annotations: cert-manager.io/cluster-issuer: "cloudflare-acme-prod" + # Add custom annotations as needed: + # nginx.ingress.kubernetes.io/proxy-body-size: "10m" + # nginx.ingress.kubernetes.io/proxy-connect-timeout: "600" + # Gateway routing configuration + # All traffic is routed through API7 Gateway for advanced features: + # - Dynamic routing based on ADC configuration + # - Rate limiting (standard and AI-based) + # - CORS policies + # - Authentication/Authorization + # - Request/Response transformation hosts: - host: commandware.it paths: - path: / pathType: Prefix - # Route to API7 Gateway instead of direct service + # Route to API7 Gateway (recommended for production) gateway: - serviceName: gateway-0-1759393614-gateway - port: 80 - # Legacy configuration (commented out - use gateway instead) + serviceName: gateway-0-1759393614-gateway # API7 Gateway service name + port: 80 # Gateway HTTP port (443 for HTTPS) + namespace: api7ee # Gateway service namespace + + # Direct service routing (legacy, not recommended) + # Only use this if you need to bypass API7 Gateway # - path: / # pathType: Prefix - # service: web # Routes to web service + # service: web # Routes directly to web service # - path: /api # pathType: Prefix - # service: api # Routes to API service + # service: api # Routes directly to API service + # TLS/SSL Configuration tls: - - secretName: api7ee-tls + - secretName: api7ee-tls # Certificate secret name (created by cert-manager) hosts: - commandware.it @@ -210,111 +227,182 @@ secrets: create: false data: {} +# ============================================================================ # API7 Gateway Configuration +# ============================================================================ +# API7 Enterprise provides advanced API Gateway features including: +# - Dynamic routing with service discovery +# - Rate limiting (standard and AI-based for LLM endpoints) +# - CORS policies +# - Authentication/Authorization +# - Request/Response transformation +# - Observability and metrics api7: - enabled: true # Enable API7 ADC configuration + enabled: true # Enable API7 ADC (API Declarative Configuration) sync - # ADC Container settings + # ADC Container Settings + # ADC syncs declarative configuration from ConfigMap to API7 Gateway adc: - image: ghcr.io/api7/adc:latest + image: ghcr.io/api7/adc:latest # ADC container image imagePullPolicy: IfNotPresent - verbose: true - tlsSkipVerify: true # Required for dashboard self-signed certificate + verbose: true # Enable verbose logging for debugging + tlsSkipVerify: true # Skip TLS verification (required for self-signed dashboard certificates) + # Resources for ADC sync job + resources: + limits: + cpu: 500m + memory: 256Mi + requests: + cpu: 100m + memory: 128Mi - # API7 Gateway connection + # API7 Gateway Connection Settings gateway: - # Use the Dashboard service for API7 Enterprise admin API (HTTPS required) + # Dashboard Admin API URL (HTTPS required for API7 Enterprise) + # The dashboard service exposes the admin API on port 7443 adminUrl: https://api7ee3-0-1759339083-dashboard:7443 - adminKey: "" # Change this! - group: default - # Gateway service for traffic routing - gatewayService: gateway-0-1759393614-gateway - # Backend type (api7ee or apisix) + # Admin API key (CHANGE THIS IN PRODUCTION!) + # Obtain from: kubectl get secret -n api7ee api7ee3-0-1759339083 -o jsonpath='{.data.admin_key}' | base64 -d + adminKey: "" + + # Gateway group name (logical grouping of gateway instances) + group: default + + # Gateway service name (for traffic routing) + # This is the Kubernetes service that routes traffic to APISIX data plane + gatewayService: gateway-0-1759393614-gateway + gatewayNamespace: api7ee # Gateway service namespace + + # Backend Type + # - api7ee: API7 Enterprise (includes all enterprise features) + # - apisix: Open source APISIX (limited features) backend: api7ee - # Auto-publish routes after sync + # Auto-publish Routes + # When true, routes are automatically published after ADC sync + # When false, routes must be manually published via dashboard autoPublish: true - # Hosts for routing (using wildcard domain from existing ingress) + # Domain Hosts + # List of domains that API7 Gateway will handle + # Must match Ingress hosts for proper routing hosts: - commandware.it # TLS/SSL Configuration tls: - enabled: true - # Option 1: Use cert-manager + enabled: true # Enable HTTPS for API7 Gateway + + # Option 1: Use cert-manager (Recommended) + # Automatically provisions and renews certificates certManager: enabled: true - issuer: cloudflare-acme-prod # ClusterIssuer name - issuerKind: ClusterIssuer # or Issuer - # Private key configuration + issuer: cloudflare-acme-prod # ClusterIssuer/Issuer name + issuerKind: ClusterIssuer # ClusterIssuer or Issuer + + # Private key settings privateKey: - rotationPolicy: Always # Always or Never (cert-manager >= v1.18.0 default is Always) - # Option 2: Use existing secret - secretName: "" # Name of existing TLS secret - # Option 3: Provide certificates directly (not recommended for production) + rotationPolicy: Always # Always or Never (cert-manager >= v1.18.0) + algorithm: RSA # RSA or ECDSA + size: 2048 # Key size in bits + + # Certificate lifetime + duration: 2160h # 90 days + renewBefore: 720h # Renew 30 days before expiry + + # Option 2: Use existing TLS secret + secretName: "" # Leave empty to auto-generate name + + # Option 3: Provide certificates directly (NOT recommended for production) certificate: "" key: "" - # Service Discovery - # When enabled, API7 Gateway dynamically discovers backend Pods through Kubernetes API - # instead of using static upstream nodes. This provides: - # - Automatic scaling: New Pods are automatically added to the upstream pool - # - Health checks: Only healthy Pods receive traffic - # - Zero downtime: Automatic updates during deployments and rollouts + # ============================================================================ + # Service Discovery Configuration + # ============================================================================ + # When enabled, API7 Gateway dynamically discovers backend Pods through + # Kubernetes API instead of using static upstream node configuration. + # + # Benefits: + # - Automatic scaling: New Pods are automatically added to upstream pool + # - Health checks: Only healthy/ready Pods receive traffic + # - Zero downtime: Seamless updates during deployments and rollouts + # - No manual configuration: Eliminates need to specify Pod IPs/hostnames + # + # Requirements: + # - RBAC permissions for services, endpoints (already configured in rbac-adc.yaml) + # - Service must exist in Kubernetes serviceDiscovery: - enabled: true # Use Kubernetes service discovery + enabled: true # Enable Kubernetes service discovery namespace: "" # Leave empty to use release namespace + # ============================================================================ # API7 Plugins Configuration + # ============================================================================ + # Plugins provide advanced features like rate limiting, CORS, auth, etc. + # Each plugin can be enabled/disabled and configured independently + plugins: - # Standard Rate limiting (for /api route - per IP) + # Standard Rate Limiting + # Applied to /api routes (except /api/llm) + # Limits requests per IP address rateLimit: enabled: true - count: 100 - timeWindow: 60 - rejectedCode: 429 - keyType: "var" - key: "remote_addr" + count: 100 # Max requests per time window + timeWindow: 60 # Time window in seconds + rejectedCode: 429 # HTTP status code for rejected requests + keyType: "var" # Key type: "var", "var_combination", "constant" + key: "remote_addr" # Variable name for key (client IP) - # AI Rate limiting (for /api/llm route) + # AI Rate Limiting + # Applied to /api/llm routes + # Specialized rate limiting for LLM/AI endpoints based on token usage aiRateLimit: enabled: true - limit: 100 - timeWindow: 60 - rejectedCode: 429 - limitStrategy: "total_tokens" + limit: 100 # Max tokens per time window + timeWindow: 60 # Time window in seconds + rejectedCode: 429 # HTTP status code + limitStrategy: "total_tokens" # Strategy: "total_tokens", "input_tokens", "output_tokens" - # CORS configuration + # CORS (Cross-Origin Resource Sharing) + # Enables browser-based applications to access the API cors: enabled: true - allowOrigins: ["*"] + allowOrigins: ["*"] # Allowed origins (use specific domains in production) allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "PATCH"] - allowHeaders: ["*"] - exposeHeaders: ["*"] - maxAge: 3600 - allowCredentials: false + allowHeaders: ["*"] # Allowed headers + exposeHeaders: ["*"] # Headers exposed to browser + maxAge: 3600 # Preflight cache duration (seconds) + allowCredentials: false # Allow credentials (cookies, auth headers) # Authentication + # Key-based authentication for API access auth: - enabled: false - header: X-API-Key + enabled: false # Enable to require API keys + header: X-API-Key # Header name for API key - # Prometheus metrics + # Prometheus Metrics + # Exposes metrics for monitoring and observability prometheus: enabled: true + # Metrics endpoint: http://:9091/apisix/prometheus/metrics - # Request logging + # Request Logging + # Sends request logs to external logging service logging: - enabled: false - endpoint: http://logging-service:8080/logs - batchMaxSize: 1000 - inactiveTimeout: 5 + enabled: false # Enable to send logs to external service + endpoint: http://logging-service:8080/logs # Logging service URL + batchMaxSize: 1000 # Max batch size before sending + inactiveTimeout: 5 # Max wait time (seconds) before sending batch - # API Consumers (for authentication) + # ============================================================================ + # API Consumers + # ============================================================================ + # Consumers represent API clients with authentication credentials + # Used with auth plugin (when auth.enabled: true) consumers: - username: demo-user - apiKey: demo-key-12345 + apiKey: demo-key-12345 # Change in production! - username: admin - apiKey: admin-key-67890 + apiKey: admin-key-67890 # Change in production!