Come installare un DS3 Gateway

Benvenuti nella guida all'installazione del Gateway DS3. Il Gateway DS3 è l'interfaccia principale tra i client esterni e lo Swarm DS3, fornendo un'API compatibile con S3 per un'integrazione senza problemi con applicazioni e strumenti esistenti. Ogni istanza di gateway è un servizio leggero e statelss che gestisce:

• Gestione API S3: Processa le richieste dei client secondo le semantiche DS3.
• Crittografia: Esegue la crittografia lato client, garantendo che i dati siano sicuri prima della trasmissione allo Swarm.
• Frammentazione dati e ridondanza: Divide gli oggetti in frammenti, applica l'erasure encoding in base alla tua Classe di Ridondanza e prepara i frammenti per la distribuzione tramite il componente Offloader.
• Distribuzione shard: Instrada i frammenti codificati agli Agenti in Ring selezionati su uno o più Nexus.
• Caching opzionale: Accelera i carichi di lavoro con cache locali o condivise per operazioni ripetute o sensibili alla latenza.

Molteplici gateway possono funzionare in parallelo, in sede, nel cloud o all'edge, scalando indipendentemente dal backend di storage e bilanciati facilmente per un'elevata capacità di throughput e alta disponibilità. Per ulteriori informazioni sul Gateway DS3, si prega di fare riferimento a questa sezione

Prima di iniziare

Prima di iniziare, verifica i seguenti prerequisiti di sistema

