Quickstart — celda autohospedada

Levanta una celda de OpenDome que sirve la API OSL, sin control-plane y sin phone-home. Este es el camino del self-hoster; el producto gestionado/Enterprise añade el control-plane central y la consola sobre exactamente los mismos charts.

Invariante

La celda arranca y sirve su API sin que el namespace opendome-system exista jamás. El gate de CI scripts/oss-gate.sh lo verifica de extremo a extremo.

Requisitos

• Un clúster de Kubernetes (kind sirve) con:
  • Un CNI que aplique NetworkPolicy — se recomienda Cilium. El kindnet por defecto de kind no lo aplica. Con Cilium, instálalo con --set 'policyCIDRMatchMode={nodes}'; sin eso, Cilium ignora las reglas ipBlock que cubren las IPs de nodo/apiserver y el Postgres bundled se queda bloqueado en “Setting up primary”. (scripts/cluster-create.sh lo hace por ti en kind.)
  • Un controlador Ingress para alcanzar la API OSL.
  • Una StorageClass por defecto (para los PVC del object store + Postgres bundled).
  • El operador CloudNativePG instalado cluster-wide — solo si usas el Postgres bundled.
• helm ≥ 3.12 y kubectl.

Para ingress-nginx, instálalo eliminando cualquier X-Actor-Roles que envíe el cliente en el edge (defensa en profundidad — el motor ignora ese header en standalone de todas formas):

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

Precaución

Las snippet annotations no se usan: el ingress-nginx moderno las rechaza en admission con el allow-snippet-annotations=false por defecto.

Si usas el Postgres bundled, instala antes CloudNativePG:

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

Levantar la celda

1. El shell de la celda + infra bundled (object store + Postgres).

   standard-tenant crea el namespace, una NetworkPolicy deny-all (sin reglas allow al control-plane), las quotas y — en el perfil standalone — un object store in-namespace (RustFS) y un Postgres CloudNativePG, más el Secret tenant-object-storage.

   # La NetworkPolicy deny-all solo deja a los pods alcanzar la API de Kubernetes
   # a través de este allowlist (el init de CNPG lo necesita). Deriva ambas
   # direcciones de TU clúster — sin adivinar por 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"

   Sin valores explícitos, el chart genera credenciales aleatorias en la primera instalación y las reutiliza en los upgrades. Recupéralas cuando quieras:

   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

2. El motor OSL — la superficie de consumo.

   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

   Esto habilita el Ingress opt-in y renderiza el manifest OSL localmente desde los values. En el perfil standalone el motor no confía en el header X-Actor-Roles — un llamante por un Ingress público no puede falsear roles. El acceso con ACL pasa por el emisor de tokens local: el chart genera un Secret de firma y el motor valida tokens Authorization: Bearer HS256.

3. Verifica que la celda es usable vía su API — sin 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 + niveles de conformancia
   curl -fsS "http://$HOST/osl/schema"        # manifest compilado (vacío hasta autorar facets)

4. Emite un token firmado localmente y haz una llamada gobernada.

   Los roles del token gobiernan la ACL — los facets los honran server-side.

   TOKEN=$(scripts/osl-token.sh demo --roles analyst)
   curl -fsS -H "Authorization: Bearer $TOKEN" "http://$HOST/osl/schema"

   Fail-closed

   Un token inválido o expirado es un 401 rotundo (E3001). El motor nunca degrada en silencio un token roto a “anónimo”.

Si eso devuelve 200 sin que exista el namespace opendome-system, la celda es usable en standalone. Corre scripts/oss-gate.sh para afirmarlo de extremo a extremo.

Capas opcionales

• Pierna estructurada (Trino + Nessie + Iceberg) — charts/lakehouse. Por defecto endpoints in-namespace con credenciales del Secret tenant-object-storage; necesita el Postgres bundled/externo del paso 1.
• API de Config (allowlist / pipeline / discovery) — charts/tenant-config. Ya standalone: usa el propio Postgres de la celda + una API directa GET/PUT /config/{key}.
• Ingest / orquestación — charts/dagster. Por defecto: sin callbacks al control-plane, sin telemetría upstream, los Jobs corren en este namespace.

Cargar datos reales

Para servir retrievals reales: crea el bucket (tenant-demo) en tu object store, autora facets OSL (YAML UnstructuredFacet / JointEntity bajo manifest.facets del motor) e ingesta datasets Lance a s3://tenant-demo/lance. Ver Conceptos para el modelo del manifest y la referencia de la API para cómo se llama al retrieval.