Minimum Requirements for Clustered Installation

SwaggerHub On-Premise can be installed into an existing Kubernetes or OpenShift cluster. A standard SwaggerHub On-Premise cluster deployment consists of a minimum of 3 nodes behind a load balancer, plus external databases. Both online and airgapped installations are supported.

Resource provisioning varies with intended load and usage. While this guide outlines the recommended minimum cluster size, you should plan to add resources to suit the usage.

If you are going to do airgapped (offline) installation, please contact Sales or your account manager before you proceed with the installation. We will send you a link to the download portal where you can download the installation files.

General requirements

To install SwaggerHub On-Premise, you need the following things prepared in advance:

A SwaggerHub license file (.yaml) provided to you by SmartBear. To request a trial license, contact Sales or your account manager.
A Kubernetes or OpenShift cluster with a node pool allocated. See the sizing recommendations below.
(Optional.) External PostgreSQL and MongoDB databases running in the same region as the cluster nodes. See the details below.
A “jumpbox” Linux VM for installation and maintenance tasks, with network access to the Kubernetes cluster.
- The jumpbox should have at least 10 GB free disk space.
- You must have SSH or cloud shell access to the jumpbox, and either root login or sudo permissions on the jumpbox.
- kubectl (Kubernetes) or oc (OpenShift) installed. kubectl and Kubernetes versions should match to avoid errors.
- If enabling Enhanced Search see below for additional permissions that are required.
An SMTP server to send user invitations and other emails from SwaggerHub. Trial users can use a temporary SMTP server.
A DNS name that you will use to connect to SwaggerHub. For example, swaggerhub.yourcompany.com. This name must already be registered in your DNS service and must be routable on your network. You need to point this DNS name to the cluster’s ingress controller.

Enhanced Search requirements

Enhanced Search allows users to have a better experience when searching for documents with SwaggerHub. Before enabling Enhanced Search, two operating system kernel parameters need to be set to minimum values.

vm.max_map_count: set to a minimum value of 262144. For sample commands consult the Virtual memory page in the Elasticsearch documentation.
fs.file-max: set to a minimum value of 65536. For sample commands consult the File Descriptors page in the Elasticsearch documentation.

For example, you might add the following to the bottom of your /etc/sysctl.conf file:

vm.max_map_count=262144
fs.file-max=65536

These parameters must be correctly set before installation, so after adding them to /etc/sysctl.conf, you will either need to reboot or issue the sysctl --system command.

OpenShift cluster requirements

An OpenShift cluster with at least 1 worker node and an ingress controller. (See the sizing recommendations below.). OpenShift version must be 4.8, 4.9, or 4.10.
A Linux or macOS computer with the OpenShift CLI (oc) installed.
The user installing SwaggerHub must have a cluster-scopedcluster-admin role. A cluster-admin can assign this role to the installing user:
```
oc adm policy add-cluster-role-to-user cluster-admin USERNAME
```
Alternatively SwaggerHub can be installed with namespace-scoped access. This requires a user with full permissions on a single project:
```
oc adm policy add-role-to-user cluster-admin USERNAME -n PROJECT_NAME
```
Installing with namespace-scoped access limits some functionality. This is detailed in the installation guides.

Kubernetes cluster requirements

Kubernetes version 1.23, 1.24, or 1.25
An ingress controller for the cluster nodes.
Supported platforms: Amazon Elastic Kubernetes Service (EKS), Google Kubernetes Engine (GKE), Azure Kubernetes Service (AKS), Rancher Kubernetes Engine (RKE)
Not supported: Docker Desktop, Minikube, Microk8s
An existing storage class
Cluster RBAC (role-based access control):
- Existing namespace, and an RBAC binding that allows the installing user to create workloads, ClusterRoles, and ClusterRoleBindings.
- Cluster-admin permissions to create namespaces and assign RBAC roles across the cluster.
Node pools may be labeled to support node selectors.
Nodes should have the default amount of ephemeral storage (sometimes called Temp Storage).
If KOTS CLI and Admin Console are already installed in the cluster, their version must be 1.76.1 or later. To check the KOTS version, use kubectl kots version. If needed, upgrade KOTS to the latest version.

Node requirements

The cluster must have a minimum of 1 worker node. The minimum requirements for each node are:

Linux-based
4 vCPU
16 GB memory

This assumes that SwaggerHub is the only application running on these nodes. In addition a storage class is required for persistent volume storage. If using internal databases 100 GB is the minimum recommended size. If using external databases the minimum is 10 GB.

