Quickstart — cel·la autoallotjada

Aixeca una sola cel·la d’OpenDome que serveix l’API OSL, sense control-plane i sense phone-home. Aquest és el camí que segueix un self-hoster; el producte gestionat/Enterprise afegeix el control-plane central i la consola sobre els mateixos charts exactes.

Prerequisits

Un clúster de Kubernetes (kind serveix) amb:
- Un CNI que apliqui NetworkPolicy — Cilium recomanat. El kindnet per defecte de kind no l’aplica. Amb Cilium, instal·la’l amb --set 'policyCIDRMatchMode={nodes}'; sense això, Cilium ignora les regles ipBlock que cobreixen les IPs del node/apiserver i el Postgres inclòs es dead-locka a “Setting up primary”. (scripts/cluster-create.sh ho fa per tu a kind.)
- Un controlador d’Ingress per arribar a l’API OSL.
- Una StorageClass per defecte (per a l’object store inclòs + les PVCs de Postgres).
- L’operador CloudNativePG instal·lat a tot el clúster — només si fas servir el Postgres inclòs.
helm ≥ 3.12 i kubectl.

Per a ingress-nginx, instal·la’l eliminant qualsevol X-Actor-Roles provinent del client a la vora (defensa en profunditat — el motor igualment ignora la capçalera en 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='

Si fas servir el Postgres inclòs, instal·la primer CloudNativePG:

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

Aixeca la cel·la

El shell de la cel·la + la infra inclosa (object store + Postgres).

standard-tenant crea el namespace, una NetworkPolicy deny-all (sense regles d’allow per al control-plane), quotes i — en el perfil standalone — un object store dins del namespace (RustFS) i un Postgres CloudNativePG, més el Secret tenant-object-storage.

# La NetworkPolicy deny-all només deixa que els pods arribin a l'API de
# Kubernetes a través d'aquesta allowlist (l'init de CNPG ho necessita).
# Deriva totes dues adreces del TEU clúster — sense endevinar 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"

Sense valors explícits, el chart encunya credencials aleatòries a la primera instal·lació i les reutilitza als upgrades. Recupera-les en qualsevol moment:

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

El motor OSL — la superfície de consum.
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
```
Això activa l’Ingress opt-in i renderitza el manifest OSL localment a partir dels values. En el perfil standalone el motor no confia en la capçalera X-Actor-Roles — un cridador públic de l’Ingress no pot falsejar rols. L’accés amb ACL passa pel emisor de tokens local: el chart genera un Secret de signatura i el motor valida tokens Authorization: Bearer HS256.

Verifica que la cel·la es pot fer servir via la seva API — sense 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"   # motor + nivells de conformança
curl -fsS "http://$HOST/osl/schema"        # manifest compilat (buit fins que escriguis facets)

Encunya un token signat localment i fes una crida governada.

Els rols del token impulsen l’ACL — les facetes els respecten 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 invàlid o caducat és un 401 dur (E3001). El motor mai degrada silenciosament un token trencat a “anònim”.

Si això retorna 200 sense que el namespace opendome-system estigui present, la cel·la és utilitzable en standalone. Corre scripts/oss-gate.sh per comprovar-ho d’extrem a extrem.

Capes opcionals

Pota estructurada (Trino + Nessie + Iceberg) — charts/lakehouse. Per defecte usa endpoints dins del namespace amb credencials del Secret tenant-object-storage; necessita el Postgres inclòs/extern del pas 1.
Config API (allowlist / pipeline / discovery) — charts/tenant-config. Ja és standalone: usa el Postgres propi de la cel·la + una API directa GET/PUT /config/{key}.
Ingest / orquestració — charts/dagster. Per defecte: sense callbacks al control-plane, sense telemetria cap a dalt, els Jobs corren en aquest namespace.

Reconstruir imatges al teu propi registre

Els charts publicats pinnen les imatges per digest immutable (image.digest: sha256:…), que té prioritat sobre el tag. Aquest digest identifica la imatge publicada d’OpenDome — no té significat en cap altre registre. Si reconstrueixes les imatges de la cel·la al teu propi registre, esborra el digest enviat o cada pod farà ImagePullBackOff:

helm install osl charts/tenant-semantic-api \
  --set image.repository=myreg.example/tenant-semantic-api \
  --set image.digest=""          # ← OBLIGATORI quan canvies el repository

Fes el mateix per a tenant-mgmt-api.runnerImages.*. Si baixes les imatges publicades d’OpenDome, deixa el digest tal com s’envia i fes-ne cosign verify.

Carregar dades reals

Per servir retrievals reals: crea el bucket (tenant-demo) al teu object store, escriu facetes OSL (YAML UnstructuredFacet / JointEntity sota el manifest.facets del motor) i ingesta datasets Lance a s3://tenant-demo/lance. Vegeu Conceptes per al model del manifest i la referència de l’API per a com es crida el retrieval.