Skip to content

GitLab Operator

A Kubernetes operator that manages GitLab instances declaratively via Custom Resource Definitions. Describe the instance you want in YAML, and the operator provisions the Flux HelmRelease, managed databases, Redis, object storage wiring, and Secrets for you.

Who this is for

Platform Engineers

You run Kubernetes and want to offer managed GitLab as a self-service product to internal teams or external customers. Start with Architecture to understand the reconcile model, then Installation to install the operator and its prerequisites.

Managed-Service Operators

You operate GitLab for multiple tenants and need fast provisioning, declarative upgrades, and consistent backend topology without handwriting Helm values per customer. Start with the Quick Start, then Configuration Profiles and Managed Backends.

Single-Instance Administrators

You administer one GitLab for your organisation and want declarative version management and reproducible configuration instead of manual helm upgrade commands. Start with the Quick Start and Version Management.

Not sure yet?

Follow the Quick Start — it deploys a working GitLab Community Edition in about 15 minutes and introduces all three CRDs.

Architecture at a glance

flowchart LR
    HQ([hq / user\nkubectl apply]) -->|GitlabInstance CR| K8s[(Kubernetes API)]
    K8s --> Op[bnerd-gitlab-operator\nreconcile loop]

    Op -->|creates/updates| Secrets[Operator Secrets\ncredentials]
    Op -->|emits| HR[Flux HelmRelease\nhelm.toolkit.fluxcd.io/v2beta1]
    Op -->|optional| PG[PerconaPGCluster\nPercona PG Operator]
    Op -->|optional| Redis[Redis / RedisReplication\nOT-Container-Kit]
    Op -->|optional EE| ES[Elasticsearch\nECK]

    HR -->|Flux installs| Chart[GitLab Helm Chart\ncharts.gitlab.io]
    Chart --> Pods[GitLab Pods]

    PG --> Pods
    Redis --> Pods
    ES --> Pods
    Secrets --> Pods

    style Op fill:#6366f1,stroke:#4f46e5,color:#fff
    style HR fill:#16a34a,stroke:#15803d,color:#fff

The operator watches GitlabInstance resources and translates them into everything needed to run GitLab: operator-owned Secrets, a Flux HelmRelease that drives the upstream GitLab chart, and optional managed backend clusters (PostgreSQL, Redis, Elasticsearch). See Architecture for the full reconcile sequence.

Why this operator instead of plain Helm?

Concern Plain Helm This Operator
Backend provisioning Manual PerconaPGCluster / Redis setup managed: true auto-provisions with topology and readiness gating
Credential management Inline or manually-created secrets credentialsSecret references — native Sealed Secrets / Vault / External Secrets
Version upgrades Manual helm upgrade with required-stop awareness Bump spec.version; operator resolves the chart version and emits the upgrade
Multi-tenant consistency Copy-paste values per customer GitlabProfile supplies opinionated defaults across a class of deployments
Backend retention safety Your responsibility Managed data backends are explicitly retained on deletion — no accidental data loss
Status observability helm status + pod logs CRD status subresource: phase, host, observedVersion, conditions

CRDs at a glance

CRD Scope Short name Purpose
GitlabInstance Namespaced gli One CR = one GitLab deployment. The primary workload resource.
GitlabVersionMap Cluster glvm Maps GitLab app versions to Helm chart versions; supports aliases and prefix resolution.
GitlabProfile Cluster glprofile Reusable backend topology and backup schedule defaults (production, testing, or custom).

API version: k8s.bnerd.com/v1alpha1. See CRD Mental Model for when to use which.