VM (Embedded Cluster) - Online Installation

Last modified on June 22, 2022

This guide explains how to install SwaggerHub On-Premise 2.x on a virtual machine that can access 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.

Install the Admin Console

Run the following command on the VM to install the KOTS Admin Console. The Admin Console will later be used to install and administer SwaggerHub On-Premise.

curl -sSL https://k8s.kurl.sh/swaggerhub | sudo bash

Or if you want to capture the installation log to a file:

curl -sSL https://k8s.kurl.sh/swaggerhub | sudo bash 2>&1 | tee install.log
Note: The log will contain some generated passwords, which you may want to edit out later. Search for "password" to find them.

The installation will take a few minutes, depending on your internet connection.

After the installation is complete, note down the password generated for the Admin Console. This password will not be shown again (but you will be able to change or reset it later).

Admin Console password

Click the image to enlarge it.

Notes:

  • The Admin Console IP address displayed in the installation output (shown in the image above) may not be actually accessible. Use the VM’s public IP address to access the Admin Console and the SwaggerHub application.

  • Even though the installation output mentions node join commands, SwaggerHub On-Premise VM installations do not currently support adding extra nodes.

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 Public IP>:8800 to complete the setup using the Admin Console web interface.

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

If your SwaggerHub license supports airgapped (offline) installations, you will see an option to proceed with the airgapped setup. Since you are installing SwaggerHub in online mode, click Download the application from the internet.

Skipping airgapped installation

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