1.4 Pairing and Validating a Virtual Appliance
Key Takeaways
A running VA image and a saved VA entry in the tenant are prerequisites. Pair the appliance before expecting it to handle requests.
For a standard VA, set the cluster passphrase, generate a pairing code, and submit the code on the tenant’s configuration page within four hours.
Every VA in a cluster uses the same key passphrase. Each VA must complete the pairing and configuration process.
After the VA displays Connected, test the source through the assigned cluster before relying on it for aggregation or provisioning.
Track three stages of activation
For a standard SailPoint ISC deployment, distinguish image deployment, tenant pairing, and source validation. Image deployment creates the virtual machine (VM) in the customer environment. Pairing associates that instance with the appliance entry in the intended tenant and cluster. Source validation checks the connector path between that cluster and the system the tenant will govern.
Start by confirming the particular tenant and cluster you need. The sandbox and production cluster names and records can be similar, especially if the organization tries to keep their layouts comparable. Check the tenant context before generating and entering codes. Approve any source association only after confirming which environment each end belongs to. A sandbox VA should not be validated by pointing it at a production system just because the production system is reachable.
Pair a standard VA
This sequence applies to the standard SailPoint image with direct egress in a commercial environment. An HTTP proxy deployment has a separate procedure and needs its proxy settings before bootstrap. Use the environment-specific procedure where it differs.
- In the virtual appliance settings for the intended tenant, create or select the appropriate cluster. Add a VA entry to that cluster. It is possible to save the entry before pairing, but the appliance cannot perform work in that state.
- Deploy and start the correct image on the selected virtualization platform. Sign in as the documented appliance user and change the initial password immediately.
- Run
va-bootstrap set-passphraseon the running appliance. Use the same cluster passphrase on each member. Keep the passphrase in the approved secret store. This is different from the local sign-in password and from the credential that the connector will use to access a target. - Run
va-bootstrap pairon the VA. Enter the generated code in the tenant’s VA configuration page within four hours and choose Pair. Allow roughly 30 minutes for configuration, and use the Connected status to establish that setup has finished. - Repeat for each cluster member. Once the VA is operational, connect the cluster to an appropriate source and test the connector’s configuration. Select and validate connector-side Transport Layer Security (TLS) where supported.
The documented pairing window is measured from code generation. In a worked example, a commercial VA generates a code at 08:20 Coordinated Universal Time (UTC). Four hours later is 12:20 UTC. An attempt at 12:35 UTC is outside the window, even if the virtual machine is still running. Generate a fresh code on that VA and submit it promptly in the correct tenant. The approximately 30 minutes is an expected setup duration after pairing. It is a separate time from the code’s four-hour validity.
Verify the correct stage
| Observation | What the engineer can infer | What to verify next |
|---|---|---|
| VM is running, and the VA entry was saved before pairing | The image and tenant record exist | Complete bootstrap and pairing for that entry |
| The pairing code is older than four hours | The registration window for that code has elapsed | Generate a new code and submit it within the window |
| The VA displays Connected | Its cloud-facing setup is complete | Confirm the source’s assigned cluster and test the target connection |
| Source connection and reads work | The connector can read the target for that test | With authorization, validate the write operations the use case requires |
Imagine that a two-member production cluster is ready to accept a new private directory. One VA shows Connected and the other is visible but unpaired. An aggregation through the connected member may succeed, but it does not prove both appliances are usable. Finish configuration on the second member and verify its status independently. Then validate source reachability before treating the cluster as ready for its production workload.
Troubleshoot an unpaired machine at the bootstrap stage. If it reports Connected but the new source denies authentication, check the source settings and target credentials. Entering a different pairing code will not give the connector access to an account in the target. This distinction keeps the engineer from repeating an earlier successful setup step while the actual fault remains.
See SailPoint’s instructions for adding VAs to a cluster and configuration for other egress modes.
A team saved a new VA entry, started its VM, and set the cluster passphrase. No code has been submitted. What should it do next in a standard commercial deployment?
Assign a domain service account as the new VA’s passphrase
Run va-bootstrap pair, submit the code for that VA, and wait for Connected
Configure the target account schema to pair the VA automatically
Run a source aggregation to populate the appliance entry
An appliance generated a pairing code at 08:20 UTC, and the team tries to use it at 12:35 UTC. Which action addresses this issue?
Use the code before 12:50 UTC because the configuration time extends the pairing window
Change the source’s service credential to renew the code
Start an aggregation to extend the registration window
Generate a fresh pairing code on the appliance and submit it within four hours
Sections you finish are checked off in the contents.