Bridge API

Status: Implemented Issue: none Parent: none

Goal

A frontend configures GitLab instances through an HTTP API instead of writing custom resources. The API grants a caller nothing beyond their own Kubernetes permissions.

Requirements

  • Bridge exists only in a build with the bridge tag, and serves only with ENABLE_BRIDGE=true. Release images carry no Bridge.
  • The API lists, reads, creates, updates, and deletes GitLabCore resources, in one namespace or across every namespace the caller may list.
  • Every /api request acts as the caller its bearer token names, never as the Operator.
  • A request with no token receives 401. A request the token may not perform receives 403.
  • A value the resource definition would reject receives 422, which names the field.
  • The OpenAPI document carries the field constraints of the definition. A cross-field rule of the definition comes back as the 422 of the API server.
  • Only Secret references travel over the API, never a license key or a password.
  • Each instance has at most one Siphon through the API. The API finds it by its reference to the instance, whatever its name.
  • A Siphon created through the API is named <instance>-siphon. A name longer than 31 characters receives 422.
  • A read of the Siphon of an instance reports none when the cluster does not serve the kind.
  • The Orbit of an instance follows Orbit add-on.
  • The chart versions endpoint lists the versions of the chart repository, newest first. When the repository is unreachable or dynamic chart pull is off, it lists the bundled versions.
  • The OpenAPI document, the documentation UI, and the SPA are served without a token.
  • When the caller may list namespaces, the namespaces endpoint lists every namespace, sorted by name, without the hidden ones and without those being deleted. It also returns the rules for hidden names.
  • A caller who may not list namespaces receives an empty list that says so, and the rules.
  • Hidden names start with kube- or openshift-, or are openshift or one of the add-on namespaces cert-manager, clickhouse-operator-system, cnpg-system, envoy-gateway-system, ingress-nginx, nats, seaweedfs-system, and traefik.
  • The API creates a namespace by name. A hidden name, one that is not a DNS label, or a namespace being deleted receives 422, and another existing one 409.
  • Creating a GitLabCore in a namespace that does not exist receives 404, which names the namespace.

Out of scope

  • Authentication by Bridge itself, in the cluster.
  • The v1beta1 GitLab resource.
  • Exposing Bridge through a Service or an Ingress.

FAQ

  • Why does Bridge not use the Operator ServiceAccount? It holds cluster-wide permissions, and every caller would inherit them. For more information, see ADR 34.
  • Why do the paths say gitlabs when the resource is GitLabCore? /api/v1 versions the Bridge API, not the custom resource.
  • Why does Bridge repeat the field validation of the definition? So the OpenAPI document and the generated client carry it, and a bad value fails in Bridge with the field named.
  • Why does the namespaces endpoint hide some namespaces? They belong to the cluster or to the add-ons an instance depends on, not to a GitLab instance. The add-on names are those the repository’s guides and tests install. A GitLabCore created in one of them through the gitlabs endpoints is still accepted.
  • Why does a caller who may not list namespaces get an empty list instead of 403? The form then takes a typed name, which the API server still authorizes. The rules come back either way.
  • Does Bridge label or delete the namespaces it creates? No.