Improve values.yaml documentation and configuration structure

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 <noreply@anthropic.com>

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
+  duration: {{ .Values.api7.tls.duration | default "2160h" }}
-  renewBefore: 720h  # 30 days before expiry
+  renewBefore: {{ .Values.api7.tls.renewBefore | default "720h" }}
 {{- end }}

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:
+            {{- toYaml .Values.api7.adc.resources | nindent 12 }}
-              cpu: 500m
+          {{- end }}
-              memory: 256Mi
-            requests:
-              cpu: 100m
-              memory: 128Mi
       volumes:
         - name: adc-config
           configMap:

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
+            serviceName: gateway-0-1759393614-gateway # API7 Gateway service name
-            port: 80
+            port: 80 # Gateway HTTP port (443 for HTTPS)
-        # Legacy configuration (commented out - use gateway instead)
+            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
+    verbose: true # Enable verbose logging for debugging
-    tlsSkipVerify: true # Required for dashboard self-signed certificate
+    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
+    enabled: true # Enable HTTPS for API7 Gateway
-    # Option 1: Use cert-manager
+
+    # Option 1: Use cert-manager (Recommended)
+    # Automatically provisions and renews certificates
     certManager:
       enabled: true
-      issuer: cloudflare-acme-prod # ClusterIssuer name
+      issuer: cloudflare-acme-prod # ClusterIssuer/Issuer name
-      issuerKind: ClusterIssuer # or Issuer
+      issuerKind: ClusterIssuer # ClusterIssuer or Issuer
-    # Private key configuration
+
+    # Private key settings
     privateKey:
-      rotationPolicy: Always # Always or Never (cert-manager >= v1.18.0 default is Always)
+      rotationPolicy: Always # Always or Never (cert-manager >= v1.18.0)
-    # Option 2: Use existing secret
+      algorithm: RSA # RSA or ECDSA
-    secretName: "" # Name of existing TLS secret
+      size: 2048 # Key size in bits
-    # Option 3: Provide certificates directly (not recommended for production)
+
+    # 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
+  # Service Discovery Configuration
-  # instead of using static upstream nodes. This provides:
+  # ============================================================================
-  # - Automatic scaling: New Pods are automatically added to the upstream pool
+  # When enabled, API7 Gateway dynamically discovers backend Pods through
-  # - Health checks: Only healthy Pods receive traffic
+  # Kubernetes API instead of using static upstream node configuration.
-  # - Zero downtime: Automatic updates during deployments and rollouts
+  #
+  # 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
+      count: 100 # Max requests per time window
-      timeWindow: 60
+      timeWindow: 60 # Time window in seconds
-      rejectedCode: 429
+      rejectedCode: 429 # HTTP status code for rejected requests
-      keyType: "var"
+      keyType: "var" # Key type: "var", "var_combination", "constant"
-      key: "remote_addr"
+      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
+      limit: 100 # Max tokens per time window
-      timeWindow: 60
+      timeWindow: 60 # Time window in seconds
-      rejectedCode: 429
+      rejectedCode: 429 # HTTP status code
-      limitStrategy: "total_tokens"
+      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: ["*"]
+      allowHeaders: ["*"] # Allowed headers
-      exposeHeaders: ["*"]
+      exposeHeaders: ["*"] # Headers exposed to browser
-      maxAge: 3600
+      maxAge: 3600 # Preflight cache duration (seconds)
-      allowCredentials: false
+      allowCredentials: false # Allow credentials (cookies, auth headers)
 
     # Authentication
+    # Key-based authentication for API access
     auth:
-      enabled: false
+      enabled: false # Enable to require API keys
-      header: X-API-Key
+      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://<gateway>:9091/apisix/prometheus/metrics
 
-    # Request logging
+    # Request Logging
+    # Sends request logs to external logging service
     logging:
-      enabled: false
+      enabled: false # Enable to send logs to external service
-      endpoint: http://logging-service:8080/logs
+      endpoint: http://logging-service:8080/logs # Logging service URL
-      batchMaxSize: 1000
+      batchMaxSize: 1000 # Max batch size before sending
-      inactiveTimeout: 5
+      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!