CRD Reference

Full field reference for all three CRDs in the k8s.bnerd.com/v1alpha1 API group.

---

GitlabInstance

Scope: Namespaced | Short name: gli

One CR = one GitLab deployment. The primary workload resource.

Print columns (kubectl get gli)

Column	JSONPath	Description
Phase	.status.phase	Lifecycle phase
Host	.status.host	Primary GitLab URL
Version	.status.observedVersion	Running GitLab version
Age	.metadata.creationTimestamp	Resource age

Spec fields

Top-level

Field	Type	Required	Default	Description
spec.version	string	no	latest alias	GitLab application version to deploy. Accepts exact versions ("17.11.7"), major prefix ("17", "18"), or aliases ("latest", "stable"). Resolved via GitlabVersionMap/default.
spec.edition	ce | ee	no	ce	GitLab edition. ee requires spec.licenseSecret. Elasticsearch is only provisioned for ee.
spec.profile	string	no	—	Name of a cluster-scoped GitlabProfile CR to pull backend topology defaults from.
spec.licenseSecret	string	no	—	Name of a Secret in the instance namespace containing the EE license file under key license. Required when edition: ee.

spec.domains

Field	Type	Required	Description
spec.domains.gitlab	string	yes	Primary GitLab web/API domain (e.g. git.example.com).
spec.domains.registry	string	no	Container registry domain.
spec.domains.kas	string	no	GitLab Agent Server (KAS) domain.
spec.domains.pages	string	no	GitLab Pages wildcard domain.

spec.postgres

Field	Type	Required	Default	Description
spec.postgres.managed	bool	no	false	true = operator provisions a PerconaPGCluster. false = BYO via credentialsSecret.
spec.postgres.topology	ha | standalone	no	profile default or standalone	Deployment topology (managed only). ha provisions a multi-replica cluster.
spec.postgres.pgbouncer	bool	no	false	Enable PgBouncer connection pooler sidecar (managed only). Recommended for production.
spec.postgres.nodes	int	no	profile default or 3 (HA)	Number of Postgres replicas (managed only).
spec.postgres.credentialsSecret	string	no	—	BYO: name of a Secret in the instance namespace. Required when managed: false. Keys: host, port, password.

spec.redis

Field	Type	Required	Default	Description
spec.redis.managed	bool	no	false	true = operator provisions OT-Container-Kit Redis CRs. false = BYO.
spec.redis.topology	ha | standalone	no	profile default or standalone	Redis topology (managed only). ha uses Redis Sentinel for quorum.
spec.redis.nodes	int	no	profile default	Number of Redis replicas (managed only).
spec.redis.credentialsSecret	string	no	—	BYO: name of a Secret. Required when managed: false. Keys: host, port, password.

spec.elasticsearch

Field	Type	Required	Default	Description
spec.elasticsearch.managed	bool	no	false	true = operator provisions an ECK Elasticsearch cluster. EE + licenseSecret required.
spec.elasticsearch.nodes	int	no	profile default or 3	Number of Elasticsearch nodes (managed only).

spec.objectStorage

Field	Type	Required	Description
spec.objectStorage.credentialsSecret	string	no (mandatory for GitLab 19+)	Name of the hq-provided S3 Secret. Keys: accessKey, secretKey, endpoint, region, and one bucket.<class> per storage class.

spec.smtp

Field	Type	Required	Description
spec.smtp.credentialsSecret	string	no	Name of a Secret with SMTP parameters (keys: host, port, user, password).

spec.backups

Field	Type	Required	Description
spec.backups.schedule	string	no	Cron expression for the backup schedule (e.g. "30 2 * * *").
spec.backups.objectStorage.credentialsSecret	string	no	Name of the S3 Secret for backup storage. Uses the same key shape as spec.objectStorage.credentialsSecret.

spec.placement

Field	Type	Required	Description
spec.placement.nodeSelector	map[string]string	no	Node selector applied to GitLab workloads via the HelmRelease.
spec.placement.tolerations	[]Toleration	no	Kubernetes tolerations for tainted nodes. Standard corev1.Toleration format.

spec.helm

