API Gateway Chart Values Reference

This reference lists the API Gateway values the Axual Governance Helm chart exposes: the image and pull secrets, the server TLS bundle, the application configuration sections, and the Ingress, OpenShift Route and Kubernetes Gateway API options.

Type

Reference

Goal

Look up an API Gateway chart value while writing the Axual Governance values file.

Audience

Platform Operator deploying the API Gateway that fronts Axual Governance.

When to use

While configuring the API Gateway, alongside the procedure that installs Axual Governance.

The sections below cover each area in this reference:

About API Gateway
API Gateway Configuration

About API Gateway

API Gateway is a reverse proxy built with Spring Cloud Gateway. It routes each request to a backend microservice based on the request path.

API Gateway Configuration

The API Gateway needs the three mandatory sections described under Application Configuration, plus the image, TLS and exposure values below. Replace every <VALUE> placeholder with your own value before installing.

For the full list of configuration options, see the Configuration section of the API Gateway page.

API Gateway Repository Configuration

You can override registry, tag, and pullPolicy for the API Gateway pod. By default these values come from the Axual Governance chart. You can also override imagePullSecrets; if you leave it unset, the API Gateway pod uses global.imagePullSecrets.

values.yaml

api-gateway:

  image:
    registry: "registry.axual.io"
    pullPolicy: "Always"
    tag: "0.4.1"

  imagePullSecrets:
    - name: axualdockercred

Server Security Configuration

To secure incoming connections with SSL, point the API Gateway at existing Kubernetes Secrets that hold the Privacy Enhanced Mail (PEM) certificates.

values.yaml

api-gateway:

  env:
    - name: SPRING_SSL_BUNDLE_PEM_API-GATEWAY_KEYSTORE_CERTIFICATE
      valueFrom:
        secretKeyRef:
          # key identifying the server-certificate within the k8s-secret
          key: <server-certificate-name>
          name: <k8s-secret-name>
    - name: SPRING_SSL_BUNDLE_PEM_API-GATEWAY_KEYSTORE_PRIVATE_KEY
      valueFrom:
        secretKeyRef:
          # key identifying the server-key within the k8s-secret
          key: <server-key-name>
          name: <k8s-secret-name>

  config:
    server:
      ssl:
        enabled: true
        # name referring to the bundle-pem
        bundle: "api-gateway"

Application Configuration

API Gateway is a Spring application, so it reads its settings from an application.yml file. Whatever you put under config is injected into a ConfigMap and mounted as that file. The first three subsections below are mandatory on every installation; the fourth applies once the Metrics Exposer backend is enabled.

Gateway Endpoints

These values say where each backend microservice is reachable. Disable the optional backends your installation does not run.

Use the service name of each component as your installation names it.

values.yaml

api-gateway:

  config:
    gateway:
      endpoints:
        # Mandatory Backend service
        platformManager:
          enabled: true
          url: "http://<platform-manager-service-name>"
        # Optional Backend service
        organizationManager:
          enabled: true
          url: "http://<organization-manager-service-name>"
        # Optional Backend service
        topicBrowse:
          enabled: true
          url: "http://<topic-browse-service-name>"
        # Optional Backend service
        metricsExposer:
          enabled: false
          url: "http://<metrics-exposer-service-name>"
        # Optional Backend service
        metricsExposerApiDocs:
          enabled: false
          url: "http://<metrics-exposer-service-name>"
        # Mandatory Frontend service
        platformUi:
          enabled: true
          url: "http://<platform-ui-service-name>"
        # Mandatory Backend service
        keycloak:
          enabled: true
          url: "http://<keycloak-http-service-name>"

Local and SSO Authentication Configurations

These values define the two sets of security restrictions the API Gateway applies, depending on the endpoint being called:

Local authentication covers users who signed up with an email address and authenticate against the local realm to reach the Platform Manager endpoints.
Single Sign-On (SSO) authentication covers users who authenticate with their organisation identity, such as Active Directory or Lightweight Directory Access Protocol (LDAP).

values.yaml

api-gateway:

  config:
    # This defines the Local Realm for user registration
    local:
      auth:
        # Endpoint of the Local Authentication Server Issuer URI (e.g. https://idp.example.com ).
        # This endpoint is never called. It is used to compare the iss claim of the JWT token.
        issuerUrlForValidation: https://platform.<domain>/auth/realms/local
        # Endpoint of the Local Authentication Server JWK Set URI (e.g. https://idp.example.com/.well-known/jwks.json ).
        # Used for signing up new tenants.
        jwkSetUri: http://keycloak-http/auth/realms/local/protocol/openid-connect/certs

    # Keycloak Authentication Server
    sso:
      keycloak:
        # URL of Keycloak to be accessed outside the cluster
        advertisedBaseUrl: https://platform.<domain>
        # URL of Keycloak to be accessed within the cluster
        internalBaseUrl: http://keycloak-http
        # Allow accessing Keycloak without TLS chain validation
        useInsecureTrustManager: false

