ADR: Delivery of Orbit and DIP to Self Managed

- [Security](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/docs/design-documents/security.md)

- [Observability](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/docs/design-documents/observability.md)

Delivery to GitLab Self-Managed is the exception, and is recorded as an ADR in this repository:

- [ADR 001: Deliver Orbit and DIP as independent charts](decisions/01-delivery.md)

## Resources

| Resource | Location |

---

title: "Orbit ADR 001: Deliver Orbit and DIP as independent charts"

owning-stage: "~devops::gitlab delivery"

description: "Decision to deliver Orbit and the Data Insights Platform as two independent packages"

toc_hide: true

---

<!-- Design Documents often contain forward-looking statements -->

<!-- vale gitlab.FutureTense = NO -->

## Status

**Proposed.**

## Context

[GitLab Orbit](../) and the [Data Insights Platform](/handbook/engineering/architecture/design-documents/data_insights_platform/) (DIP)

are being delivered to GitLab Self-Managed. Orbit depends on DIP, and DIP is made up of three components

that most Self-Managed installations do not run today:

1. [**Siphon**](https://gitlab.com/gitlab-org/analytics-section/siphon): manages replication from GitLab's PostgreSQL data into ClickHouse.

1. [**NATS**](https://docs.nats.io/): the messaging system that carries the replicated change data.

1. [**ClickHouse**](https://clickhouse.com/docs): the column-oriented database management system that stores it.

Several properties of these components shape how they can be delivered:

1. Orbit and DIP are complex to configure.

1. ClickHouse is also an optional GitLab component outside of DIP.

1. There are discussions to make NATS a core GitLab component outside of DIP and Orbit. ([issue #17582](https://gitlab.com/groups/gitlab-org/-/work_items/17582))

1. DIP is coupled to the GitLab Rails PostgreSQL migrations.

1. DIP has upgrade constraints that must be respected when GitLab and DIP are upgraded.

1. Neither DIP nor Orbit uses [Theseus](/handbook/engineering/architecture/design-documents/theseus_platform_vision/) as of now.

For Self-Managed customers to install, configure, and upgrade Orbit and DIP without undue effort,

we need to decide two things: how to shape the packages, and how those packages are installed.

### Package sizing

Shipping Orbit, Siphon, NATS, and ClickHouse as individual components is not feasible because the burden

of wiring and maintaining that stack is too high and would fall entirely on the customer.

The components need to be grouped into reasonably sized bundles instead. The open question is whether that

is one bundle or two. That means weighing the future demand for DIP outside of the Orbit context against the

added complexity of shipping both independently.

```mermaid

flowchart LR

    subgraph opt1["Option 1: one Orbit bundle"]

        direction TB

        P1["Orbit + DIP chart"]

        P1 --> A1["Orbit"]

        P1 --> A2["Siphon"]

        P1 --> A3["NATS"]

        P1 --> A4[(ClickHouse)]

    end

    subgraph opt2["Option 2: Orbit and DIP as independent bundles"]

        direction TB

        P2["Orbit chart"]

        P3["DIP chart"]

        P2 --> B1["Orbit"]

        P3 --> B2["Siphon"]

        P3 --> B3["NATS"]

        P3 --> B4[(ClickHouse)]

        P2 -. requires .-> P3

    end

    classDef chart fill:#333,color:#fff,stroke:#333

    classDef orbit fill:#FC6D26,color:#fff,stroke:#FC6D26

    classDef dip fill:#6E49CB,color:#fff,stroke:#6E49CB

    classDef store fill:#FFCC00,color:#000,stroke:#FFCC00

    class P1,P2,P3 chart

    class A1,B1 orbit

    class A2,A3,B2,B3 dip

    class A4,B4 store

```

### Install experience

The [GitLab Helm chart](https://docs.gitlab.com/charts/) is the de facto delivery method for cloud-native

customers today, and it bundles core GitLab together with optional satellite components such as the

AI Gateway and OpenBao. With GitLab moving towards a more modular install experience, we need to decide

whether the Orbit and DIP charts follow that pattern or stay outside of the GitLab Helm chart.

```mermaid

flowchart LR

    subgraph int["Integrated into the GitLab chart"]

        direction TB

        G1["GitLab chart"]

        O1["Orbit/DIP chart(s)"]

        G1 --> C1["GitLab core"]

        G1 --> |fully integrated|O1

        G1 --> S1["Satellite components<br/>AI Gateway, OpenBao"]

    end

    subgraph sep["Outside of the GitLab chart"]

        direction TB

        G2["GitLab chart"]

        O2["Orbit/DIP chart(s)"]

        G2 -.-> |manual wiring|O2

        G2 --> C2["GitLab core"]

        G2 --> S2["Satellite components<br/>AI Gateway, OpenBao"]

    end

    classDef chart fill:#333,color:#fff,stroke:#333

    classDef orbit fill:#FC6D26,color:#fff,stroke:#FC6D26

    class G1,G2,C1,C2,S1,S2 chart

    class O1,O2 orbit

```

### Isolation and upgrade constraints

Siphon is designed as a general data processing component that is not bound to GitLab, but the replication

it performs for DIP tracks the GitLab Rails schema. Siphon needs a change data capture (CDC) configuration

that matches that schema, which means DIP and GitLab upgrades must be synchronized.

We publish the CDC table mapping as an independent bundle that Siphon pulls on startup, so the mapping does

not have to ship inside Siphon itself. Delivery still has to guarantee two things: that Siphon references the

CDC bundle matching the installed GitLab version, and that Siphon does not start before the GitLab Rails

migrations have completed.

ClickHouse may already be installed for other GitLab integrations, and NATS may become a core GitLab component.

The chart that ships DIP therefore cannot assume that it owns either of them. It must work against externally

hosted NATS and ClickHouse instances as well as the ones it deploys itself.

## Decision

Orbit and DIP will be delivered as **two independent charts**, and **neither will be integrated into the

GitLab Helm chart**.

Integrating these components with a GitLab installation will require thorough documentation, and can later be

automated with orchestration tooling such as the

[GitLab Kubernetes Operator](/handbook/engineering/architecture/design-documents/theseus_platform_vision/#622-the-gitlab-kubernetes-operator)

and [Bridge](/handbook/engineering/architecture/design-documents/theseus_platform_vision/#623-bridge).

Omnibus users will be able to consume the same charts through

[Omnibus-Adjacent Kubernetes](/handbook/engineering/architecture/design-documents/omnibus_adjacent_kubernetes/) (OAK).

Whichever chart ships DIP must also be able to run against an **externally managed ClickHouse and NATS**

rather than only deploying its own. ClickHouse is already an optional GitLab component outside of DIP and

NATS is planned to become a core one, so an installation may well run either of them before DIP is installed.

A customer may also want to run them elsewhere entirely, such as ClickHouse Cloud. Both must be configurable

as external endpoints, with the chart's own deployments serving as the default for installations that have

neither.

## Consequences

### Positive

1. **DIP is available outside of Orbit.** Customers who want the data platform without the graph can install

   the DIP chart on its own, which is the demand the split anticipates.

1. **No lock-in on chart internals.** Orbit and DIP can move to Theseus-generated charts without having to

   migrate users across changes to configuration format and immutable fields such as selector labels.

1. **Upgrades can be sequenced.** DIP's coupling to the GitLab Rails migrations is respected by upgrading the

   charts in order, rather than by holding a bundled release back to the slowest component.

1. **The GitLab Helm chart does not grow.** It keeps moving towards a more modular install experience, where

   customers pick the components they want instead of receiving one bundle that carries everything.

1. **Existing ClickHouse and NATS deployments can be reused.** A customer who already runs either can

   configure the DIP package to use these instead. If NATS becomes a mandatory component of GitLab core,

   NATS will be moved out of the DIP chart.

### Negative

1. **Customers wire Orbit and DIP themselves.** Configuration that a shared bundle would pass along has to

   be supplied by hand until orchestration tooling lands. The most notable example is the GitLab version,

   which DIP needs in order to configure data streaming correctly.

1. **Documentation carries the integration.** Until the GitLab Kubernetes Operator and Bridge automate it,

   thorough install and upgrade documentation, including the upgrade ordering constraints, is the primary

   user experience.

1. **Less initial delight for existing chart users.** Enabling Orbit is not a single value in a chart the

   customer already runs; it is installing and wiring two more charts.

1. **The DIP chart carries two topologies.** Supporting both bundled and external ClickHouse and NATS widens

   the configuration surface and the matrix that has to be documented and tested.

## Alternatives Considered

### Alternative: one bundle containing Orbit and DIP

#### Approach

Ship a single package containing Orbit, Siphon, NATS, and ClickHouse.

#### Why not chosen

This is the most straightforward delivery option and the best experience for Orbit users, but it makes DIP

reachable only through Orbit. Given the expected demand for DIP outside of the Orbit context, and for

ClickHouse and NATS outside of DIP, the bundle would have to be unpicked later, after customers have

already installed it.

### Alternative: integrate Orbit and DIP into the GitLab Helm chart

#### Approach

Add Orbit and DIP to the GitLab Helm chart as optional components, alongside the AI Gateway and OpenBao,

so existing chart users can enable them without installing anything else.

#### Why not chosen

The integration is attractive on two counts: existing chart users could enable Orbit and DIP without wiring

separate charts, and configuration defined by the GitLab Helm chart, such as the GitLab version DIP needs

for data streaming, would be shared without user interaction.

Both advantages are outweighed by the lock-in effect. Bundling every component into a single chart makes

handling breaking changes, or swapping a component out, difficult. With Orbit and DIP moving towards Theseus,

replacing a hand-written chart with a generated one inside a customer-facing bundle would be a breaking change

in itself, because the generated chart uses a different configuration format.

Keeping the charts independent avoids that. The hand-written and the Theseus-generated chart can coexist while

customers migrate at their own pace, supported by our documentation and guidance.

## References

- [GitLab Orbit](../): the design document this decision belongs to.

- [Data Insights Platform](/handbook/engineering/architecture/design-documents/data_insights_platform/):

  the platform Orbit depends on, and the second of the two charts.

- [Siphon](/handbook/engineering/architecture/design-documents/siphon/): the replication component and its

  coupling to the GitLab Rails schema.

- [Omnibus-Adjacent Kubernetes](/handbook/engineering/architecture/design-documents/omnibus_adjacent_kubernetes/):

  how Omnibus users consume Kubernetes-only components.

- [Theseus Platform Vision](/handbook/engineering/architecture/design-documents/theseus_platform_vision/):

  the per-component chart model Orbit and DIP move towards, and the source of the GitLab Kubernetes Operator

  and Bridge.

- [Theseus ADR 004: Independent per-component deploys for GitLab.com; bundled releases for Self-Managed](/handbook/engineering/architecture/design-documents/theseus_platform_vision/decisions/004_independent_vs_bundled_releases/):

  the release-shape decision this ADR sits under.