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. pay-attention.gif 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.29, 1.30 or 1.31

  • 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

  • An admin user or a user with database creation rights (CREATEDB). You can create such a user as follows:

    CREATE ROLE shubuser WITH CREATEDB LOGIN ENCRYPTED PASSWORD 'shubpassword'

  • In the case of a user with database creation rights: before installing SwaggerHub, connect to PostgreSQL with the user's credentials and create the swaggerhub_accounts database. Note that it should be provided in the connection string in Admin Console (for example, postgresql://user1:[email protected]:5432/swaggerhub_accounts).

External MongoDB

  • MongoDB 6 or 7

  • Memory: 16 GB

  • A user with the root privilege in the admin 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

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

In this section:
© 2024
Publication date: