Bridge custom resource reference

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
Status: Experiment

Bridge writes, and the Operator reconciles, the custom resources of the apps.gitlab.com/v2alpha1 API group. Use this reference to write the resources with kubectl or a GitOps tool.

The v2alpha1 resources are an experiment in an early development phase. Fields can change or be removed without notice.

A field that is not required can be left out. Validation lists the constraints of a single field, and Rules the checks that span several fields. The Kubernetes API server enforces both when you create or update a resource.

Resources

GitLabCore

GitLabCore is a complete DevOps platform, delivered in a single application.

It is a definition of its own, separate from the v1beta1 GitLab resource, and the two do not convert into each other.

Field	Type	Required	Description
`apiVersion`	string		`apps.gitlab.com/v2alpha1`
`kind`	string		`GitLabCore`
`metadata`	ObjectMeta	No	For the fields of `metadata`, see the Kubernetes API reference.
`spec`	GitLabCoreSpec	No	Specification of the desired behavior of a GitLab instance.
`status`	GitLabCoreStatus	No	Most recently observed status of the GitLab instance. It is read-only to the user.

GitLabSecrets

GitLabSecrets declares the Secrets that the GitLab chart generates, for a controller to create instead of the chart’s shared-secrets hook Job.

The GitLab chart renders it under shared-secrets.provider: controller, for a GitLabCore to own.

Field	Type	Required	Description
`apiVersion`	string		`apps.gitlab.com/v2alpha1`
`kind`	string		`GitLabSecrets`
`metadata`	ObjectMeta	No	For the fields of `metadata`, see the Kubernetes API reference.
`spec`	GitLabSecretsSpec	No	Specification of the declared Secrets.
`status`	GitLabSecretsStatus	No	Most recently observed status of the declared Secrets. It is read-only to the user.

Orbit

Orbit deploys the GitLab Knowledge Graph against a GitLab instance and the Siphon that feeds it.

It is a namespace-scoped peer of GitLabCore and Siphon, backed by the Orbit chart.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

the name must be at most 44 characters: the chart names each indexer pool <name>-orbit-indexer-<pool> and cuts that name at 63 characters, so a longer name truncates the default pools sdlc and code, and two pools that share a prefix collide

Field	Type	Required	Description
`apiVersion`	string		`apps.gitlab.com/v2alpha1`
`kind`	string		`Orbit`
`metadata`	ObjectMeta	No	For the fields of `metadata`, see the Kubernetes API reference.
`spec`	OrbitSpec	No	Specification of the desired behavior of an Orbit deployment.
`status`	OrbitStatus	No	Most recently observed status of the Orbit deployment. It is read-only to the user.

Siphon

Siphon streams change data capture from the PostgreSQL database of a GitLab instance into ClickHouse, through NATS JetStream.

It is a namespace-scoped peer of GitLabCore and Orbit, backed by the Siphon chart.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

the name must be at most 31 characters: the Operator derives Deployment, ServiceAccount and pod selector names from it, and the longest of those is <name>-siphon-reconciler-clickhouse-sa, which a 63 character label value has to hold

Field	Type	Required	Description
`apiVersion`	string		`apps.gitlab.com/v2alpha1`
`kind`	string		`Siphon`
`metadata`	ObjectMeta	No	For the fields of `metadata`, see the Kubernetes API reference.
`spec`	SiphonSpec	No	Specification of the desired behavior of a Siphon deployment.
`status`	SiphonStatus	No	Most recently observed status of the Siphon deployment. It is read-only to the user.

Field types

BackupBackend

BackupBackend is the kind of object storage the backups go to.

Underlying type: string.

Validation:

Enum: [s3 gcs azure]

Used by: BackupStorageSpec.

Value	Description
`s3`	BackupBackendS3 is S3 or an S3 compatible storage.
`gcs`	BackupBackendGCS is Google Cloud Storage.
`azure`	BackupBackendAzure is Azure Blob Storage.

BackupStorageSpec

BackupStorageSpec is the object storage the backups go to.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

gcpProject is required for the gcs backend and not allowed for any other

Used by: ToolboxBackupsSpec.

Field	Type	Required	Default	Description
`backend`	BackupBackend	No	`s3`	Backend is the kind of object storage. Validation: `Enum: [s3 gcs azure]`.
`secretRef`	SecretKeySelector			SecretRef selects the key of the Secret that holds the configuration of the storage, in the format the backend expects: an s3cmd configuration for `s3`, a service account key for `gcs`, or an azcopy configuration for `azure`. See https://docs.gitlab.com/charts/backup-restore/#object-storage.
`gcpProject`	string	No		GCPProject is the Google Cloud project of the gcs backend. Validation: `MaxLength: 63`, `MinLength: 1`.

CertManagerSpec

CertManagerSpec points the chart-provisioned Gateway at an existing cert-manager Issuer or ClusterIssuer. The chart has no equivalent of its own for the Gateway: its global.gatewayApi.configureCertmanager flag only provisions a Let’s Encrypt ACME Issuer, under a name it picks itself and against an email address it also demands, which the Operator always turns off, so the Operator sets the cert-manager annotation directly instead.

Used by: EnvoyGatewayControllerSpec, GatewayClassSpec.

Field	Type	Required	Default	Description
`issuerRef`	IssuerRef			IssuerRef selects the cert-manager Issuer or ClusterIssuer to request certificates from.

CertificateAlgorithm

CertificateAlgorithm is the key algorithm of a certificate set. Ed25519 is not supported.

Underlying type: string.

Validation:

Enum: [rsa ecdsa]
MaxLength: 16

Used by: CertificateAuthority.

Value	Description
`rsa`	CertificateAlgorithmRSA is an RSA key.
`ecdsa`	CertificateAlgorithmECDSA is an ECDSA key.

CertificateAuthority

CertificateAuthority is the subject and key of the CA of a certificate set. An rsa key is even and from 2048 to 8192 bits. An ecdsa key is 256, 384, or 521 bits.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

an rsa keySize is even and from 2048 to 8192
an ecdsa keySize is 256, 384, or 521

Used by: SelfSignedCertificate.

Field	Type	Description
`commonName`	string	CommonName is the subject common name of the CA. Validation: `MaxLength: 253`, `MinLength: 1`.
`organization`	string	Organization is the subject organization of the CA. Validation: `MaxLength: 253`, `MinLength: 1`.
`organizationalUnit`	string	OrganizationalUnit is the subject organizational unit of the CA. Validation: `MaxLength: 253`, `MinLength: 1`.
`algorithm`	CertificateAlgorithm	Algorithm is the key algorithm of the CA and the wildcard certificate. Validation: `Enum: [rsa ecdsa]`, `MaxLength: 16`.
`keySize`	integer	KeySize is the key size, in bits.

CertificatesSpec

CertificatesSpec adds certificate authorities GitLab trusts beyond its system ones.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`customCAs`	CustomCASource array	No		CustomCAs are the administrator’s own certificate authorities, such as a corporate CA. They set `global.certificates.customCAs` of the chart, which `spec.chart.values` replace. Every key becomes a file in one directory, so two entries must not share a key. Validation: `MaxItems: 64`.

Charset

Charset is the character set of a random value.

Underlying type: string.

Validation:

Enum: [alphanumeric hex lowerAlphanumeric]
MaxLength: 32

Used by: RailsSecretField, SecretGenerator.

Value	Description
`alphanumeric`	CharsetAlphanumeric is `a-zA-Z0-9`.
`hex`	CharsetHex is `a-f0-9`.
`lowerAlphanumeric`	CharsetLowerAlphanumeric is `a-z0-9`.

ChartValues

ChartValues holds unstructured values for rendering a Helm chart.

Used by: ChartValuesSpec, GitLabCoreChartSpec.

ChartValuesSpec

ChartValuesSpec carries the free-form values a bundled chart is rendered with. The version of the chart is selected by a StaticVersionSpec beside it.

The Operator derives values from the structured fields of the specification and merges these values over that result. The free-form values win on conflict, which keeps them a working escape hatch for every setting the structured layer does not cover yet.

Used by: OrbitSpec, SiphonSpec.

Field	Type	Required	Default	Description
`values`	ChartValues	No		Values is the set of Helm values that is used to render the chart.

ClickHouseGraphSpec

ClickHouseGraphSpec is the connection to the ClickHouse database that holds the graph.

The database must already exist. The dispatcher creates and migrates the tables in it.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

