Airgapped Installation Into Existing Kubernetes Cluster

Last modified on June 22, 2022

If your Kubernetes cluster is not connected to the Internet, you can install SwaggerHub On-Premise in airgapped (offline) mode.

Prerequisites

This guide assumes a Kubernetes cluster has been prepared as specified in the Minimum Requirements.

This guide also assumes a private Docker container registry in the network as specified in the Airgapped Installation Requirements.

All commands assume a jumpbox with connectivity to the cluster, and kubectl installed.

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 Bring my own cluster on the left.

  3. Download the following files:

    • Your license (.yaml)
    • Latest Kots CLI (kots_linux_amd64.tar.gz) - if not already installed

      Note:

      This version of KOTS CLI is for Linux and WSL. If you are running kubectl on macOS, you can download the macOS version of KOTS CLI from GitHub:

      kots_darwin_all.tar.gz

    • Latest Kots Admin Console Airgap bundle (kotsadm.tar.gz)
    • Latest SwaggerHub Airgap bundle (SwaggerHub-<version>.airgap)

    The total size of the files is about 3 GB.

Download Portal

Click the image to enlarge it.

Copy these files to a temporary directory on your jumpbox.

Install KOTS to kubectl

Here and in the rest of this guide, the commands are to be run on the jumpbox.

SwaggerHub 2.x uses KOTS to manage the installation, licensing, and updates. KOTS is a plugin for kubectl. SwaggerHub requires KOTS 1.68.0 or later.

First, check if KOTS is already installed:

$ kubectl kots version

If you see Replicated KOTS 1.x.x and the version is:

If you see the “unknown command” error, install KOTS:

  1. Unpack the kots_<platform>.tar.gz file. In this example, we unpack it to the kots-cli directory:

    mkdir kots-cli
    tar -zxvf kots_linux_amd64.tar.gz -C kots-cli
  2. Rename the kots executable to kubectl-kots:

    cd kots-cli
    mv kots kubectl-kots
  3. Copy the renamed kubectl-kots to anywhere on the PATH, for example, to /usr/local/bin/:

    sudo mv kubectl-kots /usr/local/bin/
  4. Verify successful installation:

    kubectl kots version

Push images

Extract KOTS Admin Console container images and push them into your private Docker container registry:

kubectl kots admin-console push-images ./kotsadm.tar.gz private.registry.host/swaggerhub \
--registry-username rw-username \
--registry-password rw-password

Replace private.registry.host with your registry host and port (if used). Examples: myregistry.example.com, 10.100.20.24:5000.

Registry credentials (rw-username and rw-password in the command above) must have push access. These credentials will not be stored anywhere or reused later.

Install Admin Console

The next step is to install the Admin Console using images pushed in the previous step.

Registry credentials provided in this step (ro-username and ro-password in the command below) only need to have read access. They will be stored in a Secret in the same namespace where Admin Console will be installed. These credentials will be used to pull the images and will be automatically created as an imagePullSecret on all of the Admin Console pods.

kubectl kots install swaggerhub \
--kotsadm-namespace swaggerhub \
--kotsadm-registry private.registry.host \
--registry-username ro-username \
--registry-password ro-password

Once this has completed, the KOTS will create a port forward to the Admin Console on port 8800. The Admin Console is exposed internally in the cluster and can only be accessed using a port forward. The port forward will be active as long as the CLI is running. Pressing Ctrl + C will end the port forward.

  • Press Ctrl+C to exit
• Go to http://localhost:8800 to access the Admin Console

Once this message is displayed, visit http://localhost:8800 to set up SwaggerHub On-Premise using the Admin Console.

Upload the license

Browse to http://localhost:8800 and log in to the Admin Console using the administrator password that you set during deployment.

Login prompt

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

Upload your license file

Click the image to enlarge it.

Upload airgap bundle

On the Install in airgapped environment screen, you will be prompted for your Docker container registry details:

  • Hostname - The registry host in the format host[:port]. Examples: myregistry.example.com, 10.100.20.24:5000.

  • Username and Password - Registry credentials with push access.

  • Registry Namespace - The namespace within the registry where SwaggerHub container images will be pushed. For example, swaggerhub.

Install in airgapped environment

Click the image to enlarge it.

At the bottom of the screen, upload the SwaggerHub-n.n.n.airgap file to the indicated drop zone and click Upload airgap bundle.

Click the image to enlarge it.

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

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

Configuration page

Click the image to enlarge it.

Preflight checks

The next step checks your Kubernetes cluster 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 passed

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 -n swaggerhub

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

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 -n swaggerhub -- 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://DNS_NAME 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