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 Default Description
apiVersion string check-sm apps.gitlab.com/v2alpha1
kind string check-sm 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 Default Description
apiVersion string check-sm apps.gitlab.com/v2alpha1
kind string check-sm 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 Default Description
apiVersion string check-sm apps.gitlab.com/v2alpha1
kind string check-sm 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 Default Description
apiVersion string check-sm apps.gitlab.com/v2alpha1
kind string check-sm 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 check-sm 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 check-sm 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 Required Default Description
commonName string check-sm CommonName is the subject common name of the CA.

Validation: MaxLength: 253, MinLength: 1.
organization string check-sm Organization is the subject organization of the CA.

Validation: MaxLength: 253, MinLength: 1.
organizationalUnit string check-sm OrganizationalUnit is the subject organizational unit of the CA.

Validation: MaxLength: 253, MinLength: 1.
algorithm CertificateAlgorithm check-sm Algorithm is the key algorithm of the CA and the wildcard certificate.

Validation: Enum: [rsa ecdsa], MaxLength: 16.
keySize integer check-sm 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 check-sm 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 check-sm Database is the database that holds the graph, for example orbit.

Validation: MaxLength: 63, MinLength: 1.
user string check-sm 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 check-sm 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 check-sm 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 check-sm Database is the database holding the target tables, for example gitlab_clickhouse_main_production.

Validation: MaxLength: 63, MinLength: 1.
username string check-sm 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 check-sm 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 Required Default Description
url string check-sm 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 check-sm Database is the database GitLab runs its ClickHouse migrations in, for example gitlab_clickhouse_main_production.

Validation: MaxLength: 63, MinLength: 1.
username string check-sm Username is the ClickHouse user GitLab connects as.

Validation: MaxLength: 63, MinLength: 1.
passwordSecretRef SecretKeySelector check-sm 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 check-sm 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 Default 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, together with the GitLab integration with a registry (global.registry.enabled).
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 Default 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 check-sm User is the ClickHouse user Orbit reads the datalake as, for example gkg_siphon_reader.

Validation: MaxLength: 63, MinLength: 1.
passwordSecretRef SecretKeySelector check-sm 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 check-sm 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 Default Description
name string check-sm 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 Default Description
name string check-sm 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 check-sm 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 check-sm 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 Default Description
name string check-sm Name is the name of the Secret.

Validation: MaxLength: 253, MinLength: 1.
ready boolean check-sm 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
valuesFrom ValuesReference array No ValuesFrom lists ConfigMaps and Secrets in the namespace of the resource that hold Helm values. They are merged in list order, each over the one before it, above the values derived from the structured fields and below values. A change to a referenced object renders the chart again. Each object must carry the label operator.gitlab.com/config-source: "true"; the Operator does not see one without it.

Anyone who can write a referenced object controls the values it contributes, so grant write access to it as carefully as write access to the resource.

Validation: MaxItems: 32.
values ChartValues No Values is the set of Helm values that is used to render the chart. They win over the values ValuesFrom references.

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 No { type:Latest } Version selects the version the instance runs: a fixed one, or one the Operator follows as GitLab releases new versions. It defaults to the Latest type without a Major, which installs the newest major and stays within the major the instance runs.
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 Default 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.
upgradeVersions string array No UpgradeVersions are the chart versions the instance can upgrade to, newest first: the newest patch of each minor above Version, among the versions the types that follow the repository resolve against. A repository out of reach for now keeps the versions listed before, one that fails for good lists none, and the UpgradeVersionsListed condition says so either way. It is empty until the instance is installed. A client offers these rather than read a chart repository itself, which may not be the one the Operator pulls from.
upgradeGitLabVersions string array No UpgradeGitLabVersions are the GitLab versions an instance on a Static GitLab version (a version or a versionRef of spec.version) can upgrade to, newest first: the newest release of each GitLab minor above GitLabVersion whose record in the release manifest lists a GitLab chart. A manifest out of reach for now keeps the versions listed before, one that fails for good lists none, and the UpgradeGitLabVersionsListed condition says so either way. It is empty for any other spec.version, and until the instance is installed.
clickHouseEnabled boolean No ClickHouseEnabled reports whether the chart values turn the ClickHouse integration of GitLab on: global.clickhouse.enabled as spec.chart.valuesFrom and spec.chart.values set it, or spec.clickhouse when they set no boolean. It is unset until a pass resolves the references, and a Siphon that references the instance reads it, because only the reconciler of the instance reads the referenced objects.
rejectedVersion string No RejectedVersion is the last candidate whose preflight failed for good. It is not checked again until the spec, the objects spec.chart.valuesFrom references, or the charts the Operator carries change, or an hour passes; a newer candidate is checked straight away.
rejectedValuesDigest string No RejectedValuesDigest identifies the objects spec.chart.valuesFrom referenced when RejectedVersion failed its preflight, by their UID and resourceVersion, never their content. RejectedVersion is checked again once it differs from what the references resolve to.
rejectedCatalogDigest string No RejectedCatalogDigest identifies the GitLab chart versions the Operator carried when RejectedVersion failed its preflight. RejectedVersion is checked again once it differs from the charts the Operator carries, as after an upgrade of the Operator.
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 check-sm 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 check-sm 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 check-sm 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 check-sm 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 Default 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 Default 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 check-sm 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 Default Description
enabled boolean check-sm 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 check-sm 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 check-sm 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 check-sm 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 check-sm 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 Default Description
gitlabRef GitLabReference check-sm 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 check-sm 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 check-sm 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 check-sm Graph is the ClickHouse database Orbit writes the graph to and serves it from.
jwtSecretRef SecretKeySelector check-sm 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 check-sm 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 Default 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 check-sm 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 check-sm 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 check-sm 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 check-sm Host is the hostname of the PostgreSQL server, for example gitlab-postgresql.databases.svc.cluster.local.

