SWARM Migration Guide

GuardRails On-Premise SWARM to KOTS Migration Guide

Pre-requisites

• An existing Kubernetes cluster that meets these requirements
• A license for the KOTS installation
• Several DNS entries and SSL certs
• A backup of your production database

Footnotes:

1. Support from your cluster admin team is needed
2. Provided by GuardRails
3. Support from your DB admin team is needed

On domain names and SSL certificates

Nodeports In the SWARM setup the services were exposed via ports (e.g 1444, 1445), which is still possible for KOTS installations (via Nodeports), but that's not a common configuration on production Kubernetes clusters.

Ingress: When leveraging Ingress on your cluster, you will expose all services via unique domain names. If your old hostname was guardrails.example.com and you are going with Ingress, then you need to provision the following domain names:

• Temporary domain name for the new KOTS dashboard: e.g. guardrails-kots.example.com. This will be removed after a successful migration.
• A domain name for each of the GuardRails services, that will remain even after the successful migration, e.g:
  • guardrails-api.example.com
  • guardrails-probot.example.com
  • guardrails-minio.example.com

Migration Step Summary

	Before Migration (SWARM)	During Migration (K8s)	After Migration (K8s)
Provider App	Original App	Temporary App	Original App (1)
Hostnames	Original Hostname	Temporary Hostname	Original Hostname (2)
Database	Original Database	Embedded Database	Original Database

Footnotes:

1. The original app after the migration will in most cases have new hostnames for API and Probot. Unless services are exposed via Nodeports.
2. The original hostname will point to the new installation, and in most cases new hostnames are created for API and Probot. Unless services are exposed via Nodeports.

Part 1: Install KOTS

The steps for the installation are described here. Follow the steps and when you get to setup the provider integration, make sure that you create a new application that points to the temporary DNS name of the new Kubernetes-off-the-shelf (KOTS) installation. Note that depending on the type of service exposure option you have on your cluster, you will either expose services via ports aka Nodeports (similar to the SWARM setup before), or via domain names specific to each service aka Ingress. This new application/integration will supersede the one that is in use currently. In addition you can just start with using the embedded PostgreSQL database for the new setup.

Once the setup is complete you can install it into the same org, or a test org and enable a few repositories to make sure everything is working as expected.

The following tasks must work to consider this part to be successfully completed:

• Logging in to the GuardRails dashboard works
• Creating a new PR would show the guardrails/scan check/pipeline.
• Adding a sample vulnerability e.g var password = 'topsecret'; would result in a PR comment being created.

Part 2: Schedule a maintenance window for the switch

Set apart around 1-2 hours for a maintenance window. For some of that time, no events will be processed and also not stored in the queue for later processing.

Step 1: Scale down all services on the SWARM instances

Connect to your manager node and execute the following commands:

# Get the service names
sudo docker service ls
# Scale the services down
sudo docker service scale replXXXX_probot=0
sudo docker service scale replXXXX_worker=0
sudo docker service scale replXXXX_api=0
sudo docker service scale replXXXX_core-api=0

Optionally, you can go to the GuardRails Admin interface and enable the maintenance mode for the dashboard under "settings".

Step 2: Backup and switch the PostgreSQL DB

• Trigger a backup based on which external provider you are using to ensure you have the latest data and as a potential restoration point.
• Modify the database connection on your new KOTS GuardRails installation under the Config from Embedded to External and add your existing connection string from the current SWARM GuardRails installation.

The URI should look something like this:

postgresql://dbadmin%40guardrailsdb:p%[email protected]:5432/guardrails-onpremise

Do note that any special characters in the username and/or password must be URL encoded. E.g. @ becomes %40.

Restart the core-api pod to ensure that all the latest migrations are applied.

kubectl -n <namespace> delete pod <core-api-pod>

Step 3: Update the main domain name and the app settings

GitHub In the GuardRails admin interface we update the GitHub App details to reference the existing app. On the old GitHub App we change the domain names to include the new services (e.g probot and api), which before were the main domain name and different ports.

In a typical manged cluster with a load balancer the CNAME to the load balancer address can be used for the domain names. In a custom cluster deployment it depends on the configuration. Most commonly that means either putting multiple A records to the LB IPs or a CNAME to another record which is kept up to date with changing IPs for the LB.

Now we have to wait for the domain name to change to the new instance and then traffic will automatically come in and scans will start. You can monitor the Advanced tab of the GitHub app to see what events are coming in and when they start succeeding.

Part 3: Verify the new deployment

Once the migration is complete make sure that everything is working as expected.

The following tasks must work to consider this part to be successfully completed:

• Logging in to the GuardRails dashboard works
• Creating a new PR would show the guardrails/scan check/pipeline.
• Adding a sample vulnerability e.g filename: secrets.js content: var password = 'thisistopsecret'; would result in a PR comment being created.

Part 4: Terminating the old deployment

Once all other steps are completed, you can terminate the old deployment.