AWS EKS customers can use r5.xlarge instances.

Database requirements

SwaggerHub On-Premise can be configured with internal or external databases. Both databases have to be external or internal ones. Choosing a mix of internal and external databases is not supported.

If using external databases:

The databases must be provisioned in the same region where your SwaggerHub On-Premise cluster nodes are is located. The databases must be initially empty. SwaggerHub installation will create the necessary database tables.
You are responsible for backing up, maintaining, and securing external databases.
External databases are not included in SwaggerHub snapshots. You must back them up separately using your corresponding database backup tools. Both databases have to be backed up at the same time to avoid data inconsistency when a data restore is needed.

External PostgreSQL

PostgreSQL 11 to 14.6
Memory: 16 GB
A user that has the ability to create databases. You can create such a user as follows:
```
CREATE ROLE shubuser WITH CREATEDB LOGIN ENCRYPTED PASSWORD 'shubpassword'
```

External MongoDB

MongoDB 6 or 7
Memory: 16 GB
A user with the root privilege in the admin database.

Airgapped installation requirements

If your cluster is not connected to the Internet, you can install SwaggerHub On-Premise in airgapped (offline) mode.

Airgapped installation requires a private container registry accessible from the cluster and the jumpbox. Such as Docker Registry, Docker Hub, quay.io, Google Container Registry (GCR), JFrog Artifactory, Harbor, Sonatype Nexus, or any other registry that supports the standard Docker Registry HTTP API. The registry must support dynamically provisioning repositories on push.
If the registry is secured and requires authentication, you will need push and pull credentials for that registry.
- Push credentials will be used only once and will not be stored anywhere.
- Pull credentials will be automatically created as an imagePullSecret on all of the Admin Console pods.
You will also need to download the SwaggerHub install bundle (about 3 GB) and transfer it to the jumpbox manually.

Network connectivity

The following firewall configurations are required for inbound and outbound traffic in a SwaggerHub On-Premise cluster.

To check the connectivity from a node, you can connect to it over SSH and then either ping the target server, or telnet into the target server and port, or fetch the target URL using curl or wget. Note that ping will not work if ICMP is blocked on the target server or by your firewall.

Online installation and upgrades

Internet-connected clusters require outbound HTTPS Internet access (on TCP port 443) from each cluster node to the following domains in order to pull images, licenses, and product updates:

hub.docker.com
proxy.replicated.com
replicated.app
k8s.kurl.sh

Airgapped clusters do not need this.

Ongoing access

The following applies to both Internet-connected and airgapped clusters.

Outbound from each node - required:

Destination	Port	Purpose
MongoDB database/cluster	MongoDB port, for example, 27017	Database access
PostgreSQL database/cluster	DB port, for example, 5432	Database access
SMTP server	SMTP port	To send invitations and email notifications
API servers specified in your OpenAPI definitions		To use the “try it out” feature in API documentation
`$ref` URLs		To resolve references to external OpenAPI documents hosted outside of SwaggerHub

Outbound from each each node - optional (depends on the integrations and services used):

Destination	Port	Purpose
LDAP server	LDAP port	For single sign-on via Active Directory OpenLDAP
Backup storage		Backups created using Velero can be stored to a variety of storage providers. The configured storage must be accessible from each cluster node.
Webhook URLs		For outgoing webhooks
github.com api.github.com	443	GitHub.com integration
self-hosted GitHub Enterprise Server		GitHub Enterprise Server integration
gitlab.com	443	GitLab integration
self-hosted GitLab server		GitLab integration
bitbucket.org api.bitbucket.org	443	Bitbucket Cloud integration
self-hosted Bitbucket Server		Bitbucket Server integration
*.visualstudio.com	443	Azure DevOps Services integration
self-hosted Azure DevOps Server		Azure DevOps Server integration
apigateway.{region}.amazonaws.com	443	Amazon API Gateway integration
api.enterprise.apigee.com	443	Apigee Edge integration
self-hosted Apigee Edge server		Apigee Edge integration
*.management.azure-api.net	443	Azure API Management integration
apimanager.ussouth.apiconnect.cloud.ibm.com login.service.us.apiconnect.ibmcloud.com	443	IBM API Connect integration

Proxy server

SwaggerHub On-Premise lets you specify a proxy server in the Admin Console. This proxy server will be used for outgoing HTTP/S traffic from SwaggerHub services, such as “try it out” requests, integrations, and outgoing webhooks.

Note: This proxy server is not used for non-HTTP traffic (such as SMTP) and traffic from KOTS services.