Field	Type	Required	Description
spec.helm.version	string	no	Escape hatch: pins the operator to a specific GitLab Helm chart version, bypassing GitlabVersionMap resolution entirely.
spec.helm.values	object	no	Arbitrary Helm chart values deep-merged last (highest precedence). Accepts any valid GitLab chart value key. Use for configuration not exposed by the operator's CRD.

Status fields

Field	Type	Description
status.phase	string	Lifecycle phase: Pending | Provisioning | Deploying | Ready | Failed.
status.host	string	Primary GitLab URL (https://<spec.domains.gitlab>). Set once the HelmRelease is emitted.
status.observedVersion	string	GitLab application version from the last reconcile (mirrors spec.version).
status.chartVersion	string	GitLab Helm chart version currently deployed.
status.conditions	[]metav1.Condition	Standard Kubernetes conditions. Types: Ready, Progressing, BackendsReady.
status.secrets	[]string	Names of operator-owned Secrets tracked for finalizer GC.

Phase transitions

Pending ──▶ Provisioning ──▶ Deploying ──▶ Ready
   ▲                                         │
   └─────────────────── (retry) ─────────────┘
                                    │
                              Failed (permanent)

• Pending — waiting for a referenced dependency Secret.
• Provisioning — waiting for one or more managed backends to become ready.
• Deploying — HelmRelease has been applied; Flux is installing/upgrading the chart.
• Ready — HelmRelease reports Ready=True.
• Failed — permanent error (validation, missing CRD, bad version, incomplete S3 buckets). Manual correction required.

---

GitlabVersionMap

Scope: Cluster | Short name: glvm

Maps GitLab application version strings to GitLab Helm chart versions. The operator always looks up the instance named default.

Print columns

Column	JSONPath	Description
Latest	.spec.aliases.latest	The alias target for latest
Age	.metadata.creationTimestamp	Resource age

Spec fields

Field	Type	Required	Description
spec.versions	map[string]VersionEntry	yes	Maps a GitLab version string (e.g. "17.11.7") to a chart version + optional image tag.
spec.versions[*].chartVersion	string	yes	GitLab Helm chart version for this GitLab release (e.g. "8.11.8").
spec.versions[*].image	string	no	GitLab image tag override. If empty the chart's default image is used.
spec.aliases	map[string]string	no	Maps symbolic names to version strings present in spec.versions. Common aliases: latest, stable, "17", "18", "19".

Version resolution algorithm

Given spec.version on a GitlabInstance:

1. If spec.helm.version is set → use it directly (bypasses this map).
2. Check spec.aliases for an exact match → resolve to the aliased version string.
3. Check spec.versions for an exact match → use chartVersion.
4. Check spec.versions for a prefix match ("18" matches "18.x.y", "18.5" matches "18.5.y") → use the highest matching entry.
5. If no match → permanent VersionResolutionFailed condition.

---

GitlabProfile

Scope: Cluster | Short name: glprofile

Reusable defaults for a class of GitLab deployments. Referenced by GitlabInstance.spec.profile.

Print columns

Column	JSONPath	Description
PG-Topology	.spec.defaults.postgres.topology	Default Postgres topology
Age	.metadata.creationTimestamp	Resource age

Spec fields

Field	Type	Required	Description
spec.defaults.postgres.topology	ha | standalone	no	Default Postgres deployment topology for instances referencing this profile.
spec.defaults.postgres.nodes	int	no	Default number of Postgres nodes/replicas.
spec.defaults.redis.topology	ha | standalone	no	Default Redis topology. ha uses Sentinel.
spec.defaults.redis.nodes	int	no	Default number of Redis nodes.
spec.defaults.elasticsearch.topology	string	no	Default Elasticsearch topology (informational; currently unused in value composition).
spec.defaults.elasticsearch.nodes	int	no	Default number of Elasticsearch nodes for managed ECK deployments.
spec.defaults.backupSchedule	string	no	Default cron expression for backup schedule (e.g. "30 2 * * *").

Profile defaults are applied as the lowest-priority layer. An explicit setting on the GitlabInstance always overrides the profile default.