Routing and Ingress Configuration

Swagger Studio On-Premise uses the swaggerhub-ingress Ingress resource to route external traffic to its internal services, directing each request to a backend service based on its hostname and path. The installer creates and manages this resource after you provide the DNS name and, optionally, an Ingress class in the Admin Console, as described in Swagger Studio Configuration.

If you route traffic with a custom Ingress controller, an external load balancer, or a separate API gateway instead of the built-in Ingress, configure the paths and hosts described on this page to ensure that all Swagger Studio components continue to work as expected.

Tip

Note: To view the routing rules generated by the installer, run the following command:

kubectl get ingress -n <SWAGGERHUB_NAMESPACE> swaggerhub-ingress -o yaml

General Ingress configuration

The following paths are required for core functionality. Several of them route to the haproxy service, which rewrites the path before proxying the request to the underlying API services.

Path	Path type	Service	Port	Description
`/api/`	`Prefix`	`haproxy`	`80`	API requests, proxied to the Swagger Studio API service.
`/virts/`	`Prefix`	`haproxy`	`80`	VirtServer requests.
`/v1/`	`Prefix`	`haproxy`	`80`	RegistryAPI requests.
`/socket.io`	`Prefix`	`swaggerhub-notifications`	`80`	WebSocket connections for real-time notifications.
`/`	`Prefix`	`swaggerhub-frontend`	`80`	Web frontend application.

The / path acts as a catch-all. Ensure it is evaluated last, following more specific prefixes.

Portal Ingress configuration

If your organization uses the Swagger Portal feature, configure the following host-based rules. Swagger Portal uses a wildcard host to route tenant subdomains. Replace DOMAIN with your Swagger Studio DNS name.

Host	Path	Path type	Service	Port	Description
`portal.DOMAIN`	`/`	`Prefix`	`swaggerhub-portal-frontend`	`80`	Swagger Portal frontend.
`api.portal.DOMAIN`	`/`	`Prefix`	`swaggerhub-portal-api-external`	`80`	Swagger Portal backend API.
`*.portal.DOMAIN`	`/`	`Prefix`	`swaggerhub-portal-frontend`	`80`	Tenant subdomain routing for the Swagger Portal frontend.

Implementing a custom routing solution

If you use your own routing solution or a different Ingress controller, make sure that it meets the following requirements:

Path types – Use Prefix matching, and evaluate the specific prefixes before the / catch-all.
Service names and ports – Use the same service names and ports listed above. Do not rename or re-port the backend services.
Hostnames – Match the hostnames used by Swagger Studio, including the Portal hosts if the Portal is enabled.
WebSockets – Allow WebSocket upgrade headers to pass through to /socket.io.
SSL/TLS – If your solution terminates SSL/TLS or performs load balancing, configure it as described in the next section.

Service type compatibility in installations with HELM

In a Helm-based installation, you can configure each service that backs the paths and hosts above as either ClusterIP or NodePort, depending on your deployment's configuration:

ClusterIP - The default service type, reachable only within the cluster. Your Ingress controller or reverse proxy must run inside the cluster, or you must use a mechanism such as port forwarding or a cloud load balancer that can reach the cluster network.
NodePort - A service type that is reachable on a static port on each node's IP address. An external load balancer or proxy outside the cluster can target any node IP address at the assigned NodePort.

Regardless of the service type, reference services in your routing rules by the service names and ports listed in the tables above - not by node IP addresses or NodePort numbers, which might change. If you use NodePort, ensure your external proxy or load balancer targets the NodePort number assigned to each service, and configure the health checks accordingly.

In this section: