VM (Embedded Cluster) - Airgapped Installation

Last modified on June 22, 2022

Follow this guide to install SwaggerHub On-Premise on a virtual machine that is not connected to the internet.

Prerequisites

  • This guide assumes you already have a VM that meets the system requirements, along with other resources required for SwaggerHub installation. See Requirements for VM Installation.

  • We recommend that you create a VM snapshot before installing SwaggerHub. In this case, you will be able to reset the VM to its original state if the installation becomes corrupt.

Download installation files

Before you proceed with the airgapped installation, contact Sales or your account manager and ask for a link to download the installation files. You will receive a link and password to access the download portal. The link is customer-specific and looks like this:

https://get.replicated.com/airgap/#/kots/swaggerhub/<UNIQUE-ID>

On a computer with Internet access:

  1. Log in to the download portal using the provided link and password.

  2. Select Embedded cluster on the left.

  3. Download the following files:

    • Your license
    • Latest kURL embedded install (swaggerhub.tar.gz, 5.3 GB)
    • Latest SwaggerHub Airgap bundle (SwaggerHub-<version>.airgap, 3 GB)
Download Portal

Click the image to enlarge it.

Install the Admin Console

First you need to install the KOTS Admin Console on the VM. The Admin Console will later be used to install and administer SwaggerHub On-Premise.

  1. Copy the swaggerhub.tar.gz file to an existing temporary directory on the VM. For example, to /var/tmp/swaggerhub.

    scp swaggerhub.tar.gz username@VM:/var/tmp/swaggerhub/
  2. Connect to the VM using SSH.

  3. Extract the contents of swaggerhub.tar.gz using tar.

    cd /var/tmp/swaggerhub
    
    tar xvzf swaggerhub.tar.gz
  4. Run the installation script:

    cat install.sh | sudo bash -s airgap

    The installation will take a few minutes to complete.

    Notes:

    • The "Host preflight failed" error caused by

      [FAIL] Filesystem Performance: Write latency is too high. p99 target < 10ms, actual:

      can be ignored, but consider using a faster disk.

    • The “SELinux is not installed: no configuration will be applied” error is expected on operating systems other than SELinux and can be ignored.

  5. After the installation is complete, note down the password generated for the Admin Console. This password will not be shown again.

    Admin Console password

    Click the image to enlarge it.

    Note: You can change or reset this password later, as explained in Resetting the Admin Console Password.

To configure kubectl reload your shell:

bash -l

By default kubectl is configured only for the user that ran the installation. If you wish to give another user access then SSH in as that user and run:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Next, browse to http://<VM>:8800 to set up SwaggerHub On-Premise using the Admin Console.

Configure HTTPS for the Admin Console (Optional)

By default, the Admin Console at http://<VM>:8800 uses a self-signed certificate, which will cause a browser warning to appear every time you access the Console. The initial page informs you about this. Click Continue to Setup.

Click the image to enlarge it.

Ignore the browser warning that appears.

Ignoring the 'Your connection is not private' warning in Chrome

Click the image to enlarge it.

On the next screen, you can upload your own SSL certificate to secure access to the Admin Console.

If you want to continue with the default (self-signed) certificate, click Skip & continue. You will be able to add a certificate later.

Click the image to enlarge it.

Note: The SSL certificate configured here is used only by the Admin Console and not by the main SwaggerHub application. The SSL termination support for the SwaggerHub application will be added in a future release.

Install and configure SwaggerHub

Upload the license

Proceed to log in to the Admin Console using the password that was previously generated for you.

Login prompt

On the next screen, you will be asked to upload your SwaggerHub license file (.yaml):

Upload your license file

Upload airgap bundle

On the Install in airgapped environment screen, upload the SwaggerHub-n.n.n.airgap file to the indicated drop zone.

After the bundle has been uploaded, the Admin Console will start to process the images and manifests. Images will be loaded, re-tagged, and pushed to your Docker container registry. Wait until this process is complete.

Pushing images

Click the image to enlarge it.

