TLS Configuration

This guide covers TLS configuration for the MaaS API component to enable encrypted communication for all API traffic.

Quick Verification

For TLS verification commands, see Validation Guide - TLS Verification.

Overview

The MaaS API supports end-to-end TLS encryption across all traffic paths:

sequenceDiagram
    participant Client
    participant Gateway as Gateway<br/>(openshift-ingress)
    participant Authorino as Authorino<br/>(kuadrant-system)
    participant MaaS as maas-api

    Note over Gateway,MaaS: All connections use TLS

    Client->>Gateway: HTTPS request
    Gateway->>Authorino: gRPC/TLS (port 50051)
    Authorino->>Gateway: Auth decision
    Gateway->>MaaS: HTTPS (port 8443)
    MaaS->>Gateway: Response
    Gateway->>Client: Response

When TLS is enabled:

External API traffic is encrypted from client to backend
Internal authentication traffic (Authorino → maas-api) is encrypted
All certificate validation uses a trusted CA bundle

Prerequisites

Authorino TLS Configuration

Authorino handles two TLS-protected traffic flows:

inbound from the Gateway (listener TLS)
outbound to maas-api (for metadata lookups).

For ODH/RHOAI deployments, the inbound flow is a platform pre-requisite for secure LLMInferenceService communication; only the outbound configuration is needed for MaaS.

For all deployments using ./scripts/deploy.sh (both operator and kustomize modes with TLS enabled), both flows are configured automatically via scripts/setup-authorino-tls.sh. Use --disable-tls-backend with deploy.sh to skip this and manage Authorino TLS separately. To run the standalone script:

./scripts/setup-authorino-tls.sh
# Use AUTHORINO_NAMESPACE=rh-connectivity-link for RHCL

Gateway → Authorino (Inbound TLS)

Enables TLS on Authorino's gRPC listener for incoming authentication requests from the Gateway.

# Annotate service for certificate generation
kubectl annotate service authorino-authorino-authorization \
  -n kuadrant-system \
  service.beta.openshift.io/serving-cert-secret-name=authorino-server-cert \
  --overwrite

# Patch Authorino CR to enable TLS listener
kubectl patch authorino authorino -n kuadrant-system --type=merge --patch '
{
  "spec": {
    "listener": {
      "tls": {
        "enabled": true,
        "certSecretRef": {
          "name": "authorino-server-cert"
        }
      }
    }
  }
}'

For more details, see the ODH KServe TLS setup guide.

Authorino → maas-api (Outbound TLS)

Enables Authorino to make HTTPS calls to maas-api for API key validation and metadata lookups. Requires the cluster CA bundle and SSL environment variables.

# Configure SSL environment variables for outbound HTTPS
# Note: The Authorino CR doesn't support envVars, so we patch the deployment directly
kubectl -n kuadrant-system set env deployment/authorino \
  SSL_CERT_FILE=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt \
  REQUESTS_CA_BUNDLE=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt

Note

OpenShift projects the openshift-service-ca.crt ConfigMap, which service-ca-operator populates with the service CA bundle, into every pod's service account volume at /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt. This is the bundle that signs the maas-api serving certificate, and it requires no extra volume mount on the Authorino deployment — which matters because authorino-operator manages that deployment and reverts volumes added to it.

Verify the file is actually present in the pod rather than relying on the absence of errors. Authorino is written in Go, and Go's crypto/x509 ignores an unreadable SSL_CERT_FILE and falls back to the system trust store, so a path that does not exist produces no certificate errors in the logs while never trusting the service CA:

kubectl -n kuadrant-system exec deploy/authorino -- \
  ls -l /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt

Gateway → maas-api TLS (DestinationRule)

The tls overlay includes a DestinationRule to configure TLS origination from the gateway to maas-api.

Why DestinationRule? Gateway API's HTTPRoute doesn't tell Istio to use TLS when communicating with backends. Without BackendTLSPolicy (GA in Gateway API v1.4), an Istio-native DestinationRule is required to configure TLS origination.