spec.graph.port is the ClickHouse HTTP interface port, not the native protocol; 9000 is the native protocol and Orbit does not speak it
spec.graph.readUser and spec.graph.readPasswordSecretRef are set together

Used by: OrbitSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the ClickHouse server. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`port`	integer	No	`8123`	Port is the port of the ClickHouse HTTP interface, not of the native protocol. Validation: `Maximum: 65535`, `Minimum: 1`.
`database`	string			Database is the database that holds the graph, for example `orbit`. Validation: `MaxLength: 63`, `MinLength: 1`.
`user`	string			User is the ClickHouse user the indexer and the dispatcher write the graph as, for example `gkg_writer`. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of that user.
`readUser`	string	No		ReadUser is the ClickHouse user the webserver reads the graph as, for example `gkg_reader`. Left unset, the webserver reads as User. Validation: `MaxLength: 63`, `MinLength: 1`.
`readPasswordSecretRef`	SecretKeySelector	No		ReadPasswordSecretRef selects the key of the Secret that holds the password of ReadUser.
`ssl`	boolean	No	`false`	SSL turns TLS on for the HTTP connection. The port changes with it, so set both.

ClickHouseSinkSpec

ClickHouseSinkSpec is the connection to the ClickHouse server the stream is written to.

The database must already hold the target tables. For GitLab those are created by the ClickHouse migrations of the application, not by Siphon, so the database and the user are required rather than defaulted: the Operator uses the reference it is given instead of guessing the schema layout of the instance.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

spec.sink.port is the ClickHouse native protocol port, not the HTTP interface; 8123 is the HTTP interface and Siphon does not speak it

Used by: SiphonSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the ClickHouse server. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`port`	integer	No	`9000`	Port is the port of the ClickHouse native protocol, not of the HTTP interface. Validation: `Maximum: 65535`, `Minimum: 1`.
`database`	string			Database is the database holding the target tables, for example `gitlab_clickhouse_main_production`. Validation: `MaxLength: 63`, `MinLength: 1`.
`username`	string			Username is the ClickHouse user the consumer and the reconciler connect as. It needs INSERT and SELECT on the target tables. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of that user.
`ssl`	boolean	No	`false`	SSL turns TLS on for the native protocol connection. The port changes with it, so set both.

ClickHouseSpec

ClickHouseSpec is the connection GitLab reads and writes ClickHouse through, over its HTTP interface. It is the main database of the chart, the only one GitLab uses.

The database and the user are required rather than defaulted, as for the sink of a Siphon: the Operator uses the reference it is given instead of guessing the layout of the server. A Siphon keeps a connection of its own, over the native protocol and as a user of its own.

For the privileges the user needs, see https://docs.gitlab.com/integration/clickhouse/.

Used by: GitLabCoreSpec.

Field	Type	Description
`url`	string	URL is the URL of the HTTP interface of the ClickHouse server, for example `https://clickhouse.example.com:8443`. It is not the native protocol port a Siphon uses. Validation: `MaxLength: 2048`, `MinLength: 1`, `Pattern: ^https?://`.
`database`	string	Database is the database GitLab runs its ClickHouse migrations in, for example `gitlab_clickhouse_main_production`. Validation: `MaxLength: 63`, `MinLength: 1`.
`username`	string	Username is the ClickHouse user GitLab connects as. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector	PasswordSecretRef selects the key of the Secret that holds the password of that user. The password is a reference to a Secret, so no password is stored in the custom resource.

ComponentSpec

ComponentSpec turns one component of the chart on or off.

Used by: ComponentsSpec.

Field	Type	Required	Default	Description
`enabled`	boolean			Enabled turns the component on or off.

ComponentsSpec

ComponentsSpec turns the components of the chart on or off. Each one left unset keeps its default: the chart default for the components without settings, which is on for every one of them but Pages, and off for the registry, the Toolbox, and OpenBao.

Used by: GitLabCoreSpec.

Field	Type	Required	Description
`webservice`	ComponentSpec	No	Webservice serves the web UI and the API.
`sidekiq`	ComponentSpec	No	Sidekiq runs the background jobs.
`gitaly`	ComponentSpec	No	Gitaly stores the Git repositories. Turning it off needs an external Gitaly, configured in the free-form chart values.
`gitlabShell`	ComponentSpec	No	GitLabShell serves Git over SSH.
`kas`	ComponentSpec	No	KAS is the GitLab agent server for Kubernetes.
`gitlabExporter`	ComponentSpec	No	GitLabExporter exports GitLab metrics to Prometheus.
`mailroom`	ComponentSpec	No	Mailroom processes incoming email. The chart renders it only with incoming email configured in the free-form chart values.
`pages`	ComponentSpec	No	Pages serves GitLab Pages. The chart default is off.
`registry`	RegistryComponentSpec	No	Registry is the container registry. The Operator defaults it off.
`toolbox`	ToolboxComponentSpec	No	Toolbox runs backups, restores, and maintenance tasks. The Operator defaults it off.
`openbao`	OpenBaoComponentSpec	No	OpenBao backs the GitLab Secret Manager. The chart default is off.

CustomCASource

CustomCASource names a Secret or a ConfigMap in the namespace of the resource that holds PEM certificates GitLab trusts.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

set exactly one of secret and configMap

Used by: CertificatesSpec.

Field	Type	Required	Description
`secret`	string	No	Secret is the name of a Secret that holds the certificates. Validation: `MaxLength: 253`, `MinLength: 1`.
`configMap`	string	No	ConfigMap is the name of a ConfigMap that holds the certificates. Validation: `MaxLength: 253`, `MinLength: 1`.
`keys`	string array	No	Keys are the keys to read. Leaving it unset reads every key of the source, so set it for a Secret that also holds a private key, such as a `kubernetes.io/tls` Secret. Validation: `MaxItems: 64`, `items:MaxLength: 253`, `items:MinLength: 1`, `items:Pattern: ^[-._a-zA-Z0-9]+$`.

DatalakeSpec

DatalakeSpec is the connection to the ClickHouse database the Siphon writes to.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

spec.datalake.port is the ClickHouse HTTP interface port, not the native protocol; 9000 is the native protocol and Orbit does not speak it

Used by: OrbitSpec.

Field	Type	Required	Default	Description
`port`	integer	No	`8123`	Port is the port of the ClickHouse HTTP interface, not of the native protocol. Validation: `Maximum: 65535`, `Minimum: 1`.
`user`	string			User is the ClickHouse user Orbit reads the datalake as, for example `gkg_siphon_reader`. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of that user.
`ssl`	boolean	No	`false`	SSL turns TLS on for the HTTP connection. The port changes with it, so set both.

Edition

Edition is the GitLab edition an instance is deployed from.

Underlying type: string.

Validation:

Enum: [ce ee]

Used by: GitLabCoreSpec.

Value	Description
`ce`	EditionCE is the Community Edition, which carries the MIT-licensed code only.
`ee`	EditionEE is the Enterprise Edition, which runs the Free feature set until a license activates more.

Encoding

Encoding is how a generated value is stored.

Underlying type: string.

Validation:

Enum: [none raw base64]
MaxLength: 16

Used by: SecretGenerator.

Value	Description
`none`	EncodingNone stores the characters of a `random` value as they are.
`raw`	EncodingRaw stores the bytes of a `bytes` value as they are.
`base64`	EncodingBase64 stores standard base64 with no wrapping and no trailing newline.

EnvoyGatewayControllerSpec

EnvoyGatewayControllerSpec points at the controller of an Envoy Gateway installation that already runs in the cluster.

Used by: NetworkingSpec.

