← SailPoint ISC Greenfield Implementation Field Guide

SailPoint ISC Greenfield Implementation Field Guide

Setting Up Virtual Appliances and Clusters

On this page

Step 0: plan the clusters
Step 1: sizing and prerequisites
Step 2: obtain and deploy the image
Step 3: network settings on the VA
Step 4: create the cluster in the tenant
Step 5: pair each VA with the cluster
Step 6: verify before you attach a source
Step 7: attach sources
Operating the cluster
Disaster recovery
Build checklist
Actions

Every on-premises source in the program reached ISC through a virtual appliance (VA) in a cluster. This page is the build procedure, in the order we would do it again: plan the clusters, prepare the network, deploy the image, pair it with the tenant, verify, and then operate it. It follows SailPoint's published procedure (checked against the VA documentation in October 2026) and adds the planning and checks that the documentation leaves out. Commands are from the documentation unless marked otherwise. Re-check them against the current VA guide before use, because images and tooling change.

Step 0: plan the clusters

Decide this before you deploy anything. Sources are attached to a cluster, and moving fifty sources later is painful.

Question	Guidance
How many clusters?	At least one for production and one for sandbox. Add clusters per network boundary and per blast radius
How many VAs per cluster?	At least two, sandbox included. Updates roll through one VA at a time, so one VA means an outage on every update
Where do VAs sit?	Close to the sources they serve. One VA per virtual machine host, spread across hosts or availability zones. SailPoint advises against the DMZ
Which sources on which cluster?	Group by reachability and risk. The program used a cluster for HR, one per directory estate, one for application sources and one for flat files and region-specific systems, 5 clusters and 9 appliances in all
What is the network method?	Standard (direct outbound), HTTP proxy, or network tunnel. Pick one per cluster and keep each cluster consistent
Time zone	Set per cluster. It governs aggregation schedules and does not shift for daylight saving
Cluster type	Standard, unless you also run the product that needs the harvester type. The type cannot be changed afterwards

Write the plan as a table and keep it with the architecture document:

Cluster	Purpose	Sources	VAs	Host or zone	Network method	Owner
`<env>-<purpose>`			2		Standard

Order matters. The network and the plan come first; sources are attached only after every appliance shows connected and a failover test has passed.

Step 1: sizing and prerequisites

Item	Requirement (per VA)
Compute	4 processors, 16 GB memory, 128 GB storage as a minimum image. Cloud equivalents: a 4 vCPU general-purpose instance
Processor	A supported Intel or AMD generation exposed by the hypervisor
Hypervisor	vSphere 8.0 or later, Hyper-V Server 2016 or later, or a supported cloud
Network	Outbound 443 to SailPoint and the listed services, DNS (53), NTP (123), and the ports of the sources it serves
Time	Synchronised. Internal NTP if outbound 123 is closed
DNS	Reaches your internal DNS servers, so it can resolve source host names
Optional components	A Privileged Access Gateway or Data Access Security collector adds processors and memory
Restrictions	No third-party monitoring agents. Not in restricted geographies. Not in `10.255.255.241/28`, which a VA cannot route to

Write these down for the network team before the build (see the network page for a firewall request template).

Step 2: obtain and deploy the image

Platform	How
vSphere	Download the package from the VA documentation page and deploy it with your standard process
Hyper-V	Use the package labelled for Azure, which contains a `sailpoint-va.vhd`. Create a Generation 1 VM, give it the memory the requirements page states, connect it to an external virtual switch and attach the existing disk
AWS	Open a support request for an image (AMI) identifier, giving your account number and region. Launch it with an instance size that meets the requirements, enable instance metadata access with a hop limit of 2, and use a security group that allows port 22 from your range
Azure	The extracted disk is about 132 GB. Upload it to a storage container, create a managed disk from it, then create the VM from that disk (Linux, a size that meets the requirements) with a network security group that allows port 22
Google Cloud	Extract the image, upload it to a storage bucket, import it as a custom image without OS adaptation, and create an instance with a 128 GB boot disk

For every platform: start the VM, then sign in to the console or over SSH as the sailpoint user with the default password given in the documentation, and change it immediately:

bash

passwd

Store the new password in your vault. If it is lost, a new VA has to be created. On a cloud VM, if a failed DHCP-related service is reported after login, the documentation says to disable it:

bash

sudo systemctl disable esx_dhcp_bump.service

On Hyper-V, disable the Azure agent to prevent DNS and routing problems:

bash

systemctl status waagent
sudo systemctl mask waagent
sudo reboot

Step 3: network settings on the VA

Static IP (local deployments)

Find the name of the second network interface, then create the network file:

bash

ip addr
sudoedit /etc/systemd/network/static.network

text

[Match]
Name=<interface name>

[Network]
DNS=<dns server>
Address=<ip address>/<prefix length>
Gateway=<gateway>
Domains=<search domain>

bash

sudo reboot

Interface names are assigned when the VM is created, so check each VA. Use a different file, not a copy, per VA.

Local NTP

Where outbound NTP is closed, point each VA to your internal server. Each VA is configured separately:

bash

sudoedit /etc/systemd/timesyncd.conf        # set NTP=<server names or addresses>, uncomment it
sudo systemctl restart systemd-timesyncd
timedatectl status

Host name mappings for sources

If a source host name does not resolve through DNS, map it in /home/sailpoint/hosts.yaml and restart the service. Indentation is exact: two spaces before the address, four spaces then a dash before each name.

yaml

hosts:
  10.20.30.40:
    - host1.domain.example
    - host1

bash

sudo systemctl restart charon

Prefer fixing DNS to maintaining a file on every VA.

HTTP proxy

Copy the proxy template from SailPoint's community into /home/sailpoint/ and set it:

yaml