Client → Gateway (TLS termination) → [DestinationRule] → maas-api:8443 (TLS origination)

Future consideration

Once Gateway API v1.4+ with BackendTLSPolicy is supported by the Istio Gateway provider, the DestinationRule can be replaced with a standard Gateway API resource.

ExternalModel TLS Origination

By default, the ExternalModel reconciler enables TLS origination for external provider endpoints. The Istio sidecar performs the TLS handshake with the provider, and a DestinationRule with tls.mode: SIMPLE is created.

To disable TLS origination for an ExternalModel (e.g., for internal non-TLS endpoints), set the maas.opendatahub.io/tls annotation to "false":

Cleartext credential traffic

Disabling TLS while credentialRef is set means the provider API key is sent in cleartext between the gateway and the endpoint. Only disable TLS on a trusted, isolated network where credential exposure is not a concern.

apiVersion: maas.opendatahub.io/v1alpha1
kind: ExternalModel
metadata:
  name: internal-vllm
  namespace: llm
  annotations:
    maas.opendatahub.io/tls: "false"
    maas.opendatahub.io/port: "8000"
spec:
  provider: openai
  endpoint: vllm.internal.example.com
  targetModel: my-model
  credentialRef:
    name: vllm-api-key

When TLS is disabled:

The ServiceEntry protocol changes from HTTPS to HTTP
No DestinationRule is created; any existing controller-managed DestinationRule is deleted. DestinationRules annotated with opendatahub.io/managed: "false" are preserved.
The default port remains 443 unless overridden with maas.opendatahub.io/port (valid range: 1–65535)

For full annotation details, see the ExternalModel CRD Reference.

Custom maas-api TLS Configuration

This section covers how maas-api is configured to use TLS certificates. These settings are automatically configured by the kustomize overlays; manual configuration is only needed for custom deployments or non-OpenShift environments.

The maas-api component accepts TLS configuration via environment variables:

Variable	Description	Default
`TLS_CERT`	Path to TLS certificate file	`/etc/maas-api/tls/tls.crt`
`TLS_KEY`	Path to TLS private key file	`/etc/maas-api/tls/tls.key`
`TLS_SELF_SIGNED`	Generate a self-signed certificate at startup (`true` or `false`)	`false`
`TLS_MIN_VERSION`	Minimum accepted TLS version (`1.2` or `1.3`)	`1.2`

When TLS_CERT and TLS_KEY are both set, the API server listens on HTTPS (port 8443) instead of HTTP (port 8080). If TLS_SELF_SIGNED is set to true, a self-signed certificate is generated automatically and explicit cert/key paths are not required. When both cert/key files and TLS_SELF_SIGNED are provided, the cert/key files take precedence.

By default, certificates are mounted to the paths in the table above from Kubernetes Secret maas-api-serving-cert.

Kustomize Overlays

Pre-configured overlays are available for common scenarios:

Overlay	Description
`deployment/base/maas-api/overlays/tls`	Base TLS overlay for maas-api (deployment patch, service annotation, DestinationRule)
`maas-api/deploy/overlays/odh`	Tenant reconciler overlay (TLS, gateway policies)

The tls base overlay includes:

Resource	Purpose
`deployment-patch.yaml`	Configure maas-api container for TLS
`service-patch.yaml`	Add serving-cert annotation, expose port 8443
`destinationrule.yaml`	Configure gateway TLS to maas-api backend

maas-api is deployed by the Tenant reconciler in maas-controller. The deploy.sh script installs prerequisites (policy engine, PostgreSQL, Authorino TLS) and then deploys maas-controller, which creates AITenant/models-as-a-service; that AITenant creates or adopts MaasTenantConfig/default-tenant, and maas-api is reconciled via SSA.

To verify that the overlay builds correctly:

kustomize build deployment/base/maas-api/overlays/tls

Verifying TLS Configuration

For TLS verification commands, see Validation Guide - TLS Verification.