Minimum Requirements for Clustered Installation

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 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.

• 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 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

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

External MongoDB

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.

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

Ongoing access

Proxy server