Quickstart — samodzielnie hostowana komórka

Postaw pojedynczą komórkę OpenDome, która serwuje API OSL, bez control-plane i bez phone-home. To ścieżka, którą obiera self-hoster; produkt zarządzany/Enterprise dokłada centralny control-plane i konsolę na dokładnie tych samych chartach.

Niezmiennik

Komórka startuje i serwuje swoje API bez tego, by namespace opendome-system kiedykolwiek istniał. Gate CI scripts/oss-gate.sh weryfikuje to od początku do końca.

Wymagania wstępne

• Klaster Kubernetes (kind wystarczy) z:
  • CNI, który egzekwuje NetworkPolicy — zalecany jest Cilium. Domyślny kindnet w kind nie go egzekwuje. Z Ciliumem zainstaluj go z --set 'policyCIDRMatchMode={nodes}'; bez tego Cilium ignoruje reguły ipBlock obejmujące IP węzła/apiservera, a dołączony Postgres zakleszcza się na „Setting up primary“. (scripts/cluster-create.sh robi to za ciebie na kind.)
  • Kontrolerem Ingress, aby dosięgnąć API OSL.
  • Domyślną StorageClass (dla PVC dołączonego object store + Postgres).
  • Operatorem CloudNativePG zainstalowanym cluster-wide — tylko jeśli używasz dołączonego Postgresa.
• helm ≥ 3.12 i kubectl.

Dla ingress-nginx zainstaluj go, usuwając na edge wszelkie X-Actor-Roles przysłane przez klienta (obrona w głąb — silnik w trybie standalone i tak ignoruje ten header):

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

Uwaga

Snippet annotations nie są używane: nowoczesny ingress-nginx odrzuca je przy admission z domyślnym allow-snippet-annotations=false.

Jeśli używasz dołączonego Postgresa, najpierw zainstaluj CloudNativePG:

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

Postaw komórkę

1. Powłoka komórki + dołączona infra (object store + Postgres).

   standard-tenant tworzy namespace, NetworkPolicy typu deny-all (bez reguł allow do control-plane), kwoty i — w profilu standalone — object store in-namespace (RustFS) oraz Postgres CloudNativePG, plus Secret tenant-object-storage.

   # The deny-all NetworkPolicy only lets pods reach the Kubernetes API through
   # this allowlist (CNPG's init needs it). Derive both addresses from YOUR
   # cluster — no per-distro guessing:
   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"

   Bez jawnych values chart generuje losowe poświadczenia przy pierwszej instalacji i ponownie ich używa przy upgrade’ach. Odzyskaj je w dowolnej chwili:

   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. Silnik OSL — powierzchnia konsumpcji.

   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

   To włącza opt-in Ingress i renderuje manifest OSL lokalnie z values. W profilu standalone silnik nie ufa headerowi X-Actor-Roles — wywołujący przez publiczny Ingress nie może podszyć się pod role. Dostęp z ACL przechodzi przez lokalny emitter tokenów: chart generuje Secret podpisujący, a silnik waliduje tokeny Authorization: Bearer HS256.

3. Zweryfikuj, że komórka jest używalna przez swoje API — bez 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"   # engine + conformance levels
   curl -fsS "http://$HOST/osl/schema"        # compiled manifest (empty until you author facets)

4. Wygeneruj token podpisany lokalnie i wykonaj nadzorowane wywołanie.

   Role tokenu sterują ACL — fasety honorują je po stronie serwera.

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

   Fail-closed

   Nieprawidłowy lub wygasły token to twarde 401 (E3001). Silnik nigdy po cichu nie degraduje uszkodzonego tokenu do „anonimowego“.

Jeśli powyższe zwracają 200 bez obecnego namespace opendome-system, komórka jest używalna w trybie standalone. Uruchom scripts/oss-gate.sh, aby potwierdzić to od początku do końca.

Warstwy opcjonalne

• Noga ustrukturyzowana (Trino + Nessie + Iceberg) — charts/lakehouse. Domyślnie endpointy in-namespace z poświadczeniami z Secretu tenant-object-storage; wymaga dołączonego/zewnętrznego Postgresa z kroku 1.
• Config API (allowlist / pipeline / discovery) — charts/tenant-config. Już standalone: używa własnego Postgresa komórki + bezpośredniego API GET/PUT /config/{key}.
• Ingest / orkiestracja — charts/dagster. Domyślnie: bez callbacków do control-plane, bez telemetrii upstream, Joby działają w tym namespace.

Załaduj prawdziwe dane

Aby serwować prawdziwe retrievale: utwórz bucket (tenant-demo) w swoim object store, napisz fasety OSL (YAML UnstructuredFacet / JointEntity pod manifest.facets silnika) i zaingestuj datasety Lance do s3://tenant-demo/lance. Zobacz Koncepcje po model manifestu oraz referencję API po to, jak wywołuje się retrieval.