Configure Gateway API and Envoy Gateway extensions

Status: Beta

Gateway API support is currently under active development. Please be aware that:

Complete validation across all deployment scenarios has not yet been fully verified.
Configuration values and default settings for Gateway API features are subject to change without notice.
The Gateway API resources are currently only tested with Envoy Gateway. Other Gateway API controllers might need additional configuration.

For more information, see work item 5.

GitLab chart supports Gateway API and bundles Envoy Gateway as one available provider.

Global configuration

Name	Type	Default	Description
`global.gatewayApi.enabled`	Boolean	false	Enable deployment of GatewayAPI resources.
`global.gatewayApi.gatewayRef.name`	String		Gateway name rendered to all Gateway API resources. Use this to reference an externally managed Gateway and to disable the Gateway provided by the chart.
`global.gatewayApi.gatewayRef.namespace`	String		Gateway namespace rendered to all Gateway API resources. Use this to reference an externally managed Gateway in another namespace and to disable the Gateway provided by the chart.
`global.gatewayApi.httpToHttpsRedirect`	Boolean	true	Create an HTTPRoute that redirects all HTTP traffic to HTTPS with a 301 status code. Only effective when `protocol` is `HTTPS` and the Gateway is managed (no `gatewayRef`).
`global.gatewayApi.installEnvoy`	Boolean	false	Install Envoy Gateway subchart and configure a `GatewayClass` and Envoy Gateway API extensions.

Configuring managed Gateway API resources

GitLab chart allows you to customize the managed Gateway, GatewayClass, and Envoy Gateway extensions.

Name	Type	Default	Description
`gatewayApiResources.class.name`	String	`gitlab-gw`	Name of the Gateway class bound to the Gateway.
`gatewayApiResources.class.controllerName`	String	`gateway.envoyproxy.io/gitlab-gatewayclass-controller`	Controller name of the GatewayClass.
`gatewayApiResources.gateway.addresses`	Array	false	Array of addresses to be added to the Gateway.
`gatewayApiResources.gateway.protocol`	String	`HTTPS`	Default listener protocol.
`gatewayApiResources.gateway.annotations`	Map	`{}`	Annotations to add to the managed Gateway.
`gatewayApiResources.gateway.infrastructure`	Object	`{}`	GatewayInfrastructure added to the managed Gateway.
`gatewayApiResources.gateway.listeners`	Object		Listener configuration for the managed Gateway. See below for an example.

Listener configuration

The default listener config only specifies a protocol for listeners with a predefined protocol. Listeners where the protocol depends on your setup inherit the root level protocol:

protocol: HTTPS
listeners:
  http-default:
    protocol: HTTP
  gitlab-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: gitlab-tls
  gitlab-web-geo:
    tls:
      mode: Terminate
      certificateRefs:
        - name: gitlab-web-geo-tls
  gitlab-smartcard-web:
    protocol: ""
    tls:
      mode: Terminate
      certificateRefs:
        - name: gitlab-smartcard-tls
  gitlab-ssh:
    protocol: "TCP"
  registry-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: registry-tls
  pages-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: pages-tls
  kas-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: kas-tls
  kas-workspaces-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: kas-workspaces-tls
  minio-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: minio-tls
  openbao-web:
    tls:
      mode: Terminate
      certificateRefs:
        - name: openbao-tls

Envoy Gateway extensions

If the bundled Envoy Gateway is used, you can customize the EnvoyProxy and optionally create a ClientTrafficPolicy and a SecurityPolicy bound to the managed Gateway.

Envoy Gateway metrics

The bundled Prometheus is set up to collect metrics from both Envoy Gateway and the managed Envoy Proxy. If you have Prometheus Operator custom resource definitions (CRDs) enabled, a ServiceMonitor will be created for Envoy Gateway and a PodMonitor will be created for Envoy Proxy.

gatewayApiResources:
  envoy:
    metrics:
      envoyGateway:
        serviceMonitor:
          enabled: false
          additionalLabels: {}
          endpointConfig: {}
      envoyProxy:
        podMonitor:
          enabled: false
          additionalLabels: {}
          endpointConfig: {}

Route configuration

The Webservice, KAS, Registry, and GitLab Pages are exposed via an HTTPRoute while GitLab Shell is exposed via a TCPRoute. The routes can be customized at the chart level:

subchart:
  gatewayRoute:
    # Enable/disable this route, defaults to `global.gatewayApi.enabled`.
    enabled: true
    # Gateway section, defaults to matching listener.
    sectionName: "section"
    # Gateway reference, defaults to managed Gateway or globally configured external Gateway.
    gatewayName: "gateway"
    gatewayNamespace: "release-namespace"
    # Extra annotations
    annotations: {}
    # Timeout configuration
    timeouts:
      request: 15s
      backendRequest: 15s

If you configure multiple webservice deployment, the route rules can be customized further. Check the Webservice Gateway API documentation for details.

GitLab Geo

To configure GitLab Geo using the Gateway API, an additional hostname can be configured by setting global.geo.gatewayApi.additionalHostname.

The flag should be set to the internal URL on primary sites and to the external/unified URL on secondary sites. Check the Geo setup guide for more information.

Using an external Gateway API provider

The chart can be configured to use an external Gateway API provider, yet not every provider meets the requirements to expose GitLab.

Make sure your Gateway API provider does support:

HTTPRoutes, TCPRoute (for SSH), and GRPCRoutes (for future KAS features)
RegularExpression matches in HTTPRoutes

Note that we only test with the bundled Envoy Gateway chart. Support for other providers is offered on a best-effort basis. We welcome any contributions that document working configurations with other Gateway API providers.

Setting up external Gateway API providers

For GitLab to work with Envoy Gateway escaped slashed in traffic have to remain unchanged. This can be configured with a PatchPolicy.
Note that EnvoyPatchPolicies are disabled by default and Envoy Gateway must be configured to enable them.

Configure an externally managed Gateway

To configure GitLab chart to use an external Gateway, disable the chart-managed Gateway and configure your externally managed Gateway:

global:
  gatewayApi:
    enabled: true
    # Don't install Envoy Gateway subchart and custom resources.
    installEnvoy: false
    gatewayRef:
      name: "custom-gateway"
      namespace: "custom-gateway-namespace"

Configure an externally managed GatewayClass

To configure GitLab chart to use the chart-managed Gateway resource, but an external GatewayClass, disable the bundled Envoy Gateway and configure your GatewayClass:

global:
  gatewayApi:
    enabled: true
    # Don't install Envoy Gateway subchart and custom resources.
    installEnvoy: false
    class:
      # Name of the GatewayClass backed by your Gateway API controller.
      name: custom-class