Configure SwaggerHub

On the next page, you can specify the configuration settings for SwaggerHub. The required settings for VM installations are:

  • DNS name for SwaggerHub - Specify a public or internal domain name that will be used to access SwaggerHub on your network. For example, swaggerhub.mycompany.com.

    This domain name must already be registered in your DNS service. You will need to point it to the VM’s IP address.

  • Database settings - Choose between internal or external databases. If using external databases, you need to specify the database connection strings.

    It will not possible to switch from internal to external databases or vice versa after the initial configuration.
  • SMTP settings - Specify an SMTP server for outgoing email.

Other settings are optional and depend on your environment and the desired integrations. Most settings can also be changed later. See SwaggerHub Configuration for a description of the available settings.

Click Continue at the bottom of the page to proceed.

Preflight checks

The next step checks your VM to ensure it meets the minimum requirements.

If all preflight checks are green, click Continue.

If one or more checks fail, do not proceed with the installation and contact Support.

Preflight checks

Click the image to enlarge it.

Status checks

While the installer allocates resources and deploys workloads, the application status on the dashboard will be Unavailable. If it stays in this state for more than 10 minutes, generate a support bundle and send it to the Support team.

Status showing Unavailable

Click the image to enlarge it.

Tip: To monitor the deployment progress, you can run

kubectl get pods 

a few times until all pods are Running or Completed:

NAME                                       READY   STATUS      RESTARTS   AGE
kotsadm-85d89dbc7-lwvq2                    1/1     Running     0          32m
kotsadm-minio-0                            1/1     Running     6          13d
kotsadm-postgres-0                         1/1     Running     5          13d
spec-converter-api-584cc46657-hbfmd        1/1     Running     0          9m55s
swagger-generator-v3-6fc55cb57d-brwg6      1/1     Running     0          9m55s
swaggerhub-accounts-api-8bb87565b-xthkv    1/1     Running     0          9m55s
swaggerhub-api-service-546b56b94b-6jxch    1/1     Running     0          9m55s
swaggerhub-configs-api-794847bd79-jnlhl    1/1     Running     0          9m55s
swaggerhub-custom-rules-5ccfd45599-d5bxc   1/1     Running     0          9m55s
swaggerhub-frontend-69b7c55595-n7vsj       1/1     Running     0          9m55s
swaggerhub-notifications-bbd5f8794-ggz99   1/1     Running     0          9m55s
swaggerhub-operator-758c997747-hnjt7       1/1     Running     0          9m55s
swaggerhub-pre-install-r9c2f               0/1     Completed   0          13d
swaggerhub-pre-upgrade-cg664               0/1     Completed   0          10m
swaggerhub-products-api-6dd446b654-7w7wn   1/1     Running     0          9m55s
swaggerhub-registry-api-886997fd7-8q8c7    1/1     Running     0          9m54s
swaggerhub-virtserver-79fdf54f98-wpmt8     1/1     Running     0          9m54s

Once the application has become ready, the status indicators on the Dashboard become green.

Status is 'ready'

Click the image to enlarge it.

Create admin user and default organization

Reload your shell:

bash -l

Run the following command to create an admin user and a default organization in SwaggerHub. Note the space in -- cmd.

Example:

kubectl exec -it deploy/swaggerhub-operator  -- cmd create-admin-user admin -p p@55w0rd devops@example.com myorg
  • The admin username must be between 3 to 20 characters and can only contain characters A..Z a..z 0..9 - _ .

  • The admin password must be at least 7 characters long with at least 1 lowercase letter and 1 number. If the password contains characters that have a special meaning in Bash (such as ! $ & and others), enclose the password in single quotes (like -p '$passw0rd') or escape the special characters.

Once done, open the SwaggerHub web application at http://VM_DNS_OR_IP and log in using the admin username and password. You should see the created organization in the sidebar:

Organization name in the SwaggerHub sidebar

Click the image to enlarge it.

What’s next

Now that SwaggerHub is up and running, you can:

Highlight search results