Minimum Requirements for Clustered Installation

Last modified on September 27, 2023

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 4.4 or 5.0
  • 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.

See Also

Online Installation Into Existing Kubernetes Cluster
Airgapped Installation Into Existing Kubernetes Cluster

Highlight search results