Overview

This guide sets up the DvSum Gateway in High Availability (HA) mode on multiple VMs. One installer, setup.sh, run on the first VM, configures all three VMs and takes about 15–30 minutes. If any single VM, pod or job fails, the Gateway keeps running.

1. Prerequisites

1.1 Virtual machines

Provision 3 VMs (recommended) of the same size, all on the same private network.

Oracle Linux: the installer opens only the cluster ports below in the firewall and sets SELinux rules for the Gateway data folder. If your security policy does not allow this, contact DvSum before installing.

Command to verify Time Sync

timedatectl status

1.2 Ports to whitelist

Allow these ports between all 3 VMs, in both directions (security group / firewall).

Inbound to the Gateway: allow the Gateway port from your client networks (and your load balancer, if used). Outbound to data sources: allow each VM to reach every data source on its own port (for example 1433, 1521, 5432, 443).

1.3 Endpoints to whitelist

Outbound HTTPS (443) only — no inbound rule is needed. The installer checks these before asking any question.

Quick check, from each VM:

curl -sS -o /dev/null -w '%{http_code}\n' https://apis.dvsum.ai
curl -sS -o /dev/null -w '%{http_code}\n' https://ecr.us-west-2.amazonaws.com
curl -sS -o /dev/null -w '%{http_code}\n' https://releases-gateway.dvsum.ai

Any HTTP status code (200, 403, 404) means the address is reachable; a timeout means the firewall or proxy must be fixed first. 

1.4 Check Connectivity Between the VMs (from VM 1)

nc -zv <VM2-IP> 22
nc -zv <VM3-IP> 22

ssh -i /path/to/key.pem <ssh-user>@<VM2-IP> 'sudo -n true && echo sudo-ok'
ssh -i /path/to/key.pem <ssh-user>@<VM3-IP> 'sudo -n true && echo sudo-ok'

The cluster ports (6443, 10250, 2379–2380, 8472) won't respond yet, because nothing is listening on them until the installation. Confirm with the network team that the rules in Section 3.4 are in place.

1.5 Decide before you install

1.6 What happens when something fails

Why 3 VMs? The cluster database (etcd) and Redis Sentinel both need a majority to keep working. With 3 VMs the cluster survives losing any one; with 2 VMs, losing either one stops automatic failover.

2. Download the Installer

The installer package is downloaded from your DvSum account. You only need it on VM 1; the installer copies what it needs to VM 2 and VM 3.

1. Sign in to DvSum and go to Administration → Account.
2. Open the Gateway tab.
3. In the Stand-alone Gateway section, click Download (right side) and choose High Availability.
4. Save the file (for example dvsum-gateway.zip).

Choose High Availability, not Stand-Alone. The Stand-Alone installer sets up a single-node Gateway without clustering.

Copy the package to VM 1 and unpack it

scp dvsum-gateway.zip <user>@<VM1-IP>:~
ssh <user>@<VM1-IP>

unzip dvsum-gateway.zip -d ~/dvsum-gateway && cd ~/dvsum-gateway

chmod +x setup.sh dvsum-gateway.sh

The folder contains setup.sh (installer), dvsum-gateway.sh (management tool), configuration.properties (application settings) and nodes.properties (optional VM connection details).

3. Prepare the VMs

Do these checks on all 3 VMs unless noted.

3.1 Check outbound access

Run the three curl checks from Section 1.3 on each VM.

curl -sS -o /dev/null -w '%{http_code}\n' https://apis.dvsum.ai
curl -sS -o /dev/null -w '%{http_code}\n' https://ecr.us-west-2.amazonaws.com
curl -sS -o /dev/null -w '%{http_code}\n' https://releases-gateway.dvsum.ai

Any HTTP status code (200, 403, 404) means the address is reachable; a timeout means the firewall or proxy must be fixed first. 

3.2 Check SSH from VM 1 to VM 2 and VM 3 (VM 1 only)

nc -zv <VM2-IP> 22
nc -zv <VM3-IP> 22

ssh -i /path/to/key.pem <ssh-user>@<VM2-IP> 'sudo -n true && echo sudo-ok'
ssh -i /path/to/key.pem <ssh-user>@<VM3-IP> 'sudo -n true && echo sudo-ok'