https_proxy: http://<proxy>:<port>/
http_proxy: http://<proxy>:<port>/
no_proxy: <host1>|<host2>          # hosts to reach directly, such as local APIs

Then pass the proxy to the bootstrap commands in the next step. In a cloud network, the VA must not be able to reach the instance metadata address (typically 169.254.169.254) when it runs behind a proxy. A proxy that inspects TLS must present a certificate the VA trusts, because the VA rejects untrusted certificates.

Network tunnel

For firewalls that can allow IP addresses but not domain names. It needs outbound 443 to the regional tunnel addresses. The setup guide is on SailPoint's community, behind a login, and the tunnel is not available in some government environments.

Step 4: create the cluster in the tenant

Admin, Connections, Virtual Appliances, Create New.
Enter a unique cluster name and description. Use a convention such as <env>-<purpose>-<nn>.
Choose the time zone.
Choose the cluster type (Standard).
Optionally enable debugging, which gives verbose logs for 24 hours.
Save. If you license other components, enable them under cluster components.

Step 5: pair each VA with the cluster

On each VA, with the same passphrase for every VA in the cluster:

bash

va-bootstrap set-passphrase
va-bootstrap pair

For a proxy VA, add the proxy options to both commands:

bash

va-bootstrap set-passphrase --http-proxy <http://host:port> --https-proxy <http://host:port>
va-bootstrap pair             --http-proxy <http://host:port> --https-proxy <http://host:port>

Then:

In the cluster, Edit, Virtual Appliances, Add New, VA.
Enter the pairing code shown on the VA in the configuration page, and select Pair.
Wait about 30 minutes.

Rule	Detail
Passphrase	The same on every VA in the cluster. It cannot start with a special character or contain `!`, `/`, `\` or spaces
Pairing code	Valid for 4 hours. Generate a new one if it expires
Association	By passphrase and pairing code, not by a key file
Order	Add the second VA after the first shows as connected, and use the same passphrase

Step 6: verify before you attach a source

Check	Pass
VA status	Connected for every VA in the cluster
Cluster badge	No "Only 1 VA", "Inactive VA" or "VA Did Not Update" badge
Time	`timedatectl status` shows synchronised
Name resolution	The source host resolves from the VA
Port reachability	The source port answers from the VA
Outbound	The required SailPoint hosts answer on 443
Source	A test source in the cluster passes Test Connection and a small aggregation
Failover	Take one VA out of service and confirm a source still aggregates

Take a VM snapshot after a good configuration, as SailPoint suggests, and delete it once the VA has joined its cluster.

Step 7: attach sources

Select the cluster on the source. If the source supports TLS, enable it, and the certificate is copied to the cluster.
Run Test Connection, then a first aggregation, then a full run.
Record the source, cluster and owner in the cluster plan.
For directory sources that write, install and test the directory agent on the Windows host (see the directory page).

Operating the cluster

Task	How
Health	Cluster and VA badges in the tenant, plus the monitors from the hypercare page
Restart the cluster	Menu, Restart, confirm. This is the usual first step for a stuck or non-updating VA
Updates	Rolling, one VA at a time, not skippable, with no notice. A cluster with a disconnected VA receives no updates at all, so fix an inactive VA quickly
Pending OS update	`sudo update_engine_client -status` shows "need reboot"
Debug logging	Enable only when needed, and turn it off, because it fills the disk
Disk, memory warnings	Check log levels, then the sizing against the requirements
Certificate expiry	Replace the expiring certificate under `/home/sailpoint/ca-certificates/` and remove the old one
Containers restarting repeatedly	If a container restarts more than 10 times in 30 minutes, update and restart the cluster
Password	`passwd` as `sailpoint`, then `sudo reboot`. Save it

Adding a VA to a cluster

Deploy the image, apply the network settings, run va-bootstrap set-passphrase with the cluster's passphrase and va-bootstrap pair, and add it in the cluster. Keep two or more in every cluster.

Replacing or retiring a VA

Delete a VA from the cluster's edit page, then shut down the instance on your platform. A VA cannot be deleted if it is the only one in its cluster and still has a source attached.
SailPoint advises against moving or migrating existing VAs. Replace by building new.
A failed cluster is replaced by creating a new cluster with at least two VAs, pointing each source at it, checking the connections, and then deleting the old cluster. Expect to re-enter source credentials when a source moves to a different cluster.

Disaster recovery

The documented approach is a second cluster, not a standby VA: a new cluster is built, sources are re-pointed, and credentials are re-entered. Plan accordingly:

Keep a runbook for building a replacement cluster, and rehearse it once.
Keep the credentials for every source retrievable from your vault, because failover needs them.
Decide which sources are critical enough to keep a warm second cluster for.
Remember that VAs and clusters are per tenant, so production and sandbox each need their own.

Rolling updates need a pair. One appliance at a time is updated, so two keep the cluster up. SailPoint advises building a new cluster rather than moving existing appliances.

Build checklist

Done	Item
	Cluster plan approved: names, sources, hosts, methods
	Firewall requests raised and tested from the VA network
	DNS and NTP confirmed
	Image deployed, default password changed and stored
	Static IP, hosts file or proxy configured
	Cluster created in the tenant with the right time zone
	Passphrase agreed and stored; each VA paired within four hours
	Every VA Connected; two or more per cluster
	Test source passes; failover tested
	Sources attached and documented
	Monitoring and alerting on cluster status
	Rebuild runbook written

Actions

Plan clusters in a table before you deploy, and give every cluster two or more VAs.
Build the network (firewall, DNS, NTP, proxy) before the image.
Change and vault the default password on first login.
Use one passphrase per cluster and store it.
Verify with Test Connection and a failover test before you attach production sources.
Alert on cluster badges, and treat "Only 1 VA" as an incident.
Rehearse a rebuild.