Get started with GitLab Orbit on GitLab Self-Managed

GitLab Orbit depends on Kubernetes, NATS, object storage, and ClickHouse, and installs none of them. Set up all four before you install GitLab Orbit.

Prerequisites

• A GitLab version that your GitLab Orbit version supports. See Version requirements.
• Administrator access to the GitLab instance and to its PostgreSQL server.
• A maintenance window for one PostgreSQL restart.
• ClickHouse, set up for GitLab.
• Kubernetes 1.36 or later. For Kubernetes 1.33 to 1.35, see Image volumes.
• NATS with JetStream turned on.
• An S3-compatible or Google Cloud Storage bucket for Siphon.
• A GitLab Orbit release and a Helm chart release that support each other. See Version requirements.

Installation order

Each step depends on the step before it:

1. Set up ClickHouse and run the GitLab ClickHouse migrations.
2. Install NATS on the cluster with JetStream turned on.
3. Set up data replication to copy GitLab rows into the ClickHouse data lake.
4. Set up GitLab Orbit and turn on indexing for a top-level group.

You can verify steps 1 to 3 before you install GitLab Orbit.

Sizing

For the pod, node, NATS, Siphon, and ClickHouse sizes, see GitLab Orbit sizing. For the chart defaults, see values.yaml.

High availability

For ClickHouse high availability, see High availability. For a NATS cluster, see Configure a NATS cluster.

Image volumes

Siphon mounts the gitlab-siphon-tables image as an image volume. Image volumes need Kubernetes 1.35 or later, or the ImageVolume feature gate on Kubernetes 1.33 and 1.34, and a container runtime that supports them. Some managed services, such as Amazon EKS, do not let you turn on the gate. When the gate is off, Kubernetes drops the volume without an error, and the Siphon pods fail with no such file errors under /etc/tables.

If your cluster cannot use image volumes, set splitTables.volumeMode: initCopy in siphon-values.yaml. For more information, see Split mode without ImageVolume.

Configure NATS

Siphon publishes every changed row to a NATS JetStream stream, and Siphon and GitLab Orbit read from it. NATS needs JetStream, a persistent volume, and a max_payload of 64 MB, because some GitLab rows are larger than the 1 MB default.

To configure NATS, set these values in the NATS Helm chart:

config:
  jetstream:
    enabled: true
    fileStore:
      pvc:
        size: <volume_size>
  merge:
    max_payload: << 64MB >>

Replace the following values:

• <volume_size>: the size of the JetStream volume, from NATS.

Keep the << and >> marks around 64MB, so the chart writes the value without quotes.

Object storage

Siphon writes snapshots and oversize rows to an S3-compatible or Google Cloud Storage bucket. For the credentials, see Object storage for large rows.

Shared configuration values

Use the same value in every component that reads it. No component checks these values against the others, so a mismatch stops data without an error.

To use a stream name other than siphon_stream_main_db, set both stream_name values in siphon-values.yaml and schedule.tasks.siphon.events_stream_name in orbit-values.yaml.