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-scoped
cluster-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 16
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 theadmin
database.A user with built-in role: root, admin or readWriteAnyDatabase.
Alternatively, you can achieve this with a custom role. To do so, assign the user the following permissions:
serverStatus custom rule
readWrite and listCollections for the following databases:
swaggerhub_configs
swaggerhub_email
swaggerhub_operator
swaggerhub_standardization
swaggerhub_registry
swaggerhub_products
swaggerhub_plugins
serverStatus
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 | |
| 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.