You should see sudo-ok for both. If sudo asks for a password, passwordless sudo is not set up for that user; fix this first because the automatic join depends on it. The cluster ports (6443, 2379–2380, 10250, 8472) will not respond yet because nothing listens on them until the install. Ask your network team to confirm those rules are in place.

4. First-Time Installation (VM 1)

Run every step in this section on VM 1, from the ~/dvsum-gateway folder. The installer is interactive: it prints a heading (--- Step name ---), asks a question if needed, and shows [setup] progress lines. Press Enter to accept a default shown in brackets.

4.1 (Optional) Pre-fill VM 2 and VM 3 details

To skip the SSH questions in Step 14, fill in nodes.properties before you start. JOIN_VM_1 and JOIN_VM_2 mean the first and second additional VMs (VM 2 and VM 3). If you leave this file as it is, the installer asks for the details and saves your answers here for next time.

Treat nodes.properties like an SSH key if it holds a password: chmod 600 nodes.properties.

4.2 Start the installer

./setup.sh

Step 1 — System requirements

The installer compares this VM to the recommended 8 vCPU / 32 GB RAM. If the VM is smaller, it warns you and asks whether to continue.

On screen

--- System Requirements ---

Recommended minimum: 8 vCPUs, 32 GB RAM

Detected on this machine: 8 vCPU(s), 32 GB RAM

(only if below the minimum)

Continue anyway? [y/n]:

Step 2 — Connectivity check

The installer tests the DvSum API and the private container registry (Section 2.3), then lists the packages this install needs (private ECR images, K3s, Helm, KEDA, MetalLB, Redis). All of K3s, Helm, KEDA, MetalLB and Redis are downloaded through apis.dvsum.ai.

On screen

--- Connectivity Check ---

  [OK]   DvSum API (https://apis.dvsum.ai)

  [OK]   Private ECR (gateway images) (https://ecr.us-west-2.amazonaws.com)

[setup] ... All required endpoints reachable.

Step 3 — Operating-system preparation (automatic)

No questions are asked unless an automatic fix fails. The installer detects the Linux distribution and then:

If an automatic fix fails, the installer prints the exact commands to run by hand and asks Applied already, or continue anyway? [y/n]. Run the commands, then answer y (or answer n, run them, and start ./setup.sh again).

Step 4 — This VM's role

Every VM runs the same script. This question tells the installer whether this VM starts a new cluster or joins an existing one.

On screen

--- This VM's Role ---

1) First VM — initializes a new install (single-node, or the first VM of a multi-node cluster)

2) Additional VM — join a cluster that's already been initialized on another VM

Choice [1]:

Step 5 — Node count

How many VMs the Gateway will run on, counting this one.

On screen

--- Deployment Type ---

How many nodes will this gateway run on?

  Enter 1 for a single-node install (this machine only), or

  enter any integer >= 2 for multi-node (this machine + that many worker VMs).

Node count : 3

Step 6 — Environment

No question is asked. The installer uses production by default and prints Environment: prod, the DvSum API address it will use, and the private registry it will pull images from.

Step 7 — DvSum API key

Paste the API key from your DvSum account. The installer then verifies it and confirms the private registry access that downloads the Gateway images.

On screen

--- DvSum API Key ---

Paste your DvSum API key []:

--- Verifying DvSum Connectivity ---

[setup] ... Connected to DvSum successfully — API key verified.

--- Private ECR Access ---

[setup] ... Private ECR access confirmed ...

Step 8 — Gateway port

The port clients use to reach the Gateway on every VM.

On screen

--- Gateway Port ---

Gateway port [8183]:

Press Enter for the default 8183. If you change it, your firewall rules (Section 2.2), load balancer and DvSum registration must use the same port.

Step 9 — Database connection limit

The maximum number of simultaneous connections the Gateway opens to each data source. This limit is shared across all Gateway pods, regardless of how many VMs or workers run.

On screen

--- Database Connection Limit ---

Maximum concurrent database connections allowed per data source, shared

across all gateway pods regardless of how many VMs or worker pods exist.

Max database connections per source [20]:

