For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
HTTPS access
Serve the Solo UI over TLS on your own domain by fronting it with a Kubernetes Gateway API gateway.
Put an HTTPS listener in front of the Solo UI, so that users reach it on a domain that you own with a TLS certificate that their browser trusts.
By default, the management chart creates the solo-enterprise-ui service as a LoadBalancer and serves plain HTTP on it. That address carries the login flow, the access token of every signed-in user, and the mesh data that the UI renders, all unencrypted. The install guide therefore limits you to a load balancer address on a trusted network, or a local port-forward. Follow this guide to serve the UI over TLS on your own domain instead.
You create a TLS certificate, front the UI with a gateway that terminates HTTPS, point your identity provider at the new domain, and then tell the UI what its public address is.
Warning
Do not expose the UI on a public domain while the built-in auto identity provider is in use. The auto provider signs every visitor in as the hardcoded admin user without asking for credentials, so anyone who reaches the address gets full access. Set up an external OIDC provider before you complete this guide.
Before you begin
Install the Solo UI in your ambient mesh, and confirm that you can reach it.
Confirm that the UI is set up with your own identity provider. The UI uses the built-in auto identity provider until you set
oidc.issuer, and that provider signs in every visitor as the hardcodedadminuser without asking for credentials. If the following command returns no issuer, set up an external OIDC provider before you continue.helm get values solo-management -n solo-enterprise -o yaml | grep -A3 '^oidc:'Get a domain name for the UI from your domain name provider, and a TLS certificate and key for that domain. Consider cert-manager and external-dns, or the equivalent services from your cloud provider, to issue the certificate and manage the DNS record for you.
Decide which gateway terminates TLS for the UI. Any Kubernetes Gateway API implementation in your cluster works, because the UI is an ordinary Kubernetes service behind an HTTPRoute. The ingress gateway options guide compares the gateways. This guide includes steps for the following gateways.
GatewayClass When to use it istioThe ingress gateway that ships with your ambient mesh. No extra product and no extra license, so this is the shortest path if you run no other gateway. enterprise-agentgatewayThe recommended ingress gateway for ambient meshes, and the right choice if you already run it or you also route agent, MCP, or LLM traffic. Requires a separate Solo Enterprise for agentgateway license. enterprise-kgatewayUse if you already run Solo Enterprise for kgateway as your ingress. Save the hostname that you want to serve the UI on. This hostname must match the domain that your TLS certificate is issued for.
export UI_HOST=solo-ui.example.com
Create the TLS certificate secret
Store the certificate and key for your domain in a Kubernetes secret in the solo-enterprise namespace. The gateway reads this secret to terminate TLS.
Create the secret from your certificate and key files. Replace the file paths with the paths to your own certificate and key.
kubectl create secret tls solo-ui-https-cert \ -n solo-enterprise \ --cert=<filepath/tls.crt> \ --key=<filepath/tls.key> \ --dry-run=client -o yaml | kubectl apply -f -Verify that the secret holds both keys.
kubectl get secret solo-ui-https-cert -n solo-enterprise -o jsonpath='{.data}' | jq 'keys'Example output:
[ "tls.crt", "tls.key" ]
Note
The Gateway and the secret go in the solo-enterprise namespace, alongside the UI. Keeping all three in one namespace means that the HTTPRoute reaches the UI service without a ReferenceGrant. If your gateway must live in another namespace, create a ReferenceGrant in solo-enterprise that permits the route to reference the solo-enterprise-ui service.
Create the HTTPS gateway
Create a Gateway with an HTTPS listener for your domain. The listener terminates TLS and forwards the decrypted request to the UI inside the cluster.
Use the istio GatewayClass as the quickest way to get started with an ingress gateway for the Solo UI. The class ships with your ambient mesh, so it needs no other product and no other license.
Create the Gateway with the
istioGatewayClass, which your ambient mesh installs by default.kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: solo-ui-https namespace: solo-enterprise spec: gatewayClassName: istio listeners: - name: https protocol: HTTPS port: 443 hostname: "${UI_HOST}" tls: mode: Terminate certificateRefs: - name: solo-ui-https-cert kind: Secret allowedRoutes: namespaces: from: Same EOFSetting Description spec.gatewayClassNameThe GatewayClass that provisions the gateway. The istioclass ships with your ambient mesh, and istiod creates the gateway deployment and service for you.spec.listeners.hostnameThe domain that the listener accepts requests for. This value must match the domain that your TLS certificate is issued for. spec.listeners.tls.modeTerminatedecrypts HTTPS at the gateway and forwards the request to the UI over the mesh. Because thesolo-enterprisenamespace runs in the ambient mesh, ztunnel encrypts that second hop with mTLS.spec.listeners.tls.certificateRefsThe secret that holds the certificate and key. The secret must be in the same namespace as the Gateway. spec.allowedRoutes.namespaces.fromSamerestricts the listener to routes in thesolo-enterprisenamespace, which is where you create the HTTPRoute in the next step.Verify that istiod provisioned the gateway and programmed the listener.
kubectl get gateway solo-ui-https -n solo-enterpriseExample output, in which
PROGRAMMEDisTrueandADDRESSshows the address that your cloud provider assigned:NAME CLASS ADDRESS PROGRAMMED AGE solo-ui-https istio 198.51.100.10 True 45sThe
istioGatewayClass names the generated deployment and service after the Gateway with an-istiosuffix, such assolo-ui-https-istio. The generated pod carries theistio.io/dataplane-mode: nonelabel, so ztunnel does not capture the gateway itself even though thesolo-enterprisenamespace is in the mesh.Note
On a cluster with no load balancer provider, such as a local kind or minikube cluster,
PROGRAMMEDstaysFalsewith the reasonAddressNotAssigned, because the generated service never receives an external address. The gateway itself is healthy: its pod runs, routes attach, and it serves traffic. Check theAcceptedandResolvedRefsconditions instead, then reach the gateway through a port-forward as described in Verify the HTTPS endpoint.kubectl get gateway solo-ui-https -n solo-enterprise -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
Use the enterprise-agentgateway GatewayClass if you already use Solo Enterprise for agentgateway as the preferred ingress for ambient mesh and agentic traffic.
If you have not already, install Solo Enterprise for agentgateway with the Istio integration enabled.
Create the Gateway with the
enterprise-agentgatewayGatewayClass.kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: solo-ui-https namespace: solo-enterprise spec: gatewayClassName: enterprise-agentgateway listeners: - name: https protocol: HTTPS port: 443 hostname: "${UI_HOST}" tls: mode: Terminate certificateRefs: - name: solo-ui-https-cert kind: Secret allowedRoutes: namespaces: from: Same EOFSetting Description spec.gatewayClassNameThe GatewayClass that provisions the gateway. Installing Solo Enterprise for agentgateway creates the enterprise-agentgatewayclass for you.spec.listeners.hostnameThe domain that the listener accepts requests for. This value must match the domain that your TLS certificate is issued for. spec.listeners.tls.modeTerminatedecrypts HTTPS at the gateway and forwards the request to the UI. With the Istio integration enabled, the gateway opens an HBONE connection to the UI, so the second hop stays mutually authenticated.spec.listeners.tls.certificateRefsThe secret that holds the certificate and key. The secret must be in the same namespace as the Gateway. spec.allowedRoutes.namespaces.fromSamerestricts the listener to routes in thesolo-enterprisenamespace, which is where you create the HTTPRoute in the next step.Verify that the Gateway is programmed.
kubectl get gateway solo-ui-https -n solo-enterpriseExample output:
NAME CLASS ADDRESS PROGRAMMED AGE solo-ui-https enterprise-agentgateway 198.51.100.10 True 45s
Use the enterprise-kgateway GatewayClass if you already run Solo Enterprise for kgateway as your ingress.
If you have not already, install Solo Enterprise for kgateway and integrate it with your ambient mesh.
Create the Gateway with the
enterprise-kgatewayGatewayClass.kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: solo-ui-https namespace: solo-enterprise spec: gatewayClassName: enterprise-kgateway listeners: - name: https protocol: HTTPS port: 443 hostname: "${UI_HOST}" tls: mode: Terminate certificateRefs: - name: solo-ui-https-cert kind: Secret allowedRoutes: namespaces: from: Same EOFSetting Description spec.gatewayClassNameThe GatewayClass that provisions the gateway. Installing Solo Enterprise for kgateway creates the enterprise-kgatewayclass for you.spec.listeners.hostnameThe domain that the listener accepts requests for. This value must match the domain that your TLS certificate is issued for. spec.listeners.tls.modeTerminatedecrypts HTTPS at the gateway and forwards the request to the UI over the mesh.spec.listeners.tls.certificateRefsThe secret that holds the certificate and key. The secret must be in the same namespace as the Gateway. spec.allowedRoutes.namespaces.fromSamerestricts the listener to routes in thesolo-enterprisenamespace, which is where you create the HTTPRoute in the next step.Verify that the Gateway is programmed.
kubectl get gateway solo-ui-https -n solo-enterpriseExample output:
NAME CLASS ADDRESS PROGRAMMED AGE solo-ui-https enterprise-kgateway 198.51.100.10 True 45s
Point DNS at the gateway
Save the external address of the gateway. Every GatewayClass in this guide labels its generated service with the Gateway name, so the following command works for all of them. The address might take a few seconds to appear.
export GATEWAY_ADDRESS=$(kubectl get svc -n solo-enterprise \ -l gateway.networking.k8s.io/gateway-name=solo-ui-https \ -o jsonpath="{.items[0].status.loadBalancer.ingress[0]['hostname','ip']}") echo ${GATEWAY_ADDRESS}In your DNS provider, create a record that points
${UI_HOST}at${GATEWAY_ADDRESS}. Create an A record for an IP address, or a CNAME record for a hostname.
Route to the UI
Create an HTTPRoute that sends requests for your domain to the UI.
Create the HTTPRoute. Port 80 of the
solo-enterprise-uiservice reaches the UI backend, which serves the UI frontend and the UI APIs from the same address.kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: solo-enterprise-ui namespace: solo-enterprise spec: parentRefs: - name: solo-ui-https namespace: solo-enterprise hostnames: - "${UI_HOST}" rules: - matches: - path: type: PathPrefix value: / backendRefs: - name: solo-enterprise-ui port: 80 EOFSetting Description spec.parentRefsThe Gateway that serves this route. The listener that you created in the previous step accepts routes from its own namespace only, so the route must stay in solo-enterprise.spec.hostnamesThe domain that the route matches. This value must fall within the listener hostname, or the gateway rejects the route.spec.rules.matches.pathA /prefix sends every path to the UI. The UI backend serves the frontend assets and its own APIs under/api, so a single rule covers both.spec.rules.backendRefs.portPort 80 of the solo-enterprise-uiservice, which targets the UI backend on container port 8090.Note
To serve the UI under a path prefix instead of the root, such as
https://solo-ui.example.com/mesh/, set thepath.valueto that prefix, setui.basePathto the same prefix in Update the UI settings, and add the prefix to the identity provider redirect URIs in Point the identity provider at the domain. The value must start with/and must not end with/.Verify that the gateway accepted the route.
kubectl get httproute solo-enterprise-ui -n solo-enterprise -o yamlExample output, in which the
AcceptedandResolvedRefsconditions are bothTrue:status: parents: - conditions: - message: Route was valid reason: Accepted status: "True" type: Accepted - message: All references resolved reason: ResolvedRefs status: "True" type: ResolvedRefsConfirm that the listener reports the attached route.
kubectl get gateway solo-ui-https -n solo-enterprise -o jsonpath='{.status.listeners[0].attachedRoutes}'Example output:
1
Note
This topology needs no cross-origin resource sharing (CORS) policy, because the UI frontend and the UI backend are both served from ${UI_HOST}. Add a CORS policy only if you give the backend a hostname of its own.
Point the identity provider at the domain
The UI now answers on a new address, so your identity provider must accept that address in the login flow. Until you update it, the provider rejects the redirect and users cannot sign in.
If you have not set up an external provider yet, follow the External OIDC provider guide now, and use https://${UI_HOST} as the UI address throughout it. That guide registers both clients against the HTTPS domain from the start, so you can skip the rest of this section. To update a provider that you already set up against the old address, continue with the following steps.
In your identity provider, update both the backend client and the frontend client with the following redirect URIs.
Setting Value Redirect URI https://${UI_HOST}/callbackPost-logout redirect URI https://${UI_HOST}/logoutIf your provider enforces its own CORS rules, add
https://${UI_HOST}as an allowed origin. The browser calls the token endpoint of the provider directly, so the login flow fails without this entry.
Update the UI settings
Update the UI with the new public address, and stop publishing the old plain-HTTP load balancer.
Get the current values of your management Helm release, so that your upgrade preserves them.
helm get values solo-management -n solo-enterprise -o yaml > management.yamlAdd the following values to
management.yaml.service: ui: type: ClusterIPField Description service.ui.typeThe service type for solo-enterprise-ui. Change it toClusterIPso that the gateway becomes the only way in. The chart otherwise defaults toLoadBalancer, which keeps the original plain-HTTP address reachable alongside your HTTPS domain, including the UI backend gRPC port and, under the auto identity provider, the provider itself on port 5556.Upgrade the management release with your values file.
helm upgrade -i solo-management \ oci://us-docker.pkg.dev/solo-public/solo-enterprise-helm/charts/management \ -n solo-enterprise \ --version 0.5.6 \ --values management.yamlVerify that the UI pod restarts and reports
Running.kubectl get pods -n solo-enterprise -l app=solo-enterprise-uiConfirm that the UI service no longer holds an external address.
kubectl get svc solo-enterprise-ui -n solo-enterpriseExample output, in which the type is
ClusterIPandEXTERNAL-IPis<none>:NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE solo-enterprise-ui ClusterIP 10.96.120.14 <none> 80/TCP,8091/TCP 12m
Verify the HTTPS endpoint
Send a request to your domain and confirm that the TLS handshake succeeds and the UI answers.
curl -sSI https://${UI_HOST}/Example output:
HTTP/2 200 content-type: text/html; charset=utf-8If your DNS record has not propagated yet, resolve the domain to the gateway address for this request only.
curl -sSI --resolve "${UI_HOST}:443:${GATEWAY_ADDRESS}" https://${UI_HOST}/If your cluster has no load balancer provider, so the gateway never received an external address, port-forward the gateway service instead and send the request to the forwarded port. Replace
solo-ui-https-istiowith the generated service name for your GatewayClass.kubectl port-forward -n solo-enterprise svc/solo-ui-https-istio 8443:443curl -sSI --resolve "${UI_HOST}:8443:127.0.0.1" https://${UI_HOST}:8443/Open
https://${UI_HOST}in your browser. Your identity provider prompts you to log in, and the Solo UI opens after you sign in.Confirm that the browser reports a valid certificate for your domain, and that no part of the page loads over plain HTTP.
Troubleshooting
If the gateway never becomes programmed, the browser warns about the certificate, sign-in fails, or the UI loads but its API calls fail, see Troubleshoot HTTPS access to the Solo UI.