LOGINMASTER-DeploymentScript/README.md

# LoginMaster Tenant — Deployment Tools

Toolkit per deployare un tenant LoginMaster (api-tenant + admin-tenant + MongoDB replica set) su qualsiasi cluster Kubernetes — vSphere, AWS EKS, Azure AKS, DigitalOcean DOKS, Scaleway Kapsule, Hetzner, ecc.

## Cosa viene deployato

```
namespace: <a tua scelta, es. loginmaster-tenant-acme>
│
├── MongoDB replica set rs0 (3 pod, StatefulSet)
│     ├── TLS server cert via cert-manager (CA interna self-signed, 10 anni)
│     ├── auth replica set via keyFile, auth client via password
│     └── PVC RWO 20Gi per nodo (storage class scelta dall'utente)
│
├── tenant-api (Deployment, 2 repliche, rolling update zero-downtime)
│     └── connessione Mongo via TLS, valida server cert via la CA interna
│
├── tenant-admin (Deployment, 1 replica)
│
├── Ingress nginx con cert Let's Encrypt per i due hostname pubblici
│
├── NetworkPolicy che isola il tenant:
│     ├── Mongo raggiungibile solo dai pod tenant-api e dai membri replica set
│     └── api/admin raggiungibili solo dall'ingress controller
│
└── Secret per: credenziali Mongo, MASTER_ENCRYPTION_KEY, registry, SMTP password
```

## Prerequisiti

### Sul cluster

| Cosa | Note |
|---|---|
| **cert-manager** | Con `ClusterIssuer` `letsencrypt-prod` per i certificati Ingress pubblici. Gli `Issuer` interni per il TLS Mongo sono creati dallo script. |
| **ingress-nginx** | Installato in un namespace con la label `kubernetes.io/metadata.name: ingress-nginx` (default da K8s 1.22+). |
| **CNI con NetworkPolicy** | Calico, Cilium, weave, kube-router. Le `NetworkPolicy` non sono enforcement-effective senza un CNI che le implementi. |
| **Storage class default** | Auto-rilevata dallo script via annotation `storageclass.kubernetes.io/is-default-class`. Se il cluster non ne ha una marcata, lo script chiede manualmente. |

### Sulla macchina

```
brew install kubectl gettext openssl
brew link --force gettext   # per envsubst
```

### Credenziali

- Accesso al registry `hub.codebaker.it/loginmaster-tenant/` (username + password)
- Context kubectl configurato per il cluster target

## Deploy iniziale

```bash
./deploy.sh
```

Lo script chiede 14 parametri in modo interattivo. Default sensati per Codebaker (in `[parentesi]`):

| Prompt | Default | Note |
|---|---|---|
| Context kubectl | corrente | Quello selezionato in `~/.kube/config` |
| Namespace | `loginmaster-tenant` | Uno per tenant. Lo script aborta se esiste già |
| Tag api-tenant | `prod-1.3.8` | |
| Tag admin-tenant | `prod-1.3.7` | Le due immagini possono essere a versioni diverse |
| Hostname API | `api.tenant.example.com` | Da sostituire col proprio dominio. Deve risolvere all'ingress controller |
| Hostname admin | `admin.tenant.example.com` | Idem |
| `LOGINMASTER_API_URL` | `https://api.loginmaster.it/1.3/` | API LoginMaster centrale |
| `ADMIN_ALLOWED_ORIGIN` | `https://admin.loginmaster.it` | Origin del pannello LoginMaster globale (≠ pannello del tenant) |
| Storage class | default cluster | Auto-rilevata |
| Storage size | `20Gi` | Per ogni membro Mongo (totale: 3× questo) |
| Mongo CPU/mem | 250m–2 / 1Gi–2Gi | Aumenta su carichi reali (Mongo cache cresce con la RAM) |
| SMTP | `N` | Se sì, chiede host/port/secure/user/pass |
| Registry user/password | — / — | Credenziali fornite per accedere a `hub.codebaker.it` |
| Confirm | `N` | `Y` per procedere |

A fine deploy lo script salva `.deploy-credentials.txt` (chmod 600) con MASTER_ENCRYPTION_KEY, password root + applicativa Mongo, URI di connessione. **Spostalo in un password manager e cancellalo dal disco.**

