Orbit add-on

Status: Implemented Issue: https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/work_items/2252 Parent: none

Goal

An administrator turns on Orbit, the GitLab Knowledge Graph, for an instance in the Bridge UI. One switch wires the GitLabCore, its Siphon, and the Orbit together, so nobody has to write the three references by hand. For the design, see ADR 38.

Requirements

  • The API reads, creates or replaces, and deletes the Orbit of an instance, whatever the Orbit is named. An instance has at most one Orbit through the API.
  • A created Orbit is named <instance>-orbit. A name longer than 44 characters receives 422.
  • Saving an Orbit for an instance with no Siphon, or one being deleted, receives 422. An instance that does not exist receives 404. Neither writes an Orbit.
  • A save keeps an Orbit that someone put on another Siphon of the instance on that Siphon.
  • Saving the Orbit connects GitLab to it, and deleting it disconnects GitLab. A conflicting write to the instance fails neither. A failed deletion leaves GitLab connected to the Orbit that stays. Deleting an Orbit that is already gone succeeds.
  • Deleting a Siphon that an Orbit uses receives 409, and the Siphon stays. A caller who may not list Orbit resources receives 403 instead.
  • A read of the Orbit reports none when the cluster does not serve the kind.
  • A graph read user without a read password, or the reverse, receives 422. So does port 9000 for the datalake or the graph.
  • Enabling the Orbit add-on with Siphon off fails validation on the Orbit section. So does turning Siphon off while Orbit stays on.
  • Create and Save write the Orbit after the instance and the Siphon. Turning both off deletes the Orbit before the Siphon.
  • Clearing Enable Orbit deletes the Orbit after a confirmation. Declining keeps it, and a declined or failed deletion does not stop a Siphon that stays on from saving. A Siphon that is turned off stays until the Orbit is gone.
  • When the Orbit fails to save, the instance and the Siphon stay saved, and the form stays open on the add-on. Saving again retries it, and clearing Enable Orbit deletes an Orbit the failed save created. When a Siphon fails too, the notice names both, and the form opens on the one that failed.
  • A caller who cannot read Orbit resources can still save the instance. The add-on shows as Unknown and locked, and an existing Orbit is left untouched. It is also locked and left untouched while the Siphon cannot be read.
  • While an Orbit exists, the panel reports its phase, chart version, GitLab version, and gRPC endpoint, or says that GitLab is not connected yet. While a condition is not True, it also gives the reason and message of the first one.
  • While the instance reports the OrbitConnected condition, the panel shows a GitLab connection row: Connected when it is True, otherwise its reason and message.
  • The form keeps the chart values of an Orbit it loaded.

Out of scope

  • Editing the chart values of an Orbit in the form.
  • Connecting GitLab to an Orbit whose TLS is terminated in front of it.
  • Creating the ClickHouse users, the graph database, the JWT key, or the TLS certificate.

FAQ

For how the add-on wires the three resources, in which order, and why, see ADR 38.

  • Why does saving the Orbit connect the instance to it? An Orbit no instance points at indexes a graph nothing queries. The add-on means GitLab uses Orbit, so the switch wires both sides.
  • Why does a save keep an Orbit on another Siphon of the instance? Someone set that reference with kubectl on purpose, and the form has no field to show it. Replacing it would quietly move the graph to another datalake.
  • Why does the panel show a connection row besides the endpoint? The endpoint says what the Orbit serves. Whether GitLab uses it is the OrbitConnected condition of the instance, which can be False with an endpoint, for example while the Secret of the JWT key is missing.
  • Why is the Orbit deleted before the Siphon? An Orbit without its Siphon waits with no way to recover. Deleting the Orbit first never leaves that state behind.
  • Why does deleting a Siphon need permission on Orbit resources? A caller who cannot list Orbit resources cannot show that none uses the Siphon, so the deletion is refused rather than risked.