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

• One of these GitLab versions:
  • 19.4.4 or a later 19.4 patch release
  • 19.5.2 or a later 19.5 patch release
  • 19.6.0 or later
• 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.
• The latest GitLab Orbit release and Helm chart.

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.

Reference architectures

GitLab Dedicated sizes GitLab Orbit for these tiers. Pod cells give the pod count and the limits for one pod, and node cells give the node count and size. Repository count and push rate drive the indexer load more than user count.

Each Siphon deployment runs one pod with up to 2 CPU and 2 to 10 GiB of memory. For ClickHouse, see Memory and disk. For the chart defaults, see values.yaml.

High availability

For ClickHouse high availability, see High availability.

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 Reference architectures.

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.