Press Enter for 20, or type a whole number greater than 0 if your databases allow fewer or more.

Step 10 — Data retention period

How long the Gateway keeps scan output, data-quality analysis and workflow files before cleaning them up. The cleanup runs on the Connector every 3 hours.

On screen

--- Data Retention Period ---

Data retention period (e.g. 30d, 12h) [30d]:

Enter a number followed by d (days) or h (hours), for example 30d or 12h. Any other format is rejected and asked again.

Step 11 — Gateway access method

Appears because you chose more than one VM. It decides how clients reach the Gateway (see Section 2.4).

On screen

--- Gateway Access Method (multi-VM) ---

1. Floating IP (MetalLB) — ONE address, network-layer failover.

2. Each VM's own IP (NodePort) — Each VM has separate address (Requires Reverse Proxy setup)

Set up a floating IP (option 1)? [n]:

A floating IP works only for clients on the same network segment (Layer 2) as the VMs. Firewall rules cannot make it reachable from other subnets.

Step 12 — Update mode

How the Gateway gets new versions.

On screen

--- Update Mode ---

  1. Manual — you control exactly when updates happen, by re-running ./setup.sh (Recommended)

  2. Automatic — dvsum-updater checks for new versions every 1 hour and

     applies them with zero downtime, no action needed from you

Choice [1]:

Step 13 — Kubernetes (K3s) and Helm (automatic)

No questions. The installer installs K3s on VM 1 as the first control-plane node with an embedded etcd database, sets container image downloads to go through apis.dvsum.ai, restarts K3s once to apply settings, and installs Helm. Expect this to take a few minutes.

On screen

--- Kubernetes (K3s) ---

[setup] ... Installing K3s (embedded-etcd mode, --cluster-init)...

[setup] ... Downloading k3s binary from https://apis.dvsum.ai/gateway-mirror/k3s/k3s

[setup] ... Waiting for K3s to become ready...

[setup] ... Waiting for K3s to come back up after restart...

The installer adds an export KUBECONFIG=... line to your ~/.bashrc. After the install, open a new shell (or run source ~/.bashrc) so kubectl works with the right settings.

Step 14 — Join VM 2 and VM 3

The installer now needs the other VMs to join the cluster. You can let it do this over SSH (automatic) or do it by hand (manual).

Step 14a — Automatic join over SSH (recommended)

On screen

--- Multi-Node Join ---

--- Auto-Join via SSH (optional) ---

SSH into each of the 2 additional VM(s), copy this script over, and join it

automatically 

Auto-configure the other 2 VM(s) via SSH now? [y/n]:

Then, for each additional VM, a heading --- Joiner VM n - <IP> --- is shown. If you filled in nodes.properties (Section 1.1), the details are used and no questions are asked. Otherwise:

Your answers are saved to nodes.properties and the state file so you are not asked again. For each VM the installer then:

1. Checks SSH access and passwordless sudo.
2. Copies setup.sh to ~/dvsum-gateway/ on that VM.
3. Runs it there and streams the output live. Every line is prefixed [Joiner VM n - <IP>] so you can tell it apart from VM 1's own output, between the banners Remote output — Joiner VM n and Back on this VM.
4. Joins the VM as another control-plane node.

When both VMs are done you see Auto-join summary: 2/2 VM(s) joined automatically, 0 failed. If a VM fails (SSH refused, sudo needs a password, copy failed), that VM prints its own manual instructions and the installer carries on with the others; you can join the failed VM by hand (Step 14b) while the installer waits.

Step 14b — Manual join

Use this if automatic join is not allowed, or after choosing n above, VM 1 shows its Gateway IP and a Node token, and asks you to confirm the ports are open (Confirm these ports are open between all VMs [y/n]).

The node token is like a password: anyone who has it can join a machine to your cluster. Do not share or store it.

On each additional VM, one at a time:

1. Copy setup.sh (or the full package) to the VM and make it executable: chmod +x setup.sh.
2. Run ./setup.sh 
3. At This VM's Role, choose 2) Additional VM.
4. Enter the Gateway IP and Node token shown on VM 1.
5. At Confirm these ports are open [y/n], answer y once the firewall rules are in place.
6. Wait for This VM has joined the cluster. — nothing else is installed on this VM; the certificate, API key and Gateway are managed from VM 1.

