Quickstart — cella self-hosted

Avvia una singola cella OpenDome che serve l’API OSL, senza control-plane e senza phone-home. Questo è il percorso del self-hoster; il prodotto gestito/Enterprise aggiunge il control-plane centrale e la console sopra esattamente gli stessi chart.

Prerequisiti

Un cluster Kubernetes (kind va bene) con:
- Un CNI che applichi NetworkPolicy — si raccomanda Cilium. Il kindnet di default di kind non lo applica. Con Cilium, installalo con --set 'policyCIDRMatchMode={nodes}'; senza questo, Cilium ignora le regole ipBlock che coprono gli IP di nodo/apiserver e il Postgres bundled si blocca su “Setting up primary”. (scripts/cluster-create.sh lo fa per te su kind.)
- Un controller Ingress per raggiungere l’API OSL.
- Una StorageClass di default (per i PVC dell’object store + Postgres bundled).
- L’operatore CloudNativePG installato cluster-wide — solo se usi il Postgres bundled.
helm ≥ 3.12 e kubectl.

Per ingress-nginx, installalo eliminando qualsiasi X-Actor-Roles inviato dal client sull’edge (difesa in profondità — il motore ignora comunque quell’header in standalone):

helm install ingress-nginx ingress-nginx/ingress-nginx \
  -n ingress-nginx --create-namespace --version 4.11.3 \
  --set-string 'controller.proxySetHeaders.X-Actor-Roles='

Se usi il Postgres bundled, installa prima CloudNativePG:

helm install cnpg cnpg/cloudnative-pg \
  -n cnpg-system --create-namespace --version 0.27.1

Avviare la cella

Lo shell della cella + l’infra bundled (object store + Postgres).

standard-tenant crea il namespace, una NetworkPolicy deny-all (senza regole allow verso il control-plane), le quota e — nel profilo standalone — un object store in-namespace (RustFS) e un Postgres CloudNativePG, più il Secret tenant-object-storage.

# La NetworkPolicy deny-all lascia ai pod raggiungere l'API di Kubernetes
# solo attraverso questa allowlist (l'init di CNPG ne ha bisogno). Deriva
# entrambi gli indirizzi dal TUO cluster — senza indovinare per distro:
APISERVER_VIP=$(kubectl get svc kubernetes -o jsonpath='{.spec.clusterIP}')
APISERVER_EP=$(kubectl get endpoints kubernetes -o jsonpath='{.subsets[0].addresses[0].ip}')

helm install demo charts/standard-tenant \
  -n tenant-demo --create-namespace \
  --set tenant=demo \
  --set "apiServerEgress.cidrs[0]=$APISERVER_VIP/32" \
  --set "apiServerEgress.endpointCidrs[0]=$APISERVER_EP/32"

Senza valori espliciti, il chart genera credenziali casuali alla prima installazione e le riutilizza negli upgrade. Recuperale quando vuoi:

kubectl -n tenant-demo get secret tenant-object-storage -o jsonpath='{.data.accessKey}' | base64 -d
kubectl -n tenant-demo get secret postgres-postgresql   -o jsonpath='{.data.password}'  | base64 -d

Il motore OSL — la superficie di consumo.
Ventana de terminal
```
helm install osl charts/tenant-semantic-api \
  -n tenant-demo \
  --set tenant.id=demo \
  --set ingress.host=osl.tenant-demo.127.0.0.1.nip.io
```
Questo abilita l’Ingress opt-in e renderizza il manifest OSL localmente dai values. Nel profilo standalone il motore non si fida dell’header X-Actor-Roles — un chiamante da un Ingress pubblico non può falsificare i ruoli. L’accesso con ACL passa per l’emettitore di token locale: il chart genera un Secret di firma e il motore valida i token Authorization: Bearer HS256.

Verifica che la cella sia usabile tramite la sua API — senza control-plane.

HOST=osl.tenant-demo.127.0.0.1.nip.io
curl -fsS "http://$HOST/health"            # {"status":"ok",...}
curl -fsS "http://$HOST/osl/conformance"   # motore + livelli di conformità
curl -fsS "http://$HOST/osl/schema"        # manifest compilato (vuoto finché non crei i facet)

Emetti un token firmato localmente e fai una chiamata governata.

I ruoli del token governano l’ACL — i facet li rispettano server-side.
Ventana de terminal
```
TOKEN=$(scripts/osl-token.sh demo --roles analyst)
curl -fsS -H "Authorization: Bearer $TOKEN" "http://$HOST/osl/schema"
```
Un token non valido o scaduto è un 401 secco (E3001). Il motore non degrada mai in silenzio un token rotto ad “anonimo”.

Se questi restituiscono 200 senza che il namespace opendome-system esista, la cella è usabile in standalone. Esegui scripts/oss-gate.sh per affermarlo end-to-end.

Layer opzionali

Gamba strutturata (Trino + Nessie + Iceberg) — charts/lakehouse. Di default endpoint in-namespace con credenziali dal Secret tenant-object-storage; richiede il Postgres bundled/esterno del passo 1.
API di Config (allowlist / pipeline / discovery) — charts/tenant-config. Già standalone: usa il Postgres della cella stessa + un’API diretta GET/PUT /config/{key}.
Ingest / orchestrazione — charts/dagster. Di default: nessuna callback verso il control-plane, nessuna telemetria upstream, i Job girano in questo namespace.

Ricostruire le immagini nel tuo registry

I chart rilasciati pinnano le immagini per digest immutabile (image.digest: sha256:…), che ha la precedenza sul tag. Quel digest identifica l’immagine pubblicata di OpenDome — è privo di significato in qualsiasi altro registry. Se ricostruisci le immagini della cella nel tuo registry, azzera il digest spedito o ogni pod andrà in ImagePullBackOff:

helm install osl charts/tenant-semantic-api \
  --set image.repository=myreg.example/tenant-semantic-api \
  --set image.digest=""          # ← OBBLIGATORIO quando cambi il repository

Fai lo stesso per tenant-mgmt-api.runnerImages.*. Se scarichi le immagini pubblicate di OpenDome, lascia il digest così com’è e verificalo con cosign verify.

Caricare dati reali

Per servire retrieval reali: crea il bucket (tenant-demo) nel tuo object store, crea i facet OSL (YAML UnstructuredFacet / JointEntity sotto manifest.facets del motore) e ingesta dataset Lance in s3://tenant-demo/lance. Vedi Concetti per il modello del manifest e il riferimento API per come si chiama il retrieval.