GitLabCore configuration

Status: Implemented Issue: none Parent: GitLabCore reconciler

Goal

An administrator configures a working GitLab instance through a few typed fields, and reaches every other chart setting through free-form values. For the chart values each field sets, see Effective values.

Requirements

  • spec.hostname sets the GitLab host, and its parent domain sets the domain of the sibling hosts. An apex hostname is its own domain.
  • spec.edition selects ee or ce, and defaults to ee.
  • spec.license, spec.postgresql, spec.redis, and spec.objectStorage each reference a Secret. No license key, password, or connection is stored in the resource.
  • Setting spec.objectStorage turns the consolidated object storage on.
  • Setting spec.openbao turns on the GitLab Secret Manager and the bundled OpenBao, against a PostgreSQL connection of its own. It creates no ServiceAccount, Role, or RoleBinding.
  • Leaving spec.networking unset turns the Gateway API off.
  • spec.networking accepts at most one of envoyGatewayController, gatewayClass, and gateway. The API server rejects a second one, and a change of envoyGatewayController.controllerName.
  • envoyGatewayController provisions a GatewayClass named after the namespace and name of the resource, so two instances never share one.
  • gatewayClass and gateway provision no GatewayClass, and add the Envoy extensions only when configureEnvoy is set.
  • A certManager.issuerRef points the provisioned Gateway at an existing Issuer or ClusterIssuer.
  • spec.chart.values win over every value a structured field derives.
  • The Operator overrides win over both: no cert-manager, no GitLab Runner, no bundled Ingress, Gateway, or proxy controller, and no chart-provisioned ACME issuer for the Gateway.
  • The container registry is off unless spec.chart.values turn it on.
  • The chart renders with shared-secrets.provider: controller unless spec.chart.values set another, so a GitLabSecrets provides the Secrets. On a chart that predates the value, the shared secrets Job runs under the ServiceAccount of the Operator, and creates no RBAC.
  • spec.orbitRef names an Orbit in the namespace. While it reports a gRPC endpoint, belongs to the instance, and its JWT Secret exists, GitLab is configured with that endpoint and Secret under global.appConfig.orbit. Orbit is supported on GitLab chart 10.4 or later; an older chart gets no settings.
  • The Orbit never stops the instance from reconciling. While it cannot be configured, for example because the Orbit or its Secret is missing, a read is refused, or spec.chart.values set global.appConfig.knowledgeGraph, which the chart refuses beside orbit, the instance renders without the Orbit settings, and OrbitConnected says why. Only a read that fails transiently, such as a timeout or a throttled request, retries the pass, with the settings kept as they were.
  • A changed endpoint reaches GitLab within 30 seconds, on a pass that requeues.

Out of scope

  • Provisioning PostgreSQL, Redis, object storage, or the OpenBao database.
  • An Ingress mode in spec.networking.
  • Structured fields for the registry, Pages, or backups.

FAQ

  • Why do the free-form values win over the structured fields? To keep them a working escape hatch. ADR 26 decides it.
  • Why is the Gateway API off when networking is unset? The chart default relies on the bundled Envoy Gateway, which the Operator never installs. For more information, see ADR 33.
  • Which chart version do envoyGatewayController and gatewayClass need? 10.4.0 or later. An older chart renders a Gateway whose GatewayClass never renders, and nothing reports it.
  • Why is the registry off by default? It stores images in object storage of its own, which no structured field covers.
  • Why does an instance without spec.objectStorage fail? The chart enables object storage for artifacts, LFS, uploads, and packages with no connection of its own. Unless the free-form values supply one, its checkConfig fails.
  • Why does an Orbit reference make GitLab roll out twice? The Orbit waits for the instance, so the instance renders first without the Orbit settings, and again once the Orbit reports an endpoint. Waiting for the Orbit instead would deadlock. For the other drawbacks, see ADR 37.
  • What if TLS is terminated in front of Orbit? The Orbit then reports no endpoint, and OrbitConnected stays OrbitEndpointPending. Set global.appConfig.orbit in spec.chart.values instead, which wins over the reference.
  • Why chart 10.4 or later? It is the oldest chart the Operator deploys Orbit with. Chart 10.2 knows the settings only as knowledgeGraph, and 10.3 renames them to orbit, so supporting both would mean writing a different key per upgrade step.