Airgapped Installation Into Existing OpenShift Cluster

This guide assumes a OpenShift 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.

OpenShift CLI must be installed. The kubectl binary included with the OpenShift CLI must also be installed.

By default the installer assumes that your user has the cluster-admin role at the cluster level. Alternatively, you can install with namespace-scoped access if your user only has cluster-admin access on a single project. Be aware that installing without cluster-scoped access limits some functionality:

This install guide includes the commands needed to install with namespace-scoped access.

On a computer with the OpenShift CLI and cluster access, log in to your cluster:

oc login -u USERNAME

If you do not already have a project for SwaggerHub in OpenShift, create it. If you do not have permissions to create a project you may need to ask your administrator to complete this step:

oc new-project swaggerhub

Or, if you have created a project previously, switch to it:

oc project PROJECT_NAME

In this guide we will assume that the project name is swaggerhub.

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:

Copy these files to a temporary directory on your jumpbox.

SwaggerHub 2.x uses KOTS to manage the installation, licensing, and updates. KOTS is a plugin for kubectl. SwaggerHub requires KOTS 1.76.1 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:

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.

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

Registry credentials provided in this step (rw-username and rw-password in the command below) must have push access.

kotsadm-registry is the registry host in the format host[:port]. Examples: myregistry.example.com, 10.100.20.24:5000.

kotsadm-namespace is the namespace within the registry where SwaggerHub container images will be pushed. For example, swaggerhub.

To install with cluster-scoped access, run this command:

kubectl kots install swaggerhub \
  --namespace swaggerhub \
  --license-file ./license.yaml \
  --airgap-bundle /path/to/application.airgap \
  --kotsadm-namespace swaggerhub \
  --kotsadm-registry private.registry.host \
  --registry-username rw-username \
  --registry-password rw-password

Alternatively, to install with namespace-scoped access, run this command:

kubectl kots install swaggerhub \
  --namespace swaggerhub \
  --license-file ./license.yaml \
  --airgap-bundle /path/to/application.airgap \
  --kotsadm-namespace swaggerhub \
  --kotsadm-registry private.registry.host \
  --registry-username rw-username \
  --registry-password rw-password \
  --use-minimal-rbac \
  --skip-rbac-check

With namespace-scoped installs you may see some error messages like "Failed to get OpenShift server version". This is a known issue and the messages can be safely ignored.

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.

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

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.

The next step checks your OpenShift 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.

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.

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.

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 [email protected] myorg

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:

Now that SwaggerHub is up and running, you can: