Move all documentation to web/docs for MkDocs integration
Moved all documentation files into web/docs/ directory for proper MkDocs integration and updated navigation structure. Changes: ======== 1. Documentation Structure: - Moved SWAGGER-WEB-UPDATE.md → web/docs/swagger-documentation.md - Moved ARGOCD-VALUES-UPDATE.md → web/docs/argocd-values-guide.md - Formatted both files with MkDocs frontmatter and structure 2. MkDocs Navigation (web/mkdocs.yml): - Updated site_url to https://commandware.it/docs - Added new section "API Documentation" with Swagger guide - Added "ArgoCD Values Guide" to Configuration section - Enhanced markdown extensions: * Added mermaid diagram support * Added task lists * Added emoji support * Added code annotations - Added navigation features (instant, tabs, sections) - Added tags plugin - Improved copyright notice 3. Swagger Documentation (web/docs/swagger-documentation.md): - Complete guide to Swagger UI, ReDoc, and OpenAPI - Access instructions via web interface and direct links - API overview with architecture diagram - Detailed endpoint documentation for all groups: * Root (/) * Health (/health, /ready) * Items CRUD (/items/*) * Users (/users/*) * LLM (/llm/*) - Interactive testing examples - OpenAPI specification download instructions - Tools integration (Postman, Insomnia, OpenAPI Generator) - Cross-references to other documentation pages 4. ArgoCD Values Guide (web/docs/argocd-values-guide.md): - Comprehensive guide for updating values.yaml in ArgoCD - All modifications explained (before/after) - Step-by-step application instructions - Verification commands - Security best practices New MkDocs Navigation: ====================== - Home - Getting Started - Architecture - Overview - Kubernetes Resources - Configuration - API7 Gateway - Ingress & Routing - Service Discovery - Secret Management - ArgoCD Values Guide ← NEW - CI/CD Pipeline - API Documentation ← NEW SECTION - Swagger & OpenAPI - Troubleshooting All documentation is now centralized in web/docs/ and accessible through MkDocs at https://commandware.it/docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
d.viti
274
web/docs/argocd-values-guide.md
Normal file
274
web/docs/argocd-values-guide.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# ArgoCD Values Update Guide
|
||||
|
||||
Questo documento descrive le modifiche da applicare al `values.yaml` in ArgoCD.
|
||||
|
||||
## 📋 Modifiche Principali
|
||||
|
||||
### 1. Service Discovery - DISABILITATO
|
||||
|
||||
**Prima:**
|
||||
```yaml
|
||||
api7:
|
||||
serviceDiscovery:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
**Dopo:**
|
||||
```yaml
|
||||
api7:
|
||||
serviceDiscovery:
|
||||
enabled: false # Disabled until Service Registry is configured in API7 Dashboard
|
||||
namespace: ""
|
||||
```
|
||||
|
||||
**Motivo:** Service discovery richiede la configurazione di un Service Registry nel Dashboard API7 Enterprise. Finché non viene configurato, ADC sync fallisce con errore `service registry not found`.
|
||||
|
||||
---
|
||||
|
||||
### 2. Existing Secret - CONFIGURATO
|
||||
|
||||
**Prima:**
|
||||
```yaml
|
||||
api7:
|
||||
gateway:
|
||||
existingSecret: ""
|
||||
```
|
||||
|
||||
**Dopo:**
|
||||
```yaml
|
||||
api7:
|
||||
gateway:
|
||||
# Use existing secret for production (recommended)
|
||||
# The secret api7-credentials already exists with the correct admin key
|
||||
existingSecret: "api7-credentials"
|
||||
existingSecretKeys:
|
||||
adminUrl: admin-url
|
||||
adminKey: admin-key
|
||||
group: gateway-group
|
||||
```
|
||||
|
||||
**Motivo:** Il Secret `api7-credentials` esiste già nel namespace `api7ee` con la chiave admin corretta. Usarlo evita di creare un nuovo Secret vuoto.
|
||||
|
||||
---
|
||||
|
||||
### 3. Gateway Namespace - AGGIUNTO
|
||||
|
||||
**Prima:**
|
||||
```yaml
|
||||
api7:
|
||||
gateway:
|
||||
gatewayService: gateway-0-1759393614-gateway
|
||||
```
|
||||
|
||||
**Dopo:**
|
||||
```yaml
|
||||
api7:
|
||||
gateway:
|
||||
gatewayService: gateway-0-1759393614-gateway
|
||||
gatewayNamespace: api7ee
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. ADC Resources - CONFIGURATE
|
||||
|
||||
```yaml
|
||||
api7:
|
||||
adc:
|
||||
resources:
|
||||
limits:
|
||||
cpu: 500m
|
||||
memory: 256Mi
|
||||
requests:
|
||||
cpu: 100m
|
||||
memory: 128Mi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Ingress Configuration - AGGIORNATA
|
||||
|
||||
**Prima:**
|
||||
```yaml
|
||||
ingress:
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/rewrite-target: /
|
||||
hosts:
|
||||
- host: commandware.it
|
||||
paths:
|
||||
- path: /
|
||||
gateway:
|
||||
serviceName: gateway-0-1759393614-gateway
|
||||
port: 80
|
||||
- path: /api
|
||||
gateway:
|
||||
serviceName: gateway-0-1759393614-gateway
|
||||
port: 80
|
||||
tls:
|
||||
- secretName: api7ee-demo-tls
|
||||
```
|
||||
|
||||
**Dopo:**
|
||||
```yaml
|
||||
ingress:
|
||||
className: nginx
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: cloudflare-acme-prod
|
||||
hosts:
|
||||
- host: commandware.it
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
gateway:
|
||||
serviceName: gateway-0-1759393614-gateway
|
||||
port: 80
|
||||
namespace: api7ee
|
||||
tls:
|
||||
- secretName: api7ee-tls
|
||||
hosts:
|
||||
- commandware.it
|
||||
```
|
||||
|
||||
**Modifiche:**
|
||||
- Rimossa annotation `nginx.ingress.kubernetes.io/rewrite-target: /`
|
||||
- Aggiunta annotation `cert-manager.io/cluster-issuer`
|
||||
- Un solo path `/` invece di due path separati (`/` e `/api`)
|
||||
- Aggiunto `namespace: api7ee` al gateway
|
||||
- Cambiato `secretName` da `api7ee-demo-tls` a `api7ee-tls`
|
||||
|
||||
---
|
||||
|
||||
### 6. TLS Configuration - COMPLETATA
|
||||
|
||||
```yaml
|
||||
api7:
|
||||
tls:
|
||||
enabled: true
|
||||
certManager:
|
||||
enabled: true
|
||||
issuer: cloudflare-acme-prod
|
||||
issuerKind: ClusterIssuer
|
||||
privateKey:
|
||||
rotationPolicy: Always
|
||||
algorithm: RSA
|
||||
size: 2048
|
||||
duration: 2160h # 90 days
|
||||
renewBefore: 720h # 30 days before expiry
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Come Applicare le Modifiche
|
||||
|
||||
### Opzione 1: Interfaccia Web ArgoCD
|
||||
|
||||
1. Accedi ad ArgoCD Dashboard
|
||||
2. Seleziona l'applicazione `api7ee-demo`
|
||||
3. Clicca su "APP DETAILS" → "PARAMETERS"
|
||||
4. Modifica i valori come sopra indicato
|
||||
5. Clicca "SAVE"
|
||||
6. Clicca "SYNC" per applicare le modifiche
|
||||
|
||||
### Opzione 2: Via CLI
|
||||
|
||||
```bash
|
||||
# Edit application
|
||||
kubectl edit application -n argocd api7ee-demo
|
||||
|
||||
# O usa ArgoCD CLI
|
||||
argocd app set api7ee-demo --values /path/to/updated-values.yaml
|
||||
argocd app sync api7ee-demo
|
||||
```
|
||||
|
||||
### Opzione 3: Usa il values.yaml aggiornato
|
||||
|
||||
Il file `values.yaml` nella root del progetto è già stato aggiornato con tutte le modifiche.
|
||||
Puoi copiarlo direttamente nella configurazione ArgoCD.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verifica Post-Sync
|
||||
|
||||
Dopo la sincronizzazione, verifica che tutto funzioni:
|
||||
|
||||
### 1. Check ConfigMap
|
||||
```bash
|
||||
kubectl get configmap -n api7ee api7ee-demo-api7ee-demo-k8s-adc-config \
|
||||
-o jsonpath='{.data.adc-config\.yaml}' | grep "discovery_type"
|
||||
```
|
||||
**Risultato atteso:** Nessun output (service discovery disabilitato)
|
||||
|
||||
### 2. Check Secret
|
||||
```bash
|
||||
kubectl get secret -n api7ee api7ee-demo-api7ee-demo-k8s-api7-admin \
|
||||
-o jsonpath='{.data.admin-key}' | base64 -d | wc -c
|
||||
```
|
||||
**Risultato atteso:** `88` (chiave presente)
|
||||
|
||||
### 3. Check ADC Sync Job
|
||||
```bash
|
||||
kubectl logs -n api7ee job/api7ee-demo-api7ee-demo-k8s-adc-sync --tail=20
|
||||
```
|
||||
**Risultato atteso:**
|
||||
```
|
||||
[ADC] › ✔ success Sync configuration
|
||||
[ADC] › ★ star All is well, see you next time!
|
||||
```
|
||||
|
||||
### 4. Test Routing
|
||||
```bash
|
||||
# Test web
|
||||
curl -I https://commandware.it/
|
||||
|
||||
# Test API
|
||||
curl -I https://commandware.it/api/health
|
||||
```
|
||||
**Risultato atteso:** HTTP 200 o 405 (metodi funzionanti)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Note Importanti
|
||||
|
||||
### Service Discovery
|
||||
Per riabilitare service discovery in futuro:
|
||||
|
||||
1. **Configura Service Registry nel Dashboard API7:**
|
||||
- Accedi al Dashboard: `https://api7ee3-0-1759339083-dashboard:7443`
|
||||
- Vai a: Gateway Groups → Service Registries
|
||||
- Aggiungi: Kubernetes Service Registry
|
||||
- Configura: API Server URL e Token
|
||||
|
||||
2. **Abilita nel values.yaml:**
|
||||
```yaml
|
||||
api7:
|
||||
serviceDiscovery:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
3. **Sync ArgoCD**
|
||||
|
||||
### Secret Management
|
||||
Il Secret `api7-credentials` contiene:
|
||||
- `admin-url`: URL del Dashboard API7
|
||||
- `admin-key`: Chiave di autenticazione (88 caratteri)
|
||||
- `gateway-group`: Nome del gateway group (`default`)
|
||||
|
||||
Per ruotare le credenziali:
|
||||
```bash
|
||||
kubectl patch secret -n api7ee api7-credentials \
|
||||
-p '{"data":{"admin-key":"<new-base64-encoded-key>"}}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Riferimenti
|
||||
|
||||
- [Service Discovery Guide](web/docs/service-discovery.md)
|
||||
- [Secret Management Guide](web/docs/secret-management.md)
|
||||
- [Ingress & Routing Guide](web/docs/ingress-routing.md)
|
||||
- [API7 Enterprise Docs](https://docs.api7.ai/enterprise/)
|
||||
|
||||
---
|
||||
|
||||
**Data aggiornamento:** 2025-10-09
|
||||
**Versione Chart:** api7ee-demo-k8s-0.1.0
|
||||
Reference in New Issue
Block a user