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 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.

Out of scope

  • Authentication by Bridge itself, in the cluster.
  • The v1beta1 GitLab resource, and the Orbit 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.