On the joining VM add these entries  

Step 15 — Waiting for all nodes (automatic)

VM 1 waits until all nodes have joined, checking every 60 seconds.

On screen

[setup] ... Waiting for 3 total node(s) to join. Checking every 60s, or press Enter anytime to check immediately.

2/3 node(s) joined so far. [Enter] to check again now, or type 'skip' ...

[setup] ... All 3 nodes have joined.

[setup] ... Node labels applied.

Step 16 — Namespace, API key and registry access (automatic)

The installer creates the dvsum-gateway namespace, stores your API key as a Kubernetes secret, then asks DvSum Cloud for a private-registry token and stores it so the pods can pull the Gateway images. It also applies the settings in configuration.properties (thread pools, logging and so on)

Step 17 — SSL certificate

The Gateway serves HTTPS only. The certificate is stored once in the cluster, so all VMs share it. All four options are explained below.

Choose how to provide the certificate:

On screen

--- SSL Certificate Configuration ---

1. Generate a new CSR for a CA-signed (or self-signed) certificate

2. Add your certificate to an existing keystore

3. Import an existing certificate + private key into a new keystore

4. Use an existing keystore as-is

Choice [1]:

Option 1 — Generate a CSR (recommended)

Part A: certificate details. Only the Common Name is required; press Enter to skip the others.

Part B: self-signed or CA-signed. The installer generates a self-signed certificate first and asks what to do with it.

On screen

A self-signed certificate has been generated for: CN=gateway.yourcompany.com

  1. Use it as-is (self-signed) — fastest, fine for local/test installs

  2. Get it CA-signed instead — generates a CSR to submit to your CA

Choice [1]:

Part C: send the CSR to your CA. Submit the .csr file to your certificate authority. It returns a server (leaf) certificate. The installer then asks:

On screen

Path to the signed SERVER certificate file (or 'later' to pause):

Part D: the CA chain. Provide the certificate authority chain so clients can trust the Gateway.

On screen

Path to root certificate file — a single cert or a full chain bundle (required):

Path to intermediate certificate file, if separate from the above (optional — press Enter to skip):

• Server certificate (required): the server certificate file from the CA.
• Root certificate (required): the file from your CA. A bundle that contains the root and intermediate together (common with CAs such as GoDaddy) is fine here.
• Intermediate certificate (optional): only if your CA gave it as a separate file. Press Enter to skip.

Option 2 — Add a certificate to an existing keystore

On screen

Path to existing keystore []:

Keystore password []:

Path to server certificate []:

Path to root certificate file ... (required):

Path to intermediate certificate file ... (optional):

If a pending keystore from an earlier CSR run exists, it is pre-filled (Found a pending keystore from an earlier CSR run). Otherwise the currently deployed keystore is offered. Enter the keystore password, the signed server certificate, then the CA chain as in Part D.

Option 3 — Import an existing certificate and private key

On screen

Path to certificate file []:

Path to private key file []:

Domain name []:

New keystore password []:

Enter the certificate file, its private key file, the domain name, and a new keystore password (min 6 characters). The installer builds the keystore for you, then asks for the CA chain as in Part D.

Option 4 — Use an existing keystore as-is

On screen

Path to existing keystore []:

Keystore password []:

Enter the path to a Java keystore (.jks) that already contains the signed certificate and chain, and its password.

Validation (all options)

The installer validates the keystore (Validating new keystore...) and stops if the certificate has already expired. On success it shows the validity dates and Certificate Secret applied. Working files stay in ~/dvsum-gateway/gateway-certs-data/ on VM 1 (pending/, issued/, backups/). Back this folder up.

Step 18 — Deployment (automatic)

No more questions. The installer:

1. Checks releases-gateway.dvsum.ai for the current published version and prints Installing published version: <version>. (If it cannot, it asks you for an image tag.)
2. Installs KEDA (autoscaling) and creates the Redis password secret.
3. Deploys the Gateway: Redis + Sentinel (one per VM), a Connector on every VM, interactive workers and batch-job scaling, and lists the resources it created.
4. Waits up to 5 minutes for the Connector, workers and Redis to be ready.