• Cluster Kubernetes Un cluster conforme (on-prem, cloud, o all'edge).
  suggerimento

  Se non ne hai uno, consulta la sezione seguente.

• DNS e SSL (consigliato)
  • Dominio personalizzato (es., example.com)
  • Certificato(i) TLS valido(i)

Configurerai DNS e SSL nella UI del Composer sotto Dominio e TLS.

Come installare

0. Preparare un DS3 Gateway

1. Nella UI del Composer, vai su Tenant → Impostazioni → Gateway → Crea il tuo gateway privato.
2. (Opzionale, ma consigliato) Nella UI del Composer sotto Tenant → Impostazioni → Gateway → DNS, aggiungi il tuo dominio personalizzato se intendi esporre il gateway su un nome host user friendly. Quindi segui la guida sulla UI e crea i seguenti record DNS.

La UI del Composer ti chiederà di creare un record DNS TXT per verificare la proprietà del dominio:

<tuo-dominio>  TXT  <codice-verifica>

Dopo la verifica, crea questi record A puntando gli ingress IP(s) di Kubernetes:

console.<domain>     A    <ingress-ip>
s3.<domain>          A    <ingress-ip>
*.s3.<domain>        A    <ingress-ip>

3. Completa il wizard; alla fine riceverai il comando di installazione esatto (una riga curl | bash). Copia questo per il passaggio successivo.

1. Esegui l'installer

Esegui lo script di installazione per installare il software Gateway DS3 sul tuo cluster Kubernetes, creando tutte le risorse necessarie, i servizi e le regole di ingress. Incolla ed esegui il comando che hai ottenuto dal Composer. Dovrebbe assomigliare a:

curl -fSsL https://installer.s3.cubbit.eu/gateway/installer.sh | bash -s -- \
  --tenant-name <TENANT_NAME> \
  --tenant-id <TENANT_ID> \
  --domain <YOUR_DOMAIN> \
  --gateway-id <GATEWAY_ID> \
  --gateway-secret <GATEWAY_SECRET>

Argomento	Descrizione
--domain	Il dominio di base sotto il quale il Gateway DS3 sarà esposto (es., example.com). Le regole di ingress utilizzeranno console.<domain>, s3.<domain>, e *.s3.<domain>.
--gateway-id	Un UUID che identifica in modo univoco questa istanza di gateway.
--gateway-secret	Una chiave segreta associata al gateway per l'autenticazione tra il gateway e il Coordinatore.
--tenant-name	Il nome leggibile del tenant per cui stai installando il gateway.
--tenant-id	Un UUID che identifica univocamente il tenant all'interno della tua organizzazione.

nota

L'installer utilizzerà il contesto Kubernetes attualmente impostato. Se vuoi modificare questo comportamento, puoi indirizzare un kubeconfig personalizzato usando la variabile d'ambiente KUBECONFIG come:

export KUBECONFIG=/path/to/your/kubeconfig

Cosa Succede Durante l'Installazione

Lo script di installazione farà:

1. Connettiti a Kubernetes utilizzando il tuo kubeconfig
2. Crea o utilizza un namespace dedicato
3. Deploya le risorse dell'Operatore Kubernetes di Cubbit
4. Configura i ConfigMap e i Secret necessari
5. Configura le risorse di ingress per:
   • console.<domain>
   • s3.<domain>
   • *.s3.<domain>
6. Applica configurazioni di cache o override
7. Configura i certificati TLS per gli endpoint HTTPS

Aiuto e Flag dell'Installer

Esegui lo script di installazione con --help per visualizzare tutte le opzioni:

curl -fSsL https://installer.s3.cubbit.eu/gateway/installer.sh | bash -s -- --help
Usage: bash [OPTIONS]
  --help                      Mostra questo messaggio
  --version                   Stampa la versione
  --domain DOMAIN             Imposta il dominio
  --tenant-name NAME          Imposta il nome del tenant
  --tenant-id ID              Imposta l'ID del tenant
  --gateway-id ID             Imposta l'ID del gateway
  --gateway-secret SECRET     Imposta il secret del gateway
  --cache PATH                Attiva la cache
  --force                     Forza la rimozione
  --uninstall                 Disinstalla l'applicazione
  --no-tls                    Disabilita TLS
  --no-init                   Disabilita l'inizializzazione
  --no-infra                  Salta la preparazione dell'infrastruttura
  --no-app                    Disabilita il setup dell'applicazione
  --ingress                   Installa solo l'ingress K8S
  --no-console                Disabilita la console web
  --no-offloader              Disabilita l'offloader
  --no-s3                     Disabilita il gateway S3
  --coordinator-domain DOMAIN Imposta l'indirizzo del coordinatore [eu00wi.cubbit.services]
  --cert-root PATH            Imposta il percorso per i certificati SSL [./cert]

2. Dipendenze Richieste

L'installatore scarica i seguenti binari in una cartella locale (non li installa a livello di sistema):

• kubectl
• helm
• yq

Questo comportamento è controllato dalle seguenti variabili d'ambiente:

Env Var	Comportamento
SKIP_BINARY=1	Usa le utilities richieste già installate sulla tua macchina.
FORCE_BINARY=1	Riscarica i binari nella sandbox anche se esistono localmente.

3. Configurazione

Dominio & TLS (consigliato)

Nell'Interfaccia del Composer sotto Tenant → Settings → Gateway → DNS, aggiungi il tuo dominio personalizzato.

Lo script di install creerà regole di ingresso per:

• console.<domain>
• s3.<domain>
• *.s3.<domain> (per URL di bucket in stile virtual‑host)

Posiziona i tuoi certificati TLS e chiavi private in una cartella chiamata ./cert/. Hai due opzioni qui:

Option A: Singolo Certificato

Usa un singolo certificato per tutti i servizi:

```
cert/
  ├─ fullchain.pem   # certificato combinato
  └─ privkey.pem     # chiave privata
```

Option B: un certificato per servizio

Un certificato separato per servizio:

```
cert/
  ├─ console/           # Per console.<domain>
  │   ├─ fullchain.pem
  │   └─ privkey.pem
  ├─ gateway/           # Per s3.<domain>
  │   ├─ fullchain.pem
  │   └─ privkey.pem
  └─ gateway-wildcard/  # Per *.s3.<domain>
      ├─ fullchain.pem
      └─ privkey.pem
```

suggerimento

Per la generazione del certificato SSL:

• Usa qualsiasi metodo preferisci (Let’s Encrypt, CA, ecc.).

• Per un rapido esempio di DNS Certbot:

sudo certbot certonly --manual \
  -d '*.s3.<your-domain>' \
  -d 's3.<your-domain>' \
  -d 'console.<your-domain>' \
  --preferred-challenges dns

Questo comando genererà un certificato unico che copre i 3 sottodomini. Puoi quindi copiare la coppia di chiavi risultante nella cartella ./cert/ seguendo l'Opzione A. sopra. Se preferisci creare 3 certificati separati, puoi eseguire il comando sopra 3 volte, uno per ciascun sottodominio. In questo caso, assicurati di usare Opzione B sopra.

Per disabilitare completamente TLS, puoi usare il flag.

--no-tls

attenzione

Se disabiliti SSL, la Console Web privata non funzionerà. Dovrai generare le chiavi e interagire con il gateway dalla CLI.

Configurazione della Cache

Per ottimizzare il processo di upload verso i nodi di archiviazione, includi l'argomento --cache nel tuo comando di installazione:

--cache /path/to/cache

Quando specificato, questo percorso funge da cache su disco locale, riducendo la necessità di una sincronizzazione completa ogni volta che il software del gateway trasferisce dati verso o dallo Swarm. Se ometti --cache, il gateway esegue di default una sincronizzazione completa per ogni operazione.

Considerazioni chiave:

• Spazio su disco e permessi: Assicurati che il percorso della cache abbia sufficiente capacità e che il processo del gateway possa leggere/scrivere su di esso.
• Cache locale per nodo: Nei cluster multi-nodo, ogni nodo mantiene la propria cache. Poiché queste cache non sono condivise, potresti riscontrare problemi di disponibilità dei dati o sincronizzazione tra i nodi.
• Cache cluster condivisa: Per una cache coerente in tutto il cluster, monta un volume condiviso (ad es., NFS, GlusterFS) allo stesso percorso su ogni nodo e punta --cache a quella directory montata in rete.

Per configurazioni più avanzate o risoluzione dei problemi di coerenza della cache, contatta il nostro team di supporto per assistenza.

nota

Nei cluster multi‑nodo, le cache locali non sono condivise. Considera una cache montata in rete per una maggiore coerenza.

Override personalizzati

Per personalizzare le impostazioni del servizio, posiziona i file YAML in una cartella overrides/ dove esegui lo script di installazione. Questi agiscono come i valori di Helm:

# overrides/gods3.yaml
hpa:
  enabled: false  # Abilita o disabilita l'autoscalamento orizzontale dei pod per il servizio
resources:        # Limiti e richieste di risorse Kubernetes
  requests:       # Risorse minime richieste per il servizio
    memory: 1Gi   # Memoria richiesta dal servizio
    cpu: 1000m    # CPU richiesta dal servizio
  limits:        # Risorse massime che il servizio può consumare
    memory: 1Gi   # Limite di memoria per il servizio

# overrides/offloader.yaml
offset: 5         # Imposta il numero di istanze offloader da installare
env:              # Variabili d'ambiente per configurazioni aggiuntive
  - name: UPLOADER_OPERATION_QUEUE_MAX_SIZE
    value: "16"   # Dimensione massima della coda di operazioni dell'offloader. Un valore maggiore consente di accodare più operazioni ma richiede più risorse ed è anche limitato dal numero di connessioni aperte
  - name: CCCP_CONCURRENCY
    value: "128"  # Numero di operazioni concorrenti, idealmente impostato come connessioni di ridondanza totale moltiplicate per `UPLOADER_OPERATION_QUEUE_MAX_SIZE`

Come disinstallare

Puoi disinstallare usando lo script di installazione:

curl -fSsL https://installer.s3.cubbit.eu/gateway/installer.sh | bash -s -- --uninstall

suggerimento

Se hai usato il nostro script bootstrap k3s per installare il tuo cluster Kubernetes (vedi Extra: Installing Kubernetes (k3s)), assicurati di seguire i passaggi in quella sezione per disinstallare k3s e qualsiasi interfaccia Cilium.

Configurazione di Kubernetes

Se non hai già un cluster Kubernetes (necessario per installare il software DS3 Gateway), puoi rapidamente avviarne uno utilizzando il nostro script di configurazione k3s. Semplicemente copia e incolla il comando sotto:

curl -fSsL https://installer.s3.cubbit.eu/k8s-setup.sh | bash -s -- \
  --user ubuntu \
  --ssh-key ./id_rsa \
  --contexts ./cluster-contexts.txt

suggerimento

Riferisciti alla sezione del file di contesto sotto per la sintassi di cluster-contexts.txt.

Questo installer supporta sia cluster a singolo nodo che multi-nodo. Per topologie alternative o configurazioni avanzate, consulta la documentazione di k3s o contatta il supporto.

L'installer:

• Legge il file di contesto per determinare i cluster.
• Scarica o riutilizza k3sup e kubectl in base alle impostazioni dell'ambiente.
• Avvia k3s su ogni nodo tramite k3sup.
• Configura il plugin CNI selezionato.

Output

Dopo il completamento, cerca una cartella config/ contenente:

• Kubeconfigs per contesto: kubeconfig-<context> per ogni cluster.
• Kubeconfig unificato: un unico file chiamato kubeconfig che include tutti i contesti, consentendo la gestione unificata del cluster.

Prerequisiti

• Utente sudo senza password: La macchina o le macchine di destinazione devono avere un utente con sudo senza password.
• Autenticazione con chiave SSH: Chiavi SSH impostate tra la tua macchina di controllo e le destinazioni. (Le installazioni locali non richiedono SSH.)

Selezione del Plugin CNI

Scegli il plugin della Container Network Interface al momento dell'installazione:

• Flannel (default)
• Cilium (aggiungi --cilium)

nota

Una volta che k3s è installato con una CNI specifica, non è possibile cambiarlo successivamente.

Dipendenze

Lo script scarica in sandbox due binari in una cartella locale (non installa a livello di sistema):

• k3sup (per il bootstrapping tramite SSH)
• kubectl

Controlla il comportamento con le variabili d'ambiente:

Variabile d'ambiente	Descrizione
SKIP_BINARY=1	Usa i binari installati nel sistema invece dei download in sandbox.
FORCE_BINARY=1	Ri-scarica i binari anche se esistono già localmente.

Utilizzo

Esegui con --help per elencare tutte le opzioni:

Uso: bash --contexts CONTEXT_FILE [--ssh-key SSH_KEY_PATH] [--user USER]
  --help                      Mostra questo messaggio di aiuto
  --contexts CONTEXT_FILE     Il file con l'elenco dei contesti da creare
  --ssh-key SSH_KEY_PATH      Il percorso della chiave privata SSH
  --user USER                 Il nome utente per le connessioni SSH
  --cilium                    Usa cilium per CNI
  --no-test                   Salta il test di connettività

Flag	Descrizione
--contexts	Percorso verso un file di contesto che definisce i cluster (vedi formato sotto).
--user USER	Utente SSH con sudo senza password (omesso se eseguito localmente).
--ssh-key PATH	Chiave privata SSH per l'autenticazione (può essere omesso se eseguito localmente).
--cilium	Usa Cilium CNI invece di Flannel.
--no-test	Salta i test di connettività preliminari.

File di contesto

Il file di contesto è un file di testo semplice, un nodo di cluster per linea:

<k8s-context>,<ip>[,<ssh-port>]

• <k8s-context>: Un nome per il contesto del cluster (es. ds3-gateway).
• <ip>: IP del nodo (usa localhost per installazioni locali).
• <ssh-port>: Porta SSH opzionale (predefinita a 22).

Esempio

# Due nodi nel cluster 'ds3-gateway', un cluster locale a nodo singolo
ds3-gateway,192.168.1.1,22
ds3-gateway,192.168.1.2,2222
localhost,192.168.1.3,22

I nodi che condividono lo stesso contesto si uniscono in un unico cluster; qualsiasi voce localhost crea sempre un cluster a nodo singolo.

Disinstalla Kubernetes

Se hai installato k3s usando Cilium come CNI, potresti dover rimuovere eventuali interfacce di rete correlate. Esegui questi comandi solo se Cilium era la tua CNI scelta:

sudo ip link delete cilium_host
sudo ip link delete cilium_net
sudo ip link delete cilium_vxlan

Per rimuovere il cluster Kubernetes (k3s) dalla macchina target, k3s fornisce uno script di disinstallazione integrato chiamato k3s-uninstall.sh. Esegui il seguente comando con i permessi appropriati sulla macchina target:

sudo /usr/local/bin/k3s-uninstall.sh

Questi passaggi arrestano e rimuovono tutti i servizi, le configurazioni e i dati correlati a k3s, ripristinando la macchina al suo stato pre-installazione.