Field	Type	Required	Default	Description
`controllerName`	string			ControllerName is the controller name of the Envoy Gateway installation, for example `gateway.envoyproxy.io/gatewayclass-controller`. The chart writes it onto the GatewayClass it provisions, which is how Envoy Gateway picks the GatewayClass up. It is a domain prefixed path, the same shape the Gateway API itself validates `GatewayClass.spec.controllerName` as. It is immutable, for the same reason `GatewayClass.spec.controllerName` is: the API server rejects an update to it, so a changed one would fail to apply on every reconcile and leave the instance stuck. Point a new instance at the other controller instead. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)\/[A-Za-z0-9\/\-._~%!$&'()+,;=:]+$`. Rules: - spec.networking.envoyGatewayController.controllerName is immutable
`certManager`	CertManagerSpec	No		CertManager points the chart-provisioned Gateway at an existing cert-manager Issuer or ClusterIssuer.

FieldShape

FieldShape is the kind of value of a railsSecrets field.

Underlying type: string.

Validation:

Enum: [scalar pem list]
MaxLength: 16

Used by: RailsSecretField.

Value	Description
`scalar`	FieldShapeScalar is a string of random characters.
`pem`	FieldShapePEM is a PEM-encoded RSA private key.
`list`	FieldShapeList is a list that holds one string of random characters.

GatewayClassSpec

GatewayClassSpec names a GatewayClass that already exists in the cluster.

Used by: NetworkingSpec.

Field	Type	Required	Description
`name`	string		Name is the name of the existing GatewayClass. Validation: `MaxLength: 253`, `MinLength: 1`.
`configureEnvoy`	boolean	No	ConfigureEnvoy turns on the chart-managed Envoy Gateway API extensions (EnvoyProxy, the traffic and security policies) against the GatewayClass. Leave it off for a GatewayClass controlled by anything other than Envoy Gateway.
`certManager`	CertManagerSpec	No	CertManager points the chart-provisioned Gateway at an existing cert-manager Issuer or ClusterIssuer.

GatewaySpec

GatewaySpec names a Gateway that already exists in the cluster.

Used by: NetworkingSpec.

Field	Type	Required	Description
`name`	string		Name is the name of the existing Gateway. Validation: `MaxLength: 253`, `MinLength: 1`.
`namespace`	string	No	Namespace is the namespace the existing Gateway lives in. It defaults to the namespace of the GitLabCore resource. A namespace name is a DNS label, not the DNS subdomain an object name may be, so it is bounded at 63 characters rather than 253. Validation: `MaxLength: 63`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`.
`configureEnvoy`	boolean	No	ConfigureEnvoy turns on the chart-managed Envoy Gateway API extensions (EnvoyProxy, the traffic and security policies) against the Gateway. Leave it off for a Gateway controlled by anything other than Envoy Gateway.

GeneratedSecret

GeneratedSecret declares one Secret and the generators of its keys. A railsSecrets generator is the only generator of its entry.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

a railsSecrets generator is the only generator of its entry

Used by: GitLabSecretsSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the Secret, in the namespace of the resource. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`type`	string	No	`Opaque`	Type is the type of a Secret the controller creates. An existing Secret keeps its type. Validation: `MaxLength: 253`, `MinLength: 1`.
`generators`	SecretGenerator array			Generators produce the keys of the Secret. Validation: `MaxItems: 16`, `MinItems: 1`.

GeneratedSecretStatus

GeneratedSecretStatus is the observed state of one declared Secret.

Used by: GitLabSecretsStatus.

Field	Type	Required	Description
`name`	string		Name is the name of the Secret. Validation: `MaxLength: 253`, `MinLength: 1`.
`ready`	boolean		Ready is whether the Secret holds every declared key. A Secret of a certificate set is ready when the whole set is.
`readyUnits`	string array	No	ReadyUnits are the data-bearing units the controller has seen ready. A missing unit in this list is reported, not generated again. Validation: `MaxItems: 1024`, `items:MaxLength: 512`.

GeneratorType

GeneratorType selects the recipe of a generator.

Underlying type: string.

Validation:

Enum: [random bytes static rsa x509 sshHostKeys railsSecrets]
MaxLength: 16

Used by: SecretGenerator.

Value	Description
`random`	GeneratorRandom generates random characters.
`bytes`	GeneratorBytes generates random bytes.
`static`	GeneratorStatic stores a fixed value.
`rsa`	GeneratorRSA generates a PEM-encoded RSA private key.
`x509`	GeneratorX509 generates a self-signed certificate and its key.
`sshHostKeys`	GeneratorSSHHostKeys generates the SSH host key pairs.
`railsSecrets`	GeneratorRailsSecrets generates the fields of a Rails `secrets.yml`.

GitLabCoreChartSpec

GitLabCoreChartSpec carries the chart values only. The version is selected by spec.version instead.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`values`	ChartValues	No		Values is the set of Helm values that is used to render the chart.

GitLabCoreSpec

GitLabCoreSpec defines the desired state of a GitLab instance.

The structured fields are a thin typed layer over the values of the GitLab umbrella chart. For this iteration the layer covers the domain, the edition, the license, and the connections to PostgreSQL, Redis, object storage, and ClickHouse. Every other setting stays reachable through the free-form chart values.

Used by: GitLabCore.

Field	Type	Required	Default	Description
`domain`	string	No		Domain is the domain the GitLab instance is served under, for example `example.com`. Every component is served at a subdomain of it: GitLab itself at `gitlab.example.com`, the container registry at `registry.example.com`, and the GitLab agent server at `kas.example.com`. Validation: `MaxLength: 253`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)+$`.
`edition`	Edition	No	`ee`	Edition is the GitLab edition to deploy: `ee` for Enterprise Edition, `ce` for Community Edition. Enterprise Edition runs unlicensed with the Free feature set, so it is the default and the edition to pick unless the instance has to carry no proprietary code at all. Validation: `Enum: [ce ee]`.
`license`	LicenseSpec	No		License references the GitLab license to activate the instance with. The license is a reference to a Secret, so no license key is stored in the custom resource.
`postgresql`	PostgreSQLSpec	No		PostgreSQL is the PostgreSQL server the instance stores its data in. The chart bundles no database, so an instance without this field, or without the equivalent free-form chart values, does not render.
`redis`	RedisSpec	No		Redis is the Redis server the instance uses for caching, queues, and shared state. Valkey serves as a drop-in replacement. The chart bundles no server, so an instance without this field, or without the equivalent free-form chart values, does not render.
`objectStorage`	ObjectStorageSpec	No		ObjectStorage is the S3 compatible object storage the instance keeps its artifacts, uploads, and other blobs in. The chart enables object storage for these with no connection of its own, so an instance without this field, or without the equivalent free-form chart values, does not render.
`clickhouse`	ClickHouseSpec	No		ClickHouse is the ClickHouse server the instance stores analytics data in. Setting it turns the ClickHouse integration of GitLab on, and with it the ClickHouse migrations that create the tables a Siphon streams into. A Siphon waits for an instance that has ClickHouse configured, here or in the free-form chart values.
`components`	ComponentsSpec	No		Components turns the components of the chart on or off, and carries the settings of those that need some, such as the container registry, the Toolbox, and OpenBao. A component left unset keeps its default.
`networking`	NetworkingSpec	No		Networking selects one of the common Gateway API setups the chart supports. Leaving it unset turns the Gateway API off (the Operator does not install the chart’s bundled Envoy Gateway, so its own default of enabling the Gateway API would render resources with nothing implementing them), and networking is configured entirely through the free-form chart values.
`certificates`	CertificatesSpec	No		Certificates adds certificate authorities GitLab trusts beyond its system ones. The certificate authorities of the resources the instance references, such as an Orbit that serves TLS, are added by the Operator on its own and reported in status.managedCAs.
`orbitRef`	OrbitReference	No		OrbitRef names the Orbit in this namespace that the instance connects to. The Operator reads the gRPC endpoint from its status and the JWT Secret from its spec, and configures GitLab with them. It never waits for the Orbit: until the Orbit reports an endpoint, the instance renders without the Orbit settings and says why in the OrbitConnected condition.
`version`	VersionSpec			Version selects the chart version the instance runs: a fixed one, or one the Operator follows as GitLab releases new versions.
`chart`	GitLabCoreChartSpec	No		Chart carries the free-form values the GitLab umbrella chart is rendered with. The version of the chart is selected by Version.
`upgrade`	UpgradeSpec	No		Upgrade tunes how the Operator carries out a zero-downtime upgrade.

GitLabCoreStatus

GitLabCoreStatus defines the observed state of a GitLab instance.

Used by: GitLabCore.

Field	Type	Required	Description
`phase`	string	No
`version`	string	No	Version is the version of the GitLab chart the release was rendered from, which is an unrelated number to the version of the application it deploys. For that, read GitLabVersion.
`gitlabVersion`	string	No	GitLabVersion is the version of the application the release deploys, without the leading `v`, such as `19.3.2`. It is recorded alongside Version, so it describes what is deployed rather than what the spec asks for, and a resource stepping through a multi-minor upgrade reports the version it has converged to so far. It is the only place the application version is published. Nothing else can derive it from the resource: the chart version in the spec does not imply it, and the chart the Operator renders may be one it does not carry on disk.
`targetVersion`	string	No	TargetVersion is the chart version spec.version resolved to, which the instance converges to. It holds while an upgrade toward it runs.
`availableVersion`	string	No	AvailableVersion is the chart version spec.version resolves to now. For a type that follows the repository, it becomes TargetVersion only once a preflight passes: the upgrade path resolves, each step renders, and the first step passes a server-side dry-run apply. Until then, and while a target is held, it is the version waiting to be rolled out.
`rejectedVersion`	string	No	RejectedVersion is the last candidate whose preflight failed for good. It is not checked again until the spec changes or an hour passes; a newer candidate is checked straight away.
`hooksVersion`	string	No	HooksVersion is the chart version whose pre-install hooks last completed. The hooks run again when the chart version rendered differs, as well as when the spec changes, because an unattended upgrade moves the rendered version without changing the generation, and a newer chart may generate a secret the earlier one did not.
`renderedKinds`	string array	No	RenderedKinds are the kinds the last applied render used, each as `<apiVersion>/<Kind>`, for example `apps/v1/Deployment`. It is how the reconciler cleans up after a render that stops using a kind altogether, such as every Gateway API object once `global.gatewayApi.enabled` is turned off: the new render names no such object, so nothing else would say to go looking for one. It is also what the finalizer deletes by, which is why deleting a resource needs no chart.
`managedCAs`	ManagedCA array	No	ManagedCAs are the certificate authorities the Operator applied for the render of the current pass, from the resources the instance references.
`conditions`	Condition array	No	Conditions is optional, so that a status written before any condition is set, by a first pass that failed early, is accepted rather than rejected.

GitLabReference

GitLabReference names the GitLabCore resource that another resource belongs to. The reference is resolved in the namespace of the referring resource, which lets a namespace hold more than one GitLab instance.

Used by: OrbitSpec, SiphonSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the GitLabCore resource in the same namespace. Validation: `MaxLength: 253`, `MinLength: 1`.

GitLabSecretsSpec

GitLabSecretsSpec declares the Secrets of a GitLab release, as the GitLab chart renders it under shared-secrets.provider: controller. The controller generates what is missing and never overwrites a present value.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

a Secret of spec.certificates is not also declared in spec.secrets

Used by: GitLabSecrets.

Field	Type	Required	Default	Description
`secrets`	GeneratedSecret array	No		Secrets declares one Secret per entry. Two entries may name one Secret: the chart renders that when two values point at the same Secret, and the entries merge. Validation: `MaxItems: 128`.
`certificates`	SelfSignedCertificate array	No		Certificates declares the self-signed certificate set: a CA, a wildcard certificate signed by it, and a chain. The chart renders it only when no other source provides TLS. Validation: `MaxItems: 1`.

GitLabSecretsStatus

GitLabSecretsStatus is the observed state of the declared Secrets.

Used by: GitLabSecrets.

Field	Type	Required	Default	Description
`conditions`	Condition array	No		Conditions holds `Ready`, which covers the generation in its `observedGeneration`. Validation: `MaxItems: 8`.
`secrets`	GeneratedSecretStatus array	No		Secrets holds one entry per declared Secret, including the Secrets of the certificate set. Validation: `MaxItems: 256`.

IssuerKind

IssuerKind is the kind of cert-manager resource an IssuerRef selects.

Underlying type: string.

Validation:

Enum: [Issuer ClusterIssuer]

Used by: IssuerRef.

Value	Description
`Issuer`	IssuerKindIssuer selects a namespaced cert-manager Issuer.
`ClusterIssuer`	IssuerKindClusterIssuer selects a cluster-scoped cert-manager ClusterIssuer.

IssuerRef

IssuerRef selects a cert-manager Issuer or ClusterIssuer by name.

Used by: CertManagerSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the Issuer or ClusterIssuer. Validation: `MaxLength: 253`, `MinLength: 1`.
`kind`	IssuerKind	No	`Issuer`	Kind is whether Name refers to a namespaced Issuer or a cluster-scoped ClusterIssuer. Validation: `Enum: [Issuer ClusterIssuer]`.

LicenseSpec

LicenseSpec points at the Secret that holds the GitLab license key.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`secretRef`	SecretKeySelector			SecretRef selects the key of the Secret that holds the license.

LocalSecretReference

LocalSecretReference names a Secret in the namespace of the resource, without selecting a key. Use it where the whole Secret is consumed, for example a kubernetes.io/dockerconfigjson registry credential.

Used by: TablesSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the Secret. Validation: `MaxLength: 253`, `MinLength: 1`.

ManagedCA

ManagedCA is a certificate authority the Operator adds to the trust of GitLab on its own.

Used by: GitLabCoreStatus.

Field	Type	Required	Description
`sourceKind`	string	No	SourceKind is the kind of the resource the CA comes from, such as `Orbit`.
`sourceName`	string	No	SourceName is the name of that resource, in the namespace of the instance.
`configMap`	string	No	ConfigMap is the ConfigMap the Operator copied the CA into.
`key`	string	No	Key is the key of the ConfigMap that holds the CA.
`subject`	string	No	Subject is the subject of the first certificate under Key.
`notAfter`	Time	No	NotAfter is when the first certificate under Key expires.

NetworkingSpec

NetworkingSpec selects one of the common Gateway API setups the chart supports. At most one of its fields may be set; leaving all of them unset turns the Gateway API off, rather than leaving the chart’s own default of enabling it in place, and networking is configured entirely through the free-form chart values.

EnvoyGatewayController is the closest match to the chart’s own default setup and the recommended mode: it needs no provider-specific setup beyond the controller name of an already installed Envoy Gateway. GatewayClass and Gateway step in for a cluster that already has more of the Gateway API resources provisioned, by an administrator or another tool.

Ingress has no mode of its own: an instance that still routes through Ingress configures it entirely through the free-form chart values.

EnvoyGatewayController and GatewayClass need a chart at 10.4.0 or newer, the first version whose GatewayClass template honors the values they set. On an older chart both render a Gateway pointing at a GatewayClass that never renders, and nothing reports it.

Switching from one mode to another, or back to none of them, removes what the previous mode rendered, such as the previous Gateway, its Routes, and the GatewayClass, on the next pass.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

at most one of envoyGatewayController, gatewayClass, and gateway may be set

Used by: GitLabCoreSpec.

Field	Type	Required	Description
`envoyGatewayController`	EnvoyGatewayControllerSpec	No	EnvoyGatewayController points at the controller of an Envoy Gateway installation that already runs in the cluster. The chart provisions the GatewayClass, the Gateway, and the Envoy Gateway API extensions (EnvoyProxy, the traffic and security policies), but never the Envoy Gateway controller itself: like cert-manager, it is a cluster-wide prerequisite the Operator does not install. The GatewayClass it provisions is cluster-scoped, so the Operator names it after the instance rather than leaving it at the chart’s fixed default, which every instance in the cluster would otherwise fight over.
`gatewayClass`	GatewayClassSpec	No	GatewayClass names a GatewayClass that already exists in the cluster. The chart provisions standard Gateway API resources, including the Gateway itself, against it, but never the GatewayClass. The Envoy Gateway API extensions stay off unless ConfigureEnvoy asks for them.
`gateway`	GatewaySpec	No	Gateway names a Gateway that already exists in the cluster. The chart attaches its Routes to it instead of provisioning a Gateway of its own. The Envoy Gateway API extensions stay off unless ConfigureEnvoy asks for them.

ObjectStorageSpec

ObjectStorageSpec is the connection to the object storage of the instance.

The connection is one Secret rather than a set of fields: it holds the endpoint, the region, and the credentials in the format the chart expects, and the Operator neither reads nor rewrites it. For the format, see https://docs.gitlab.com/charts/charts/globals/#connection.

This covers the consolidated object storage of the application. The registry, the Pages daemon, and the backup toolbox read their own settings, which stay in the free-form chart values.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`connectionSecretRef`	SecretKeySelector			ConnectionSecretRef selects the key of the Secret that holds the connection settings.

OpenBaoComponentSpec

OpenBaoComponentSpec backs the GitLab Secret Manager with the bundled OpenBao. Enabling it turns on both the GitLab-side integration and the OpenBao subchart.

The chart bundles OpenBao itself, but not a database for it: OpenBao needs a PostgreSQL database of its own, and does not inherit the password of the instance’s main database. See https://docs.gitlab.com/charts/charts/openbao/#setup-gitlab-secret-manager-and-openbao.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

postgresql and serviceAccount are required while OpenBao is enabled

Used by: ComponentsSpec.

Field	Type	Required	Description
`enabled`	boolean		Enabled turns the Secret Manager and OpenBao on or off. Switched off, the settings stay in the resource and configure nothing.
`postgresql`	OpenBaoPostgreSQLSpec	No	PostgreSQL is the PostgreSQL server OpenBao stores its data in, separate from the database of the GitLab instance itself. Required while OpenBao is enabled.
`serviceAccount`	OpenBaoServiceAccountSpec	No	ServiceAccount names the ServiceAccount OpenBao’s pod runs as. OpenBao needs a Role granting get/update/patch on Pods in the namespace of the instance, and a RoleBinding binding that Role to the ServiceAccount. The Operator creates neither: it does not manage RBAC on the cluster it reconciles, by design. Create the ServiceAccount, the Role, and the RoleBinding ahead of time, and name the ServiceAccount here. Required while OpenBao is enabled.

OpenBaoPostgreSQLSpec

OpenBaoPostgreSQLSpec is the connection to the PostgreSQL server OpenBao uses.

Used by: OpenBaoComponentSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the PostgreSQL server. Validation: `MaxLength: 253`, `MinLength: 1`.
`port`	integer	No	`5432`	Port is the port of the PostgreSQL server. Validation: `Maximum: 65535`, `Minimum: 1`.
`database`	string	No	`openbao`	Database is the database OpenBao stores its data in. Validation: `MaxLength: 63`, `MinLength: 1`.
`username`	string	No	`openbao`	Username is the login role OpenBao connects as. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of the database user. OpenBao does not inherit the password of the instance’s own database, so this is required rather than defaulted.

OpenBaoServiceAccountSpec

OpenBaoServiceAccountSpec names the pre-existing ServiceAccount OpenBao’s pod runs as.

Used by: OpenBaoComponentSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the ServiceAccount, already granted the Role OpenBao needs. Validation: `MaxLength: 253`, `MinLength: 1`.

OrbitReference

OrbitReference names the Orbit resource a GitLabCore connects to. The reference is resolved in the namespace of the referring resource.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the Orbit resource in the same namespace. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.

OrbitSpec

OrbitSpec defines the desired state of an Orbit deployment.

Orbit, the GitLab Knowledge Graph, indexes the datalake that a Siphon fills into a graph database and serves it to GitLab over gRPC. The resource is a reference to what it builds on, not a provisioner of it: the Operator renders the Orbit chart against the GitLabCore, the Siphon and the graph database named here and applies it. Creating the ClickHouse users, the graph database and the JWT key are administrator prerequisites.

No topology is modeled. Replicas, indexer pools and resources stay in spec.chart.values.

Used by: Orbit.

Field	Type	Required	Description
`gitlabRef`	GitLabReference		GitLabRef names the GitLabCore instance that this deployment belongs to. It resolves the internal URL of GitLab and the GitLab version, and it gates the rollout: the release is not applied until that instance reports available.
`siphonRef`	SiphonReference		SiphonRef names the Siphon that fills the datalake Orbit indexes. The NATS connection, the datalake host and database, and the stream name are read from it, and the release is not applied until it reports available. It must name the same GitLabCore as GitLabRef.
`datalake`	DatalakeSpec		Datalake is how Orbit reads the tables the Siphon writes. The host and the database are the ones of the Siphon sink. Orbit reaches them over the HTTP interface as a user of its own, so the port, the user, the password and TLS are set here.
`graph`	ClickHouseGraphSpec		Graph is the ClickHouse database Orbit writes the graph to and serves it from.
`jwtSecretRef`	SecretKeySelector		JWTSecretRef selects the key of the Secret that holds the HS256 key GitLab and Orbit share: 32 random bytes, base64 encoded. Orbit verifies the tokens GitLab signs with it, and signs the calls it makes to GitLab with it, so the same key is configured on both sides.
`tls`	OrbitTLSSpec	No	TLS serves the gRPC port of the webserver over TLS. GitLab accepts only a `tls://` endpoint, so leave it unset only when TLS is terminated in front of Orbit.
`version`	StaticVersionSpec		Version selects the Orbit chart version the deployment runs, with the Static type only.
`chart`	ChartValuesSpec	No	Chart carries the free-form values the Orbit chart is rendered with. The version of the chart is selected by Version.

OrbitStatus

OrbitStatus defines the observed state of an Orbit deployment.

Used by: Orbit.

Field	Type	Required	Description
`phase`	string	No
`version`	string	No
`conditions`	Condition array	No	Conditions is optional, so that a status written before any condition is set, by a first pass that failed early, is accepted rather than rejected.
`gitlabVersion`	string	No	GitLabVersion is the application version of the referenced instance.
`grpcEndpoint`	string	No	GRPCEndpoint is the `tls://` endpoint GitLab connects to. A GitLabCore that names this Orbit in `spec.orbitRef` reads it from here. It is set only with `spec.tls`: without it the Service serves plaintext, and the address GitLab needs belongs to whatever terminates TLS in front of it.
`caSecretRef`	SecretKeySelector	No	CASecretRef is the Secret and key that hold the CA of the certificate the webserver serves: the TLS Secret it mounts, which is `spec.tls.secretName` unless `spec.chart.values` set `tls.existingSecret`, and `ca.crt`. It is set exactly while GRPCEndpoint is. The Orbit reconciler does not read the Secret, so the key may be missing, for example for a publicly trusted certificate; a GitLabCore that names this Orbit then adds no CA.
`renderedKinds`	string array	No	RenderedKinds are the kinds the last applied render used, each as `<apiVersion>/<Kind>`. It is how the reconciler cleans up after a render that stops using a kind altogether.

OrbitTLSSpec

OrbitTLSSpec names the Secret the webserver serves gRPC over TLS with.

Used by: OrbitSpec.

Field	Type	Required	Default	Description
`secretName`	string			SecretName is the name of a `kubernetes.io/tls` Secret in the namespace of the resource, holding `tls.crt` and `tls.key`. The certificate must cover the name GitLab connects to. When the Secret also holds the issuing CA under `ca.crt`, as cert-manager writes it, a GitLabCore that names this Orbit in `spec.orbitRef` trusts that CA. Validation: `MaxLength: 253`, `MinLength: 1`.

PostgreSQLSSLMode

PostgreSQLSSLMode is the libpq TLS mode of a PostgreSQL connection.

Underlying type: string.

Validation:

Enum: [disable allow prefer require verify-ca verify-full]

Used by: PostgreSQLSourceSpec.

PostgreSQLSourceSpec

PostgreSQLSourceSpec is the connection to the PostgreSQL server Siphon replicates from.

The server must already carry the publication named by status.publication, owned by the GitLab application role, the siphon_alter_publication SECURITY DEFINER function, and the SELECT grants the initial snapshot needs. The Operator creates none of them.

Used by: SiphonSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the PostgreSQL server, for example `gitlab-postgresql-rw.databases.svc.cluster.local`. It must be the primary: a logical replication slot is not created on a standby. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`port`	integer	No	`5432`	Port is the port of the PostgreSQL server. Validation: `Maximum: 65535`, `Minimum: 1`.
`database`	string	No	`gitlabhq_production`	Database is the database to replicate. Changing it re-snapshots every table, so it is immutable; delete and recreate the resource to point the pipeline elsewhere. Validation: `MaxLength: 63`, `MinLength: 1`. Rules: - spec.source.database is immutable
`user`	string	No	`siphon`	User is the login role the producer connects as. It needs REPLICATION, EXECUTE on `siphon_alter_publication`, and SELECT on the replicated tables. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of that role. The chart creates no Secret and the Operator reads none: the value reaches the pod as an environment variable and is substituted into the configuration at startup.
`sslMode`	PostgreSQLSSLMode	No	`require`	SSLMode is the libpq TLS mode of the connection. Validation: `Enum: [disable allow prefer require verify-ca verify-full]`.
`advisoryLockID`	integer	No	`1`	AdvisoryLockID is the PostgreSQL advisory lock the producer takes to elect itself. Every producer against this database must agree on it, and two Siphon deployments that share it serialize rather than run in parallel. Change it only to run a second, independent stream off the same database. Validation: `Maximum: 2.147483647e+09`, `Minimum: 1`.

PostgreSQLSpec

PostgreSQLSpec is the connection to the PostgreSQL server of the instance.

For the versions and the extensions GitLab requires, see https://docs.gitlab.com/install/requirements/#postgresql.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the PostgreSQL server, for example `gitlab-postgresql.databases.svc.cluster.local`. Validation: `MaxLength: 253`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of the database user. The password is a reference to a Secret, so no password is stored in the custom resource.

QueueAuthSpec

QueueAuthSpec holds the NATS credentials.

Used by: QueueSpec.

Field	Type	Required	Default	Description
`usernameSecretRef`	SecretKeySelector			UsernameSecretRef selects the key of the Secret that holds the user name.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password.

QueueSpec

QueueSpec is the connection to the NATS server the change data capture events pass through. JetStream must be enabled: Siphon uses streams, a key-value bucket for consumer election, and an object store for oversized events.

Used by: SiphonSpec.

Field	Type	Required	Description
`url`	string		URL is the NATS server URL, for example `nats://nats.nats.svc.cluster.local:4222`. Validation: `MaxLength: 2048`, `MinLength: 1`, `Pattern: ^nats://`.
`auth`	QueueAuthSpec	No	Auth is the user name and password the client authenticates with. Leave it unset for a server that accepts anonymous clients.
`tls`	QueueTLSSpec	No	TLS is the client certificate the connection presents.

QueueTLSSpec

QueueTLSSpec names the Secret that holds the NATS client certificate, and the keys within it.

The whole Secret is mounted read-only at /etc/ssl/certs/custom, so each key becomes a file of the same name and the key names are what the configuration points at.

Used by: QueueSpec.

Field	Type	Required	Default	Description
`secretName`	string			SecretName is the name of the Secret in the namespace of the resource. Validation: `MaxLength: 253`, `MinLength: 1`.
`caCertKey`	string	No	`ca.crt`	CACertKey is the key holding the certificate authority bundle. Validation: `MaxLength: 253`, `MinLength: 1`.
`clientCertKey`	string	No	`tls.crt`	ClientCertKey is the key holding the client certificate. Validation: `MaxLength: 253`, `MinLength: 1`.
`clientKeyKey`	string	No	`tls.key`	ClientKeyKey is the key holding the client private key. Validation: `MaxLength: 253`, `MinLength: 1`.

RailsSecretField

RailsSecretField is one field of a railsSecrets document. A scalar or list takes charset and length, and a pem takes bits. A list holds one value.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

a scalar or list field requires charset and length, and takes no bits
a pem field requires bits, and takes no charset or length

Used by: SecretGenerator.

Field	Type	Required	Description
`path`	string		Path is the name of the field under the environment. It holds no `.`. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[^.]+$`.
`shape`	FieldShape		Shape selects the kind of value. Validation: `Enum: [scalar pem list]`, `MaxLength: 16`.
`charset`	Charset	No	Charset is the character set of a `scalar` or `list` value. Validation: `Enum: [alphanumeric hex lowerAlphanumeric]`, `MaxLength: 32`.
`length`	integer	No	Length is the number of characters of a `scalar` or `list` value. Validation: `Maximum: 4096`, `Minimum: 1`.
`bits`	integer	No	Bits is the RSA key size of a `pem` value. Validation: `Maximum: 8192`, `Minimum: 2048`, `MultipleOf: 2`.

RedisSpec

RedisSpec is the connection to the Redis server of the instance. Valkey serves as a drop-in replacement.

For the versions GitLab requires, see https://docs.gitlab.com/install/requirements/#redis.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the Redis server, for example `gitlab-valkey.databases.svc.cluster.local`. Validation: `MaxLength: 253`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of the server. The password is a reference to a Secret, so no password is stored in the custom resource.

RegistryComponentSpec

RegistryComponentSpec turns the container registry on or off, with the storage and the metadata database it needs.

The registry keeps its images in a storage of its own, which the consolidated object storage of spec.objectStorage does not reach, and its metadata in a PostgreSQL database of its own. See https://docs.gitlab.com/charts/charts/registry/.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

storage and database are required while the registry is enabled

Used by: ComponentsSpec.

Field	Type	Required	Description
`enabled`	boolean		Enabled turns the registry on or off. Switched off, the settings stay in the resource and configure nothing.
`storage`	RegistryStorageSpec	No	Storage is the storage the registry keeps its images in. Required while the registry is enabled.
`database`	RegistryDatabaseSpec	No	Database is the PostgreSQL server the registry keeps its metadata in. Required while the registry is enabled.

RegistryDatabaseSpec

RegistryDatabaseSpec is the connection to the metadata database of the registry. The Operator creates neither the database nor its role.

Used by: RegistryComponentSpec.

Field	Type	Required	Default	Description
`host`	string			Host is the hostname of the PostgreSQL server. Validation: `MaxLength: 253`, `MinLength: 1`.
`port`	integer	No	`5432`	Port is the port of the PostgreSQL server. Validation: `Maximum: 65535`, `Minimum: 1`.
`database`	string	No	`registry`	Database is the database the registry keeps its metadata in. Validation: `MaxLength: 63`, `MinLength: 1`.
`username`	string	No	`registry`	Username is the login role the registry connects as. Validation: `MaxLength: 63`, `MinLength: 1`.
`passwordSecretRef`	SecretKeySelector			PasswordSecretRef selects the key of the Secret that holds the password of the database user.

RegistryStorageSpec

RegistryStorageSpec points at the Secret that holds the storage configuration of the registry.

Used by: RegistryComponentSpec.

Field	Type	Required	Default	Description
`secretRef`	SecretKeySelector			SecretRef selects the key of the Secret that holds the storage configuration, in the format the chart expects. See https://docs.gitlab.com/charts/charts/registry/#storage.

SecretGenerator

SecretGenerator produces one or more keys of a Secret. The type selects the recipe and the fields it takes:

random: key, charset, length, and optionally encoding (none or base64) and wrap.
bytes: key, length, and encoding (raw or base64).
static: key and value, which may be empty.
rsa: key and bits.
x509: commonName, bits, days, certKey, and keyKey.
sshHostKeys: no fields. The key names come from the generator.
railsSecrets: key, env, and fields.

Every type takes persistent.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

random requires key, charset, and length, and takes only encoding, wrap, and persistent besides
the encoding of random is none or base64
bytes requires key, length, and encoding, and takes only persistent besides
the encoding of bytes is raw or base64
static requires key and value, and takes only persistent besides
rsa requires key and bits, and takes only persistent besides
x509 requires commonName, bits, days, certKey, and keyKey, and takes only persistent besides
the certKey and keyKey of x509 differ
sshHostKeys takes only persistent
railsSecrets requires key, env, and fields, and takes only persistent besides

Used by: GeneratedSecret.

Field	Type	Required	Description
`type`	GeneratorType		Type selects the recipe. Validation: `Enum: [random bytes static rsa x509 sshHostKeys railsSecrets]`, `MaxLength: 16`.
`key`	string	No	Key is the key the value is stored under. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[-._a-zA-Z0-9]+$`.
`charset`	Charset	No	Charset is the character set of a `random` value. Validation: `Enum: [alphanumeric hex lowerAlphanumeric]`, `MaxLength: 32`.
`length`	integer	No	Length is the number of characters of a `random` value, before encoding, or the number of bytes of a `bytes` value. Validation: `Maximum: 4096`, `Minimum: 1`.
`encoding`	Encoding	No	Encoding is how the value is stored. `base64` is standard base64 with no wrapping and no trailing newline. Absent on `random` means `none`. Validation: `Enum: [none raw base64]`, `MaxLength: 16`.
`wrap`	Wrap	No	Wrap is applied to a `random` value after encoding. `jsonArray` stores `["<value>"]`. Absent means `none`. Validation: `Enum: [none jsonArray]`, `MaxLength: 16`.
`value`	string	No	Value is the value of a `static` key. It may be empty. Validation: `MaxLength: 4096`.
`bits`	integer	No	Bits is the RSA key size of an `rsa` or `x509` key. Validation: `Maximum: 8192`, `Minimum: 2048`, `MultipleOf: 2`.
`commonName`	string	No	CommonName is the subject common name of an `x509` certificate, at most the 64 characters X.509 allows. Validation: `MaxLength: 64`, `MinLength: 1`.
`days`	integer	No	Days is the validity of an `x509` certificate. 106751 days is the longest a Go `time.Duration` holds. Validation: `Maximum: 106751`, `Minimum: 1`.
`certKey`	string	No	CertKey is the key an `x509` certificate is stored under. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[-._a-zA-Z0-9]+$`.
`keyKey`	string	No	KeyKey is the key an `x509` private key is stored under. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[-._a-zA-Z0-9]+$`.
`env`	string	No	Env is the Rails environment of a `railsSecrets` document, its top-level key. It holds no `.`, because a unit ID is `<env>.<path>`. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[^.]+$`.
`fields`	RailsSecretField array	No	Fields are the fields of a `railsSecrets` document, one per `path`. Validation: `MaxItems: 64`, `MinItems: 1`.
`persistent`	boolean	No	Persistent marks a value tied to persisted state. Once the controller reported it ready, it reports a missing value instead of generating it again.

SecretKeySelector

SecretKeySelector selects a single key of a Secret in the namespace of the resource.

Used by: BackupStorageSpec, ClickHouseGraphSpec, ClickHouseSinkSpec, ClickHouseSpec, DatalakeSpec, LicenseSpec, ObjectStorageSpec, OpenBaoPostgreSQLSpec, OrbitSpec, OrbitStatus, PostgreSQLSourceSpec, PostgreSQLSpec, QueueAuthSpec, RedisSpec, RegistryDatabaseSpec, RegistryStorageSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the Secret. Validation: `MaxLength: 253`, `MinLength: 1`.
`key`	string			Key is the key of the Secret to read. Validation: `MaxLength: 253`, `MinLength: 1`.

SelfSignedCertificate

SelfSignedCertificate declares a certificate set: a CA from authority, a wildcard certificate for domain signed by it, and three Secrets. The tlsSecret is a kubernetes.io/tls Secret with the wildcard certificate and its key. The caSecret holds the CA certificate under caKey. The chainSecret holds the CA and wildcard certificates, concatenated, under chainKey. The three Secrets are distinct, and the wildcard certificate expires no later than the CA.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

tlsSecret, caSecret, and chainSecret are distinct
certDays is at most caDays

Used by: GitLabSecretsSpec.

Field	Type	Description
`authority`	CertificateAuthority	Authority is the subject and key of the CA.
`domain`	string	Domain is the domain of the wildcard certificate, which covers it and `*.<domain>`. Validation: `MaxLength: 253`, `MinLength: 1`.
`caDays`	integer	CADays is the validity of the CA, in days. 106751 days is the longest a Go `time.Duration` holds. Validation: `Maximum: 106751`, `Minimum: 1`.
`certDays`	integer	CertDays is the validity of the wildcard certificate, in days. Validation: `Maximum: 106751`, `Minimum: 1`.
`tlsSecret`	string	TLSSecret is the name of the Secret of the wildcard certificate. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`caSecret`	string	CASecret is the name of the Secret of the CA certificate. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`caKey`	string	CAKey is the key the CA certificate is stored under. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[-._a-zA-Z0-9]+$`.
`chainSecret`	string	ChainSecret is the name of the Secret of the chain. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`.
`chainKey`	string	ChainKey is the key the chain is stored under. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[-._a-zA-Z0-9]+$`.

SiphonReference

SiphonReference names the Siphon resource that another resource builds on. The reference is resolved in the namespace of the referring resource.

Used by: OrbitSpec.

Field	Type	Required	Default	Description
`name`	string			Name is the name of the Siphon resource in the same namespace. Validation: `MaxLength: 253`, `MinLength: 1`.

SiphonSpec

SiphonSpec defines the desired state of a Siphon deployment.

Siphon streams change data capture from a PostgreSQL source, through NATS JetStream, into a ClickHouse sink. The resource is a reference to those three, not a provisioner of them: the Operator renders the Siphon chart against the endpoints named here and applies it. Creating the PostgreSQL publication, the siphon_alter_publication function, the login roles and the grants, provisioning NATS, and creating the ClickHouse target tables are all administrator prerequisites.

The deployment topology is fixed: one producer, one ClickHouse consumer, one reconciler, one NATS stream. It is the layout GitLab is known to run. Nothing in the specification changes it; spec.chart.values is the escape hatch.

Used by: Siphon.

Field	Type	Required	Default	Description
`gitlabRef`	GitLabReference			GitLabRef names the GitLabCore instance whose database this deployment streams. It resolves the GitLab application version, which pins the table definitions to the deployed schema, and it gates the rollout: the release is not applied until that instance reports available.
`source`	PostgreSQLSourceSpec			Source is the PostgreSQL server the change data capture stream reads.
`queue`	QueueSpec			Queue is the NATS JetStream server the stream passes through.
`sink`	ClickHouseSinkSpec			Sink is the ClickHouse server the stream is written to.
`tables`	TablesSpec	No	`{ }`	Tables selects how the table definitions of the deployed GitLab version reach the pods. It defaults to an empty object so that the defaults of its own fields apply, which a nested default does not do while the object itself is absent.
`version`	StaticVersionSpec			Version selects the Siphon chart version the pipeline runs, as spec.version of a GitLabCore does, with the Static type only.
`chart`	ChartValuesSpec	No		Chart carries the free-form values the Siphon chart is rendered with. The version of the chart is selected by Version.

SiphonStatus

SiphonStatus defines the observed state of a Siphon deployment.

Used by: Siphon.

Field	Type	Required	Description
`phase`	string	No
`version`	string	No
`conditions`	Condition array	No	Conditions is optional, so that a status written before any condition is set, by a first pass that failed early, is accepted rather than rejected.
`gitlabVersion`	string	No	GitLabVersion is the application version of the referenced instance, the version the table definitions are pinned to.
`tablesSource`	string	No	TablesSource is what `spec.tables.source` resolved to, `ImageVolume` or `ConfigMap`.
`tablesImage`	string	No	TablesImage is the fully resolved table definitions image reference.
`tablesDigest`	string	No	TablesDigest is the digest that image resolved to. It is the change detector for a tag that moves, and it is empty while the definitions are mounted rather than extracted.
`tablesCheckedAt`	Time	No	TablesCheckedAt is when the digest was last resolved against the registry. It paces that lookup, which would otherwise run on every reconcile.
`tablesConfigMap`	string	No	TablesConfigMap is the ConfigMap the Operator publishes the extracted definitions to.
`tableCount`	integer	No	TableCount is how many table definitions that ConfigMap holds.
`publication`	string	No	Publication and ReplicationSlot are the PostgreSQL objects the producer uses. They are derived from the fixed topology rather than observed, and they are recorded because deleting this resource leaves both behind: a retained slot pins write-ahead log and will eventually fill the volume of the source server.
`replicationSlot`	string	No
`streamName`	string	No	StreamName is the NATS JetStream stream the events pass through. It is left behind on deletion too.
`renderedKinds`	string array	No	RenderedKinds are the kinds the last applied render used, each as `<apiVersion>/<Kind>`, for example `apps/v1/Deployment`. It is how the reconciler cleans up after a render that stops using a kind altogether, such as the PodMonitors of a cluster that no longer serves the Prometheus operator API: the new render names no such object, so nothing else would say to go looking for one.

StaticVersionSpec

StaticVersionSpec selects the chart version a resource runs, for a chart the Operator bundles. It follows the VersionSpec of a GitLabCore, but supports the Static type only: a bundled chart is never pulled, so there is no repository to follow. Version names the chart version, or VersionRef reads it from an object. Either way, only a version the Operator bundles renders, and a change of it renders that chart.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

version or versionRef is required for the Static type
version and versionRef are mutually exclusive

Used by: OrbitSpec, SiphonSpec.

Field	Type	Required	Description
`type`	StaticVersionType		Type selects how the version is chosen. Only `Static` is supported: it runs Version, or the version VersionRef reads. Validation: `Enum: [Static]`.
`version`	string	No	Version is the semantic version of the chart the Static type runs. Validation: `Pattern: ^(0\|[1-9]\d)\.(0\|[1-9]\d)\.(0\|[1-9]\d)(?:-((?:0\|[1-9]\d\|\d[a-zA-Z-][0-9a-zA-Z-])(?:\.(?:0\|[1-9]\d\|\d[a-zA-Z-][0-9a-zA-Z-]))))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`.
`versionRef`	VersionReference	No	VersionRef reads the semantic version the Static type runs from a key of an object in the namespace of the resource, in place of Version. A change to the object renders the chart again. The object must carry the label `operator.gitlab.com/config-source: "true"`; the Operator does not see one without it.

StaticVersionType

StaticVersionType selects how the chart version of a bundled chart is chosen.

Underlying type: string.

Validation:

Enum: [Static]

Used by: StaticVersionSpec.

Value	Description
`Static`

TablesSource

TablesSource selects where the table definitions come from.

Underlying type: string.

Validation:

Enum: [Auto ImageVolume ConfigMap]

Used by: TablesSpec.

Value	Description
`Auto`	TablesSourceAuto resolves to TablesSourceConfigMap, which works everywhere.
`ImageVolume`	TablesSourceImageVolume mounts the image into the pod.
`ConfigMap`	TablesSourceConfigMap has the Operator extract the image into a ConfigMap.

TablesSpec

TablesSpec selects how the table definitions of the deployed GitLab version reach the pods.

Each pod generates its half of the configuration at startup from those definitions, which ship as an OCI image tagged with the GitLab application version. The image is either mounted directly, which needs a recent Kubernetes, or extracted by the Operator into a ConfigMap it owns.

Used by: SiphonSpec.

Field	Type	Required	Default	Description
`source`	TablesSource	No	`Auto`	Source selects where the definitions come from. `ImageVolume` mounts the image into the pod, which needs both a cluster and a container runtime that serve native OCI image volumes. `ConfigMap` has the Operator pull the image, extract the definitions, and publish them to a ConfigMap it owns. `Auto`, the default, resolves to `ConfigMap`, which works everywhere: nothing in the Kubernetes API reports whether the runtime serves image volumes, and a pod that names one it cannot mount is admitted and then fails to create its container. Validation: `Enum: [Auto ImageVolume ConfigMap]`.
`image`	string	No		Image overrides the table definitions image. Left unset, it is the CNG image `registry.gitlab.com/gitlab-org/build/cng/gitlab-siphon-tables` tagged `v<version>` with the application version of the GitLab chart the referenced instance deploys. Set it to pin a version the reference does not resolve to, or to pull from a mirror. Validation: `MaxLength: 512`.
`pullSecretRef`	LocalSecretReference	No		PullSecretRef names a `kubernetes.io/dockerconfigjson` Secret the image is pulled with. It authenticates the pull the Operator performs on the `ConfigMap` path, and it becomes the pod image pull secret on the `ImageVolume` path. Leave it unset for the public image.

ToolboxBackupsSpec

ToolboxBackupsSpec configures the backups the Toolbox takes.

Used by: ToolboxComponentSpec.

Field	Type	Required	Default	Description
`storage`	BackupStorageSpec			Storage is the object storage the backups go to, and are restored from.
`schedule`	string	No		Schedule is the cron schedule a backup runs on, for example `0 1 * * *`. Leaving it unset takes no scheduled backups. Validation: `MaxLength: 253`, `MinLength: 1`.

ToolboxComponentSpec

ToolboxComponentSpec turns the Toolbox on or off, with the storage its backups go to. See https://docs.gitlab.com/charts/charts/gitlab/toolbox/.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

backups is required while the Toolbox is enabled

Used by: ComponentsSpec.

Field	Type	Required	Default	Description
`enabled`	boolean			Enabled turns the Toolbox on or off. Switched off, the settings stay in the resource and configure nothing.
`backups`	ToolboxBackupsSpec	No		Backups configures where the backups of the instance go, and when they run. Required while the Toolbox is enabled.

UpgradeSpec

UpgradeSpec tunes the zero-downtime upgrade choreography.

Used by: GitLabCoreSpec.

Field	Type	Required	Default	Description
`skipBatchedMigrationCheck`	boolean	No		SkipBatchedMigrationCheck lets an upgrade advance to the next version without waiting for the batched background migrations of the current one to finish. GitLab requires those complete before the next upgrade, so skipping the wait risks data inconsistency and failed migrations; leave it off except on instances (for example development or test ones) where that risk is acceptable in exchange for a faster upgrade.

VersionReference

VersionReference names a key of an object, in the namespace of the resource, whose value is a chart version. It lets a platform that owns the object set the version, while the resource keeps its own owner. The object must carry the label operator.gitlab.com/config-source: "true"; the Operator does not see one without it.

Used by: StaticVersionSpec, VersionSpec.

Field	Type	Description
`kind`	VersionReferenceKind	Kind is the kind of the object. Only `ConfigMap` is supported. Validation: `Enum: [ConfigMap]`.
`name`	string	Name is the name of the object in the namespace of the resource. Validation: `MaxLength: 253`, `MinLength: 1`.
`key`	string	Key is the key of the object whose value is the semantic version of the chart. Validation: `MaxLength: 253`, `MinLength: 1`, `Pattern: ^[-._a-zA-Z0-9]+$`.

VersionReferenceKind

VersionReferenceKind is the kind of object a VersionReference names.

Underlying type: string.

Validation:

Enum: [ConfigMap]

Used by: VersionReference.

Value	Description
`ConfigMap`

VersionSpec

VersionSpec selects the chart version an instance runs. It is a union discriminated by Type: Version belongs to the Static type, Minor to the Patch type, and Major to the Latest, Previous, and OldestSupported types. Every type but Static follows the released versions of the chart repository and upgrades the instance unattended, without downtime. A version below the deployed one is refused and reported on the Upgradeable condition. A Static version is either written in Version or read from the object VersionRef names.

Rules, by the message the Kubernetes API server returns when a resource breaks one:

version or versionRef is required for the Static type and not allowed for any other
version and versionRef are mutually exclusive
minor is required for the Patch type and not allowed for any other
major is required for the Latest, Previous, and OldestSupported types and not allowed for any other

Used by: GitLabCoreSpec.

Field	Type	Required	Description
`type`	VersionType		Type selects how the version is chosen. - `Static` runs Version, or the version VersionRef reads, and upgrades only when it changes. - `Patch` follows the latest patch of Minor. - `Latest` follows the latest minor (N) of Major, with its latest patch. - `Previous` follows the minor before the newest release (N-1), within Major. - `OldestSupported` follows the oldest minor GitLab still supports (N-2), within Major. Previous and OldestSupported count minors across majors, as the GitLab maintenance policy does, and a Major with too few minors resolves to its first one. With Major 10 ending at 10.11, OldestSupported runs 10.9 while 10.11 is the newest release, 10.10 once 11.0 is, and 10.11 from 11.1 on. Validation: `Enum: [Static Patch Latest Previous OldestSupported]`.
`version`	string	No	Version is the semantic version of the chart the Static type runs. Validation: `Pattern: ^(0\|[1-9]\d)\.(0\|[1-9]\d)\.(0\|[1-9]\d)(?:-((?:0\|[1-9]\d\|\d[a-zA-Z-][0-9a-zA-Z-])(?:\.(?:0\|[1-9]\d\|\d[a-zA-Z-][0-9a-zA-Z-]))))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`.
`versionRef`	VersionReference	No	VersionRef reads the semantic version the Static type runs from a key of an object in the namespace of the resource, in place of Version. It behaves as Version does: a change of the value upgrades the instance, and a value below the deployed version is refused. A change to the object reconciles the resource again. The object must carry the label `operator.gitlab.com/config-source: "true"`; the Operator does not see one without it.
`minor`	string	No	Minor is the `major.minor` chart version whose latest patch the Patch type follows, for example `10.3`. Raising it upgrades the instance to that minor. Validation: `Pattern: ^(0\|[1-9]\d)\.(0\|[1-9]\d)$`.
`major`	integer	No	Major is the chart major the Latest, Previous, and OldestSupported types resolve within, for example `10`. A major upgrade is never unattended: raising Major starts it. Validation: `Minimum: 1`.

VersionType

VersionType selects how the chart version of an instance is chosen.

Underlying type: string.

Validation:

Enum: [Static Patch Latest Previous OldestSupported]

Used by: VersionSpec.

Value	Description
`Static`	VersionStatic runs a fixed chart version.
`Patch`	VersionPatch follows the latest patch of a fixed minor.
`Latest`	VersionLatest follows the latest minor (N) of a major.
`Previous`	VersionPrevious follows the minor before the newest release (N-1), within a major.
`OldestSupported`	VersionOldestSupported follows the oldest minor GitLab still supports (N-2), within a major.

Wrap

Wrap is applied to a random value after encoding.

Underlying type: string.

Validation:

Enum: [none jsonArray]
MaxLength: 16

Used by: SecretGenerator.

Value	Description
`none`	WrapNone stores the value as it is.
`jsonArray`	WrapJSONArray stores `["<value>"]`.

Was this page helpful?