It ends with a summary. Note the Gateway address, the version and the update mode:

On screen

==================================================================

 Gateway live at (this VM): https://<VM1-IP>:8183

 No floating IP configured — every VM in this cluster answers

 independently at its own IP:8183. ... 

 Version deployed: <version>

 API key: <your key>

 Environment: prod

 Deployment type: multi-node (3 nodes)

 Update mode: Manual (re-run ./setup.sh)

 Manage with: ./dvsum-gateway.sh status | logs | restart | version

4.3 If the installer stops

Fix the cause and run ./setup.sh again; answers are remembered and finished steps are skipped. Common stops: a firewall blocking an endpoint (Step 2), an SSH problem on a joining VM (Step 14), or a CA that has not signed the certificate yet (answer later, Step 17).

4.4 Offline (air-gap) installation

Use this only if the VMs cannot reach the internet. Ask DvSum for the offline package. It adds an image bundle dvsum-gateway-images-<version>.tar and VERSION.txt next to setup.sh. Run:

./setup.sh --air-gap

On screen

--- Air-Gap Mode ---

Bundled gateway version found: <version>

Use these bundled images for this install? [y/n]:

Answer y to import the bundled images (--- Air-Gap Image Import ---, a few minutes). Everything else is the same as the online install. The installer also switches to air-gap mode by itself if the container registry is unreachable. If either file is missing, it stops and tells you which one.

5. Register the Gateway and Go Live

1. DNS. Create a DNS record for the certificate's domain name. 
   1. Floating IP: point it to the floating IP. 
   2. Load balancer: point it to the load balancer, or create 3 records (one per VM IP).
2. Load balancer (if used). Add all 3 VM IPs on the Gateway port and set the health check to https://<vm-ip>:8183/health/ready.
3. DvSum portal. In Administration → Account → Gateway, register https://<gateway-dns-name>:8183. Do not register a single VM's IP, or failover will stop working.
4. Confirm the Gateway shows as connected in DvSum.

6. Verify the Installation

On VM 1, open a new shell (or run source ~/.bashrc), then:

6.1 Check the cluster

kubectl get nodes -o wide

Expected: 3 nodes, all Ready, each with the roles control-plane,etcd.

6.2 Check the Gateway

./dvsum-gateway.sh status

kubectl get pods -n dvsum-gateway -o wide

./dvsum-gateway.sh status should also show the connection to DvSum as connected, all probes passing, and the certificate expiry date.

6.3 Functional test

• In DvSum, run Test connection on one or more data sources that use this Gateway.
• Run a small scan or job and confirm it completes.
• Call the Gateway through the registered name: curl -k https://<gateway-address>:8183/health/ready.

6.4 Failover tests (before go-live)

7. Ongoing Operations

Run all commands on VM 1, from ~/dvsum-gateway.

7.1 Monitoring Commands

7.2 The installer menu on an existing install

When you run ./setup.sh on a VM that already has the Gateway, it detects the install, loads the current settings, and shows this menu:

On screen

What would you like to do?

  1. Update to a newer gateway version (image only, settings unchanged)

  2. Change configuration (port, certs, node placement, update mode, etc.)

  3. Rotate certificates only

  4. Add another VM to this cluster

  5. Apply configuration.properties changes

  6. Deregister a VM from this cluster

Choice [1]:

7.3 Update to a newer Gateway version

Updates are rolled out one VM at a time with no downtime. Run ./setup.sh --update (or choose option 1 in the menu). The installer shows the version currently deployed, then asks where the new version comes from.

On screen