### Re-run protection

`deploy.sh` aborta se nel namespace esiste già il Secret `mongodb-tenant-auth`: rigenerarlo causerebbe la perdita del replica set (nuovo keyfile → membri non si parlano più).

Per ridistribuire da zero: `kubectl delete namespace <ns>` e rilancia.
Per aggiornare le immagini: usa `update.sh`.

## Aggiornare un tenant esistente

```bash
./update.sh                              # interattivo, prefilla con i tag attuali del cluster
./update.sh prod-1.3.9                   # stesso tag per api e admin
./update.sh prod-1.3.9 prod-1.3.8        # tag separati
```

Lo script:
1. Mostra le immagini attuali e chiede conferma per il rolling update di api e/o admin.
2. Se l'update fallisce, stampa il comando `kubectl rollout undo` da copiare.
3. In coda chiede se **riapplicare il ConfigMap** dal template — utile quando una nuova versione dell'API legge env var nuove. Riapplica `templates/03-configmap.yaml` usando i valori correnti dal cluster e fa `rollout restart` di tenant-api per propagarli.

### Rollback manuale

`kubectl` mantiene le ultime 10 revisioni dei Deployment:

```bash
kubectl -n <ns> rollout history deployment/tenant-api
kubectl -n <ns> rollout undo    deployment/tenant-api
kubectl -n <ns> rollout undo    deployment/tenant-api --to-revision=N
```

## Operazioni comuni

### Verificare lo stato

```bash
kubectl -n <ns> get pods,ingress,certificate
kubectl -n <ns> logs deploy/tenant-api --tail=100 -f
```

### Stato replica set Mongo

```bash
ROOT_PASS=$(kubectl -n <ns> get secret mongodb-tenant-auth -o jsonpath='{.data.root-password}' | base64 -d)
kubectl -n <ns> exec mongodb-tenant-0 -c mongodb -- mongosh --quiet \
  'mongodb://127.0.0.1:27017/?directConnection=true&tls=true&tlsCAFile=/etc/mongo-tls/ca.crt&tlsAllowInvalidHostnames=true' \
  -u admin -p "$ROOT_PASS" --authenticationDatabase admin \
  --eval 'rs.status()'
```

### Backup / restore

Lo script non gestisce backup: usa `mongodump`/`mongorestore` con le credenziali applicative, oppure snapshot lato cloud sui PV Mongo.

### Scale orizzontale

```bash
kubectl -n <ns> scale deployment/tenant-api --replicas=4
```

Mongo è un replica set fisso a 3 membri (PDB `minAvailable: 2` lo presuppone): non scalare a meno di non rivedere PDB e quorum.

## Cleanup

```bash
kubectl delete namespace <ns>
```

> **Attenzione**: i PV con `reclaim policy: Retain` (es. `vsphere-csi`, `sbs-default-retain`) **sopravvivono** alla cancellazione del namespace e dei PVC. Vanno rimossi a mano (`kubectl delete pv <name>`) e i dischi sottostanti dal pannello del cloud provider per non lasciare costi residui.

## Sicurezza

- **TLS interno Mongo**: cert-manager emette CA self-signed (10 anni) e cert membri (1 anno). Mongo è in `requireTLS`. Niente traffico in chiaro nel namespace.
- **Auth replica set**: keyFile (HMAC condiviso). I membri non si parlano se il keyfile non combacia.
- **Auth client**: password generata, mai in argv di kubectl, mai in log audit (le `mongo_eval*` di `deploy.sh` autenticano via `db.auth()` su stdin).
- **NetworkPolicy**: blocca traffico cross-namespace e intra-namespace non autorizzato.
- **Pod Mongo non-root** (uid/gid 999) con `fsGroup` per ownership PVC.
- **Secret K8s** (base64-encoded, non encrypted at rest se non configurato a livello cluster). MASTER_ENCRYPTION_KEY, password Mongo, password registry e SMTP risiedono qui — abilita encryption-at-rest a livello etcd se la compliance lo richiede.

### Limiti noti

