Bring-Your-Own Backends¶

When you set managed: false on a backend spec, the operator reads connection parameters from a Kubernetes Secret you provide in the instance namespace. This gives you full control over the backend lifecycle.

When to use BYO backends¶

You have an existing database or Redis cluster and want to point GitLab at it.
You share a database cluster across multiple GitLab instances (e.g. dev/staging).
You manage backends with your own tooling and want the operator to consume only connection info.
You want a cost-efficient setup for non-production environments.

BYO PostgreSQL¶

Minimal example¶

# examples/gitlabinstance-ce-min.yaml
apiVersion: k8s.bnerd.com/v1alpha1
kind: GitlabInstance
metadata:
  name: my-gitlab-ce
  namespace: my-gitlab-ce
spec:
  version: "17"
  edition: ce

  domains:
    gitlab:   git.example.com
    registry: registry.example.com
    kas:      kas.example.com

  postgres:
    managed: false
    credentialsSecret: my-gitlab-ce-pg-credentials

  redis:
    managed: false
    credentialsSecret: my-gitlab-ce-redis-credentials

  objectStorage:
    credentialsSecret: my-gitlab-ce-s3-credentials

PostgreSQL credentials Secret shape¶

The Secret must contain exactly these string keys:

apiVersion: v1
kind: Secret
metadata:
  name: my-gitlab-ce-pg-credentials
  namespace: my-gitlab-ce
stringData:
  host: pg.example.com      # required — hostname or IP of the Postgres instance
  port: "5432"              # required — as a string
  password: "<password>"    # required — the GitLab database user password

The operator reads host and port and passes them to the chart as global.psql.host and global.psql.port. The Secret is referenced by name for the chart's global.psql.password.secret / global.psql.password.key: password.

Database and user must exist

The operator does not create the GitLab database or database user. You must provision gitlabhq_production (or your chosen DB name) and a gitlab user with appropriate permissions before applying the GitlabInstance. The GitLab chart runs Rails migrations automatically on chart install/upgrade.

What the chart receives¶

global:
  psql:
    host: pg.example.com
    port: 5432
    password:
      secret: my-gitlab-ce-pg-credentials
      key: password

BYO Redis¶

Redis credentials Secret shape¶

apiVersion: v1
kind: Secret
metadata:
  name: my-gitlab-ce-redis-credentials
  namespace: my-gitlab-ce
stringData:
  host: redis.example.com   # required — hostname or IP of the Redis instance
  port: "6379"              # required — as a string
  password: "<password>"    # required — the Redis AUTH password

The operator reads host and port and passes them to the chart as global.redis.host and global.redis.port. The Secret is referenced for global.redis.password.secret / global.redis.password.key: password.

What the chart receives¶

global:
  redis:
    host: redis.example.com
    port: 6379
    password:
      secret: my-gitlab-ce-redis-credentials
      key: password

Missing Secret behaviour¶

If the referenced Secret does not exist when the operator reconciles, it sets phase: Pending and requeues after 30 seconds. The instance will stay Pending until the Secret appears. There is no permanent failure for a missing BYO credentials Secret — the operator simply waits.

# Check why an instance is Pending
kubectl describe gli my-gitlab-ce -n my-gitlab-ce
# Look for: "waiting for dependency secret" in conditions or events

Mixing managed and BYO¶

You can mix the two models. For example, use a managed Percona PG cluster but a BYO Redis:

spec:
  postgres:
    managed: true
    topology: standalone

  redis:
    managed: false
    credentialsSecret: shared-redis-credentials

The operator handles each backend independently.