[setup] ... Currently deployed image tag: <current-version> (gateway-releases.json: https://releases-gateway.dvsum.ai/gateway-releases.json)

  1. Update to the latest published version (default)

  2. Update to a specific version

  3. Update from a downloaded air-gap image bundle

Choice [1]:

What the installer does next

1. Downgrade check. If the chosen version is older than the deployed one, it warns that this is a downgrade or rollback and asks Continue anyway? [y/n].
2. Images to be pulled. Lists the three images (gateway, gateway-updater, gateway-python-service) and the version.
3. Proposed infra changes. Shows what will change in the cluster ([updated], [added], [removed] resources). If anything besides the image version changes, it asks Apply these changes? [y/n]; y to proceed, n to cancel with nothing changed. If only the image version changes, it continues without asking.
4. Registry token. Gets a fresh private-registry token from DvSum Cloud using the stored API key, and refuses to continue if it cannot, so pods are never left unable to pull images.
5. Upgrade. Applies the new version, prints Post-upgrade status, then restarts the Connector, workers (and updater) in turn so every pod runs the new version, and waits for the Connector rollout (up to 3 minutes).

If you are already on that version

The installer says Already on <version>, shows the images, and checks whether the local chart differs from what is deployed. If nothing differs it asks:

On screen

[setup] ... Local chart matches what's deployed — nothing to do.

Redeploy anyway regardless (re-pull image, restart pods)? [y/n]:

• n — leave everything as it is.
• y — re-pull the image and restart the pods (a forced redeploy of the same version).

Choose Manual update mode (Step 12) to control update timing. With Automatic, the updater applies new versions hourly; you can still run ./setup.sh --update manually at any time.

7.4 Change configuration

Choose option 2 in the menu to change settings after install. The installer asks the same questions as the first install (Gateway port, database connection limit, retention period, access method / floating IP, update mode, API key, certificate), but each prompt is pre-filled with the current value; press Enter to keep it.

At the end it shows Proposed infra changes (not yet applied) and asks Apply these changes? [y/n]. After y it upgrades the release and restarts the pods one by one so changes take effect.

7.5 Apply configuration.properties changes

configuration.properties holds the application tunables (thread pools, log settings, monitoring and so on). Edit the file, then choose option 5 (or run ./setup.sh --configure-properties).

vi ~/dvsum-gateway/configuration.properties

./setup.sh --configure-properties

The installer shows Proposed infra changes and asks Apply these changes? [y/n]. If nothing differs it says No changes — cluster already reflects the current configuration.properties. After y, the Connector and interactive workers restart so they pick up the new values.

7.6 Certificate renewal and replacement

./dvsum-gateway.sh status warns when the certificate has less than 30 days left. To renew or replace it, choose option 3 in the menu or run:

./setup.sh --rotate-certs

The installer goes straight to the same four certificate options as Step 17 (generate a CSR, add to an existing keystore, import a certificate and key, or use an existing keystore). The previous keystore is saved first under gateway-certs-data/backups/.

On screen

--- SSL Certificate Configuration ---

1. Generate a new CSR for a CA-signed (or self-signed) certificate

2. Add your certificate to an existing keystore

3. Import an existing certificate + private key into a new keystore

4. Use an existing keystore as-is

Choice [1]:

After the new certificate is applied, the Connector and interactive workers restart one at a time (Rolling restart of Connector and Interactive-worker...), so there is no downtime. It ends with Certificate rotation complete.

7.7 Registering (adding) a VM

There are two ways to register a VM, depending on when you do it.

A. Automatic — during the first install

Choose y at Auto-configure the other VM(s) via SSH now? in Step 14a. VM 1 connects to each VM over SSH, copies the installer, joins the VM as a control-plane node and verifies it. Nothing needs to be run on the other VMs. See Section 5 (Step 14a) for every prompt.

B. Manual — adding a VM to a running cluster

Use this to add a 4th (or later) VM to a cluster that is already running. Make sure the new VM meets Section 2.1 and that the ports in Section 2.2 are open between it and the existing VMs.

On VM 1: run ./setup.sh and choose 4. Add another VM to this cluster. The installer shows the current node count, then prints the Gateway IP, a Node token, and the ports to confirm:

On screen

[setup] ... Current cluster has 3 node(s).

On the new VM: copy this setup.sh (or the full install package) there and run:

  ./setup.sh --ha

Choose "Additional VM" when asked for this VM's role, then enter:

  Gateway IP:  <VM1-IP>

  Node token:  <node-token>

Press Enter once the new VM has run setup.sh (or Ctrl+C to do this later ...):

On the new VM: copy setup.sh to it, then follow the steps below.

1. Run ./setup.sh --ha. The installer runs its system checks (Steps 1–3).
2. At This VM's Role, choose 2) Additional VM.
3. Enter the Gateway IP and Node token from VM 1.
4. At Confirm these ports are open [y/n], answer y.
5. Wait for This VM has joined the cluster.

Back on VM 1: press Enter. The installer waits (up to 10 minutes) for the new node to appear, then:

1. Reports 4 node(s) now in the cluster (4 Ready) and saves the new node count.
2. Recalculates Redis replicas and the Sentinel quorum for the new size and shows Proposed infra changes. Answer Apply these changes? [y/n] with y. (If you answer n, the VM is in the cluster but Redis is not scaled; run option 4 again later to apply it.)
3. Restarts pods as needed and verifies that a Redis pod and a Connector pod are running on the new VM.
4. Finishes with VM added: cluster now has N node(s).

7.8 Deregistering (removing) a VM

Removes a VM from the cluster safely: its work is moved to the other VMs first. Run it from a VM that stays in the cluster, never from the VM being removed. Start with ./setup.sh --deregister-node (or menu option 6).

Step 1 — choose the VM

On screen

--- Current cluster nodes ---

NAME           STATUS   ROLES                AGE   VERSION ...

dvsum-gw-01    Ready    control-plane,etcd   ...

dvsum-gw-02    Ready    control-plane,etcd   ...

dvsum-gw-03    Ready    control-plane,etcd   ...

dvsum-gw-04    Ready    control-plane,etcd   ...

Node name to deregister (from the NAME column above):

Enter the exact NAME of the VM to remove. The installer refuses if: the cluster has only 1 node (use --uninstall instead), the name is not found, or the name is the VM you are running on.

Step 2 — read the warnings

If removing the VM would take the cluster below 3 nodes, the installer warns that the cluster falls back to a reduced quorum mode and asks you to type yes to continue. If removal would drop etcd below a majority, a second, stronger warning appears (etcd would stop until the remaining node's database is reset). The installer handles that reset for you, but only continue if you intend it. Keep 3 or more VMs for production.

Step 3 — confirm

On screen

This will:

  1. Cordon + drain 'dvsum-gw-04' (evicts its pods, reschedules them onto remaining nodes)

  2. Uninstall k3s from 'dvsum-gw-04'

  3. Remove its Node object from the cluster

  4. Scale Redis replicas/Sentinel quorum down to match 3 node(s)

Type 'yes' to proceed:

Type yes to proceed. Anything else cancels with nothing changed.

Step 4 — drain the VM

The installer cordons the VM (no new pods are placed on it) and drains it (its pods move to the other VMs, up to 3 minutes). If something is still stuck afterwards, it tells you which pods to check.

Step 5 — uninstall K3s on the removed VM

The installer cannot run commands on another machine, so it asks you to do this part:

On screen

'dvsum-gw-04' is a different machine — this script has no way to run

commands on it remotely. SSH to it now and run, as root/sudo:

  sudo /usr/local/bin/k3s-uninstall.sh

Step 6 — clean-up (automatic)

If etcd was reset (see Step 2) the installer does it now (Resetting this node's etcd to run standalone...) and waits for the API to return. It then removes the VM's node object, updates the saved node count, and rescales Redis and the Sentinel quorum to the new size (shown for visibility, applied automatically). It ends with the confirmation and a pod listing:

On screen

==================================================================

 Node 'dvsum-gw-04' deregistered. Cluster now has 3 node(s).

==================================================================

Check that the pods rebalanced across the remaining VMs, then remove the VM from your load balancer and DNS records.

8 Uninstalling the Gateway

Run:

 ./setup.sh --uninstall. 

On screen

What would you like to remove?

  1. Gateway only — removes the Helm release and the 'dvsum-gateway'

     namespace, leaves K3s/Kubernetes itself intact on this machine

  2. Full cleanup — Gateway, plus K3s itself on this machine

     (irreversible; this machine stops being a Kubernetes node)

  3. Cancel

Choice [1]:

The installer lists exactly what will be deleted and asks Type 'yes' to confirm:. If a local copy of the current keystore exists it asks whether to remove it too ([y/n]); the CSR, issued and backup certificate files are left untouched.

9. Troubleshooting

10. Installer Command Reference