- **Rinnovo cert TLS Mongo**: cert-manager rinnova il Secret automaticamente, ma **mongod non ricarica il cert a runtime**. Quando cert-manager riemette il Secret (default 30 giorni prima della scadenza, quindi ~ogni 11 mesi sui cert membri), serve `kubectl rollout restart statefulset/mongodb-tenant`. Il PDB garantisce che resti almeno 1 PRIMARY + 1 SECONDARY → zero downtime sul replica set, ma è una azione manuale.
- **Warning `PodSecurity "restricted"`**: il pod Mongo richiede uno user-defined `runAsUser` e l'init come root, quindi triggera un warn (non enforce). Se la policy è in enforce mode, il deploy va rivisto (init come root non è compatibile con `restricted` puro).

## Note per cloud provider specifici

| Provider | Storage class default tipica | Reclaim default |
|---|---|---|
| AWS EKS | `gp3` (recenti) o `gp2` | `Delete` |
| Azure AKS | `default` o `managed-csi` | `Delete` |
| DigitalOcean DOKS | `do-block-storage` | `Delete` |
| Scaleway Kapsule | `sbs-default-retain`, `scw-bssd` | varia |
| GCP GKE | `standard-rwo`, `premium-rwo` | `Delete` |
| vSphere | `vsphere-csi` | `Retain` |
| Hetzner | `hcloud-volumes` | `Delete` |

**Reclaim `Delete`** = cancellando il namespace perdi i dati Mongo. Per produzione: scegliere SC con `Retain` o avere snapshot/backup esterni. Lo script non sovrascrive il reclaim della SC.

**Volume binding mode**: tutte le SC cloud moderne usano `WaitForFirstConsumer`, che fa partire i 3 pod Mongo correttamente in cluster multi-AZ. Le SC custom con `Immediate` su cluster multi-AZ rischiano cross-zone mount fail.

## Struttura del repo

```
.
├── deploy.sh                 # bootstrap di un nuovo tenant (idempotente: aborta su rerun)
├── update.sh                 # rolling update + rollback hint + apply ConfigMap opzionale
└── templates/
    ├── 00-namespace.yaml
    ├── 01-mongodb-tls.yaml   # cert-manager Issuer + CA + cert membri
    ├── 02-networkpolicy.yaml # isolamento intra-namespace
    ├── 03-configmap.yaml     # tenant-api-config
    ├── 04-mongodb.yaml       # StatefulSet 3 repliche, init container per keyfile/PEM tmpfs
    ├── 05-tenant-api.yaml    # Deployment 2 repliche + Service + PDB
    ├── 06-tenant-admin.yaml  # Deployment 1 replica + Service
    └── 07-ingress.yaml       # ingress-nginx + Let's Encrypt
```

## Troubleshooting

### Pod Mongo in CrashLoopBackOff
Probabilmente cert-manager non ha emesso `mongodb-tenant-tls`. Verifica:
```bash
kubectl -n <ns> get certificate
kubectl -n <ns> describe certificate mongodb-tenant-tls
```

### Cert ingress `tenant-tls` resta `Ready: False`
DNS dei due hostname non risolve all'IP dell'ingress controller, oppure la HTTP-01 challenge fallisce per altri motivi:
```bash
kubectl -n <ns> describe certificate tenant-tls
kubectl -n <ns> get challenge
```

### Replica set non elegge un PRIMARY
Verifica connettività intra-namespace (NetworkPolicy può bloccare se la label `app: mongodb-tenant` viene cambiata) e che i 3 pod si vedano via DNS:
```bash
kubectl -n <ns> exec mongodb-tenant-0 -c mongodb -- nslookup mongodb-tenant-1.mongodb-tenant-headless
```

### `ImagePullBackOff` su admin/api
Tag inesistente sul registry. Verifica:
```bash
curl -u USER:PASS https://hub.codebaker.it/v2/loginmaster-tenant/admin-tenant/tags/list
```
Storicamente `api-tenant` esce più frequentemente di `admin-tenant`: usa tag separati con `./update.sh API_TAG ADMIN_TAG`.

### Errori PVC su provisioning
Storage class non esistente o quota cloud esaurita:
```bash
kubectl get sc
kubectl -n <ns> describe pvc mongodb-data-mongodb-tenant-0
```