Validation: MaxLength: 253, MinLength: 1.
passwordSecretRef SecretKeySelector check-sm 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 check-sm UsernameSecretRef selects the key of the Secret that holds the user name.
passwordSecretRef SecretKeySelector check-sm 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 Default Description
url string check-sm 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 check-sm 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 Default Description
path string check-sm Path is the name of the field under the environment. It holds no ..

Validation: MaxLength: 253, MinLength: 1, Pattern: ^[^.]+$.
shape FieldShape check-sm 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 check-sm Host is the hostname of the Redis server, for example gitlab-valkey.databases.svc.cluster.local.

Validation: MaxLength: 253, MinLength: 1.
passwordSecretRef SecretKeySelector check-sm 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 Default Description
enabled boolean check-sm 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 check-sm 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 check-sm 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 check-sm 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 Default Description
type GeneratorType check-sm 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 check-sm Name is the name of the Secret.

Validation: MaxLength: 253, MinLength: 1.
key string check-sm 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 Required Default Description
authority CertificateAuthority check-sm Authority is the subject and key of the CA.
domain string check-sm Domain is the domain of the wildcard certificate, which covers it and *.<domain>.

Validation: MaxLength: 253, MinLength: 1.
caDays integer check-sm 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 check-sm CertDays is the validity of the wildcard certificate, in days.

Validation: Maximum: 106751, Minimum: 1.
tlsSecret string check-sm 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 check-sm 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 check-sm CAKey is the key the CA certificate is stored under.

Validation: MaxLength: 253, MinLength: 1, Pattern: ^[-._a-zA-Z0-9]+$.
chainSecret string check-sm 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 check-sm 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 check-sm 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 check-sm 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 check-sm Source is the PostgreSQL server the change data capture stream reads.
queue QueueSpec check-sm Queue is the NATS JetStream server the stream passes through.
sink ClickHouseSinkSpec check-sm 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 check-sm 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 Default 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 Default Description
type StaticVersionType check-sm 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 check-sm 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 check-sm 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.

ValuesReference

ValuesReference names a key of a ConfigMap or Secret that holds Helm values, modeled on spec.valuesFrom of the Flux HelmRelease. The object is always read from the namespace of the resource, and must carry the label operator.gitlab.com/config-source: "true".

Used by: GitLabCoreChartSpec.

Field Type Required Default Description
kind ValuesReferenceKind check-sm Kind is the kind of the object, ConfigMap or Secret.

Validation: Enum: [ConfigMap Secret].
name string check-sm Name is the name of the object in the namespace of the resource.

Validation: MaxLength: 253, MinLength: 1.
valuesKey string No values.yaml ValuesKey is the key of the object that holds the values, as a YAML document of Helm values.

Validation: MaxLength: 253, Pattern: ^[-._a-zA-Z0-9]+$.
optional boolean No Optional renders the chart without this reference when the object or its key is missing. A required reference that is missing stops the render instead.

ValuesReferenceKind

ValuesReferenceKind is the kind of object a ValuesReference names.

Underlying type: string.

Validation:

  • Enum: [ConfigMap Secret]

Used by: ValuesReference.

Value Description
ConfigMap
Secret

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 Required Default Description
kind VersionReferenceKind check-sm Kind is the kind of the object. Only ConfigMap is supported.

Validation: Enum: [ConfigMap].
name string check-sm Name is the name of the object in the namespace of the resource.

Validation: MaxLength: 253, MinLength: 1.
key string check-sm 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 version an instance runs. It is a union discriminated by Type: Version, VersionRef, and ChartVersion belong 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 a GitLab version, written in Version or read from the object VersionRef names, whose chart the Operator looks up in the GitLab release manifest. ChartVersion names a chart instead, and bypasses the manifest.

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

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

Used by: GitLabCoreSpec.

Field Type Required Default Description
type VersionType No Latest Type selects how the version is chosen.
- Static runs the chart of the GitLab version Version names or VersionRef reads, or the chart ChartVersion names, 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.

Without Major, Latest, Previous, and OldestSupported follow the major the instance runs, and before the install the major the count lands on across every released major: with 11.0 the newest release, Latest installs within 11, and Previous and OldestSupported within 10.

It defaults to Latest.

Validation: Enum: [Static Patch Latest Previous OldestSupported].
version string No Version is the released GitLab version the Static type runs, such as 19.5.1. The Operator runs the GitLab chart the release manifest records for it, and reports VersionUnresolved for a version without a record, or with a record that lists no GitLab chart. A change upgrades the instance, and a version whose chart is below the deployed one is refused.

Validation: Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$.
versionRef VersionReference No VersionRef reads the GitLab 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 whose chart is below the deployed one 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.
chartVersion string No ChartVersion is the semantic version of the GitLab chart the Static type runs, in place of Version, without reading the release manifest. Name a chart only for a chart-only fix ahead of the next release, a chart outside the manifest, or testing.

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-]+)*))?$.
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. Without it, they follow the major the instance runs (see Type). A major upgrade is never unattended: setting or 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 GitLab version, or 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>"].