Permission and Topic Browse Config APIs

These values say where the permission API and the browse-config resource are reachable. Both paths are fixed, so only the Platform Manager service name changes.

Adjust only the service name of the Platform Manager, as your installation names it.

values.yaml

api-gateway:

  config:
    # Service Name of Platform Manager
    # the path `/api/auth` is fixed
    permissions-api:
      url: "http://<platform-manager-service-name>/api/auth"
    # Service Name of Platform Manager
    # the path `/api/stream_configs/{id}/browse-config` is fixed
    topic-browse-config-api:
      url: "http://<platform-manager-service-name>/api/stream_configs/{id}/browse-config"

Metrics Exposer Configuration

These values are mandatory once the Metrics Exposer backend is enabled in the API Gateway. The API Gateway intercepts every request to Metrics Exposer (/api/metrics/**) and calls this Platform Manager API to enrich the request before forwarding it.

Adjust only the service name of the Platform Manager, as your installation names it.

values.yaml

api-gateway:
  config:
    # Service Name of Platform Manager
    # the path `/api/monitoring_information` is fixed
    metrics-exposer-config-api:
      url: "http://<platform-manager-service-name>/api/monitoring_information"

Credentials Secret: `secrets` and `existingSecretName`

API Gateway reads a second configuration file, secrets.yml, from a Kubernetes Secret. It takes the same structure as config, is loaded after it, and overrides any key the two share. existingSecretName names an existing Secret holding a secrets.yml key. When it is "", the chart creates the Secret from secrets. For the procedure, see How to Store Component Credentials in a Kubernetes Secret.

API Gateway reads no Axual credential from config, and its TLS certificates come from PEM Secrets, as shown in Server Security Configuration. The one credential key that belongs in secrets.yml, when you set it, is:

management.opentelemetry.tracing.export.otlp.headers.<NAME>, for example an authorization header for the OpenTelemetry collector

Ingress Configuration

The API Gateway Helm chart can create an Ingress that exposes it outside the Kubernetes cluster. Self-Service only works for users once the API Gateway is reachable from outside, so this is normally enabled.

values.yaml

api-gateway:

  ingress:
    # -- Enable creation of the Ingress resource to expose this service.
    enabled: true
    # -- The name of the IngressClass cluster resource.
    # The associated IngressClass defines which controller will implement the resource.
    className: ""
    # -- Annotations to add to the Ingress resource.
    annotations: {}
    hosts:
      - # -- The fully qualified domain name of a network host.
        host: "<hostDomainName>"
        paths:
          - # -- Matched against the path of an incoming request.
            path: "/"
            # -- Determines the interpretation of the Path matching.
            # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
            pathType: "ImplementationSpecific"
    # -- TLS configuration for this Ingress.
    tls: []
    #  - secretName: chart-example-tls
    #    hosts:
    #      - <hostDomainName>

Route Configuration

On OpenShift, the API Gateway Helm chart can create a Route instead of an Ingress. The same reasoning applies: Self-Service only works for users once the API Gateway is reachable from outside the cluster.

values.yaml

api-gateway:

  route:
    # -- Enable creation of an OpenShift Route resource to expose this service.
    enabled: true
    # -- Annotations to add to the Route.
    annotations: {}
    # -- Labels to add to the route.
    labels: {}
    # -- An alias/DNS that points to the service. Optional. If not specified a route name will typically be automatically chosen.
    host: ""
    # -- subdomain is a DNS subdomain that is requested within the ingress controller's domain (as a subdomain). If host is set this field is ignored.
    subdomain: ""
    # -- Path that the router watches for, to route traffic for to the service.
    path: "/"
    tls:
      # -- The Certificate Authority certificate contents.
      caCertificate: ""
      # -- Certificate contents. This should be a single serving certificate, not a certificate chain. Do not include a CA certificate.
      certificate: ""
      # -- Key file contents.
      key: ""
      # -- Indicates termination type. One of: `edge`, `passthrough`, or `reencrypt`.
      termination: "passthrough"
      # --The CA certificate of the final destination. When using reencrypt termination this file should be provided
      # in order to have routers use it for health checks on the secure connection.
      destinationCACertificate: ""

Gateway API Configuration

From API Gateway chart 0.11.0, shipped in Axual Governance chart 1.6.0, the chart can expose the API Gateway through the Kubernetes Gateway API. The gatewayApi block is an alternative to ingress and route. The chart does not check that only one of the three is enabled. The chart never renders the Gateway itself. The route attaches to an existing shared Gateway, either directly through parentRefs or through a ListenerSet the chart renders.

The chart renders the following gateway.networking.k8s.io/v1 resources, each named after the chart’s fullname:

Resource Template Rendered when

Resource	Template	Rendered when
`HTTPRoute`	`httproute.yaml`	`gatewayApi.enabled` is `true`. It forwards the paths of every host to the API Gateway Service on `service.port`.
`ListenerSet`	`listenerset.yaml`	`gatewayApi.enabled` and `gatewayApi.listenerSet.enabled` are `true`. It adds one HTTPS listener on port `443` per host to the shared `Gateway` and terminates TLS with the host’s certificate Secret. It accepts routes from the release namespace only.
`BackendTLSPolicy`	`backendtlspolicy.yaml`	`gatewayApi.enabled` and `gatewayApi.backendTls.enabled` are `true`. It makes the gateway connect to the Service port named `api` over TLS.

HTTPRoute

httproute.yaml

gatewayApi.enabled is true. It forwards the paths of every host to the API Gateway Service on service.port.

ListenerSet

listenerset.yaml

gatewayApi.enabled and gatewayApi.listenerSet.enabled are true. It adds one HTTPS listener on port 443 per host to the shared Gateway and terminates TLS with the host’s certificate Secret. It accepts routes from the release namespace only.

BackendTLSPolicy

backendtlspolicy.yaml

gatewayApi.enabled and gatewayApi.backendTls.enabled are true. It makes the gateway connect to the Service port named api over TLS.

The keys below sit under api-gateway: in the Axual Governance values file:

Key Type Default Description

Key	Type	Default	Description
`gatewayApi.enabled`	boolean	`false`	Renders the `HTTPRoute`. The render fails when the route has no parent: neither `gatewayApi.listenerSet.enabled` nor `gatewayApi.parentRefs` is set.
`gatewayApi.annotations`	object	`{}`	Annotations added to every Gateway API resource the chart renders.
`gatewayApi.parentRefs`	list	`[]`	The `Gateway` or `ListenerSet` resources the `HTTPRoute` attaches to, passed through verbatim. Used only when `gatewayApi.listenerSet.enabled` is `false`.
`gatewayApi.hosts`	list	One host, `chart-example.local`, with path `/api`	The hosts to expose. All paths of all hosts go into one `HTTPRoute` rule, which matches hostnames and paths independently. The render fails when the list is empty or holds no path.
`gatewayApi.hosts[].host`	string	`"chart-example.local"`	Fully qualified domain name of the host. An empty or wildcard (`*`) hostname fails the render.
`gatewayApi.hosts[].certificateSecretName`	string	`""`	Secret holding the TLS certificate for this host’s listener. Overrides `gatewayApi.listenerSet.certificateSecretName`.
`gatewayApi.hosts[].paths[].path`	string	`"/api"`	Matched against the path of an incoming request.
`gatewayApi.hosts[].paths[].pathType`	string	`"PathPrefix"`	How the route matches the path. One of: `PathPrefix`, `Exact`.
`gatewayApi.listenerSet.enabled`	boolean	`false`	Renders the `ListenerSet` and attaches the `HTTPRoute` to it instead of to `gatewayApi.parentRefs`.
`gatewayApi.listenerSet.gateway.name`	string	`""`	Name of the shared `Gateway` the `ListenerSet` attaches to. Required when `gatewayApi.listenerSet.enabled` is `true`.
`gatewayApi.listenerSet.gateway.namespace`	string	`""`	Namespace of the shared `Gateway`. Required when `gatewayApi.listenerSet.enabled` is `true`.
`gatewayApi.listenerSet.certificateSecretName`	string	`""`	Secret holding the TLS certificate for every host that does not set its own. Resolved in the release namespace, so no `ReferenceGrant` is needed. A host with no certificate Secret fails the render.
`gatewayApi.backendTls.enabled`	boolean	`false`	Renders the `BackendTLSPolicy`. Required when the pod serves TLS itself, as in Server Security Configuration. Without it the gateway connects in plain text and the route returns `502`.
`gatewayApi.backendTls.hostname`	string	`""`	Hostname the backend certificate is validated against. Required when `gatewayApi.backendTls.enabled` is `true`.
`gatewayApi.backendTls.caCertificateRefs`	list	`[]`	ConfigMaps or Secrets holding the CA certificates that validate the backend certificate. When empty, the system CA bundle is used.

gatewayApi.enabled

boolean

false

Renders the HTTPRoute. The render fails when the route has no parent: neither gatewayApi.listenerSet.enabled nor gatewayApi.parentRefs is set.

gatewayApi.annotations

object

{}

Annotations added to every Gateway API resource the chart renders.

gatewayApi.parentRefs

list

[]

The Gateway or ListenerSet resources the HTTPRoute attaches to, passed through verbatim. Used only when gatewayApi.listenerSet.enabled is false.

gatewayApi.hosts

list

One host, chart-example.local, with path /api

The hosts to expose. All paths of all hosts go into one HTTPRoute rule, which matches hostnames and paths independently. The render fails when the list is empty or holds no path.

gatewayApi.hosts[].host

string

"chart-example.local"

Fully qualified domain name of the host. An empty or wildcard (*) hostname fails the render.

gatewayApi.hosts[].certificateSecretName

string

""

Secret holding the TLS certificate for this host’s listener. Overrides gatewayApi.listenerSet.certificateSecretName.

gatewayApi.hosts[].paths[].path

string

"/api"

Matched against the path of an incoming request.

gatewayApi.hosts[].paths[].pathType

string

"PathPrefix"

How the route matches the path. One of: PathPrefix, Exact.

gatewayApi.listenerSet.enabled

boolean

false

Renders the ListenerSet and attaches the HTTPRoute to it instead of to gatewayApi.parentRefs.

gatewayApi.listenerSet.gateway.name

string

""

Name of the shared Gateway the ListenerSet attaches to. Required when gatewayApi.listenerSet.enabled is true.

gatewayApi.listenerSet.gateway.namespace

string

""

Namespace of the shared Gateway. Required when gatewayApi.listenerSet.enabled is true.

gatewayApi.listenerSet.certificateSecretName

string

""

Secret holding the TLS certificate for every host that does not set its own. Resolved in the release namespace, so no ReferenceGrant is needed. A host with no certificate Secret fails the render.

gatewayApi.backendTls.enabled

boolean

false

Renders the BackendTLSPolicy. Required when the pod serves TLS itself, as in Server Security Configuration. Without it the gateway connects in plain text and the route returns 502.

gatewayApi.backendTls.hostname

string

""

Hostname the backend certificate is validated against. Required when gatewayApi.backendTls.enabled is true.

gatewayApi.backendTls.caCertificateRefs

list

[]

ConfigMaps or Secrets holding the CA certificates that validate the backend certificate. When empty, the system CA bundle is used.

The example below exposes the API Gateway through a ListenerSet on a shared Gateway, with TLS to the pod:

values.yaml

api-gateway:

  gatewayApi:
    enabled: true
    hosts:
      - host: "<hostDomainName>"
        paths:
          - path: "/"
            pathType: "PathPrefix"
    listenerSet:
      enabled: true
      gateway:
        name: "<shared-gateway-name>"
        namespace: "<shared-gateway-namespace>"
      certificateSecretName: "<tls-secret-name>"
    backendTls:
      enabled: true
      hostname: "<backend-certificate-hostname>"
      caCertificateRefs:
        - group: ""
          kind: ConfigMap
          name: "<backend-ca-configmap-name>"

Without a ListenerSet, parentRefs names the listener on an existing Gateway, which then holds the TLS certificate:

values.yaml

api-gateway:

  gatewayApi:
    enabled: true
    parentRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: "<shared-gateway-name>"
        namespace: "<shared-gateway-namespace>"
        sectionName: "<listener-name>"
    hosts:
      - host: "<hostDomainName>"
        paths:
          - path: "/"
            pathType: "PathPrefix"

API Gateway Chart Values Reference

Contents

About API Gateway

API Gateway Configuration

API Gateway Repository Configuration

Server Security Configuration

Application Configuration

Gateway Endpoints

Local and SSO Authentication Configurations

Permission and Topic Browse Config APIs

Metrics Exposer Configuration

Credentials Secret: secrets and existingSecretName

Ingress Configuration

Route Configuration

Gateway API Configuration

Credentials Secret: `secrets` and `existingSecretName`