Install VCSA Updates

原文：Install VCSA Updates — theDXT (Daniel Keer)

Here is how to update VCSA (vCenter Server Appliance, specifically version 7) with the web UI. Updating the appliance looks like the simplest job in the vSphere admin's week — there is literally a button labelled Update — and yet it is one of the best documented ways to lose a maintenance window. The depot is unreachable from the appliance, the platform services controller cannot validate a certificate, a pre-update check fails on something you have never heard of, or the snapshot you took for safety fills the datastore halfway through the install. This guide walks the whole job in order: interoperability first, then the pre-update checks, then staging the payload so the real downtime is short, then the install, then verification and rollback.

What an update actually changes

A VCSA update is not a single patch. The appliance is a Photon OS virtual machine running a vSphere software stack: vCenter services (vpxd, vpostgres, the STS token service, the certificate infrastructure), the platform services controller components if you deployed an embedded topology, and the VAMI management interface itself on port 5480. The update payload is a set of RPM-like packages plus a manifest, and the installer sequences them so that the appliance services stop, the packages are applied, the database schema is upgraded, and the services come back.

That sequencing is why a VCSA update is not instant. Depending on the size of the inventory and the database, expect 20 to 60 minutes for the actual install on a reasonably healthy appliance, plus the staging time beforehand. On a large environment with tens of thousands of objects, or where the appliance is still running on an external SQL-era migration, budgets have to be larger.

There are two distinct update paths you will meet, and it matters which one you are on:

• In-place update within the same major version — for example 7.0 U2 to 7.0 U3. This is what the Update section of the VAMI does, and it is what this article covers.
• Major upgrade to a new version — for example 7.0 to 8.0. That uses the vCenter Server installer's upgrade path or a deployment of a new appliance with a migration of configuration, and the checks and rollback model are different.

If you are still building out vCenter infrastructure and have not deployed the appliance at all yet, start with Install VMware vCenter before reading further.

Prerequisites and pre-flight checks

Do these before you touch the Update tab. Most failed updates are decided here, not in the installer.

• A real backup of the VCSA. Use the file-based backup built into the appliance and write it to a location that is not the appliance itself — an SMB share, NFS share, or SFTP target. A snapshot is not a backup: it does not help you if the vCenter database corrupts on a datastore that the appliance is running on.
• A snapshot as a second line of defence. Take a snapshot of the VCSA VM with the memory option off, and remember that vCenter is what manages DRS and HA, so choose your timing so that losing vCenter for 30 minutes does not matter.
• Credentials. You need the SSO administrator password for the vSphere Client, and the appliance root password for the VAMI on port 5480. These are frequently different. Have both checked and working before the window opens.
• DNS and time. Forward and reverse DNS records must resolve, and NTP must be healthy on the appliance, every ESXi host, and the Platform Services Controller. Certificate validation failures during an update trace back to clock skew more often than people expect.
• Free space. The appliance needs space for the staged payload and for the running services. Check the root partition and the database partition in the VAMI's Monitor tab, and check the datastore hosting the VCSA VM.
• Rights. The account you use must be a vSphere administrator with permission on the appliance objects and the SSO domain, not just a read-only or a custom role.

The original walkthrough below is from theDXT and covers version 7 with accompanying screenshots of every step. Follow it in order.

Step 1 — Confirm you have a backup and a snapshot

Make sure you have a backup of your VCSA. I like to have a backup and a snapshot to be extra safe.

Step 2 — Open the appliance and the Update tab

• Click on your VCSA server

* Click on the Update tab

Step 3 — Run the interoperability report first

Before looking at a single patch, find out what you are allowed to install. The interoperable matrix is the difference between a clean update and a failed one.

• In Update Planner select the update you want to install and click on Generate Report and select Interoperability. (this will check and make sure everything is compatible in your VCSA setup)

• Double check and make sure everything is good

What you are looking for here is a report that says the update is supported against the ESXi versions in the environment, the hardware versions of the VMs, the storage and network plugins, and any other vSphere components you have registered. A red row is not a suggestion — fix the component or choose a different update level. Skipping straight to the install because the report is inconvenient is how people end up with a half-managed environment where DRS refuses to run or a plugin silently stops responding.

Step 4 — Generate the pre-update checks

• Go back to Update Planner and click on Generate Report and click on Pre-Update Checks

The pre-update checks inspect the appliance itself rather than the ecosystem: free disk space on each partition, the health of the database, orphaned objects, duplicate or unresolvable service records, the state of the certificate infrastructure and the STS signing certificates, and whether the appliance services are actually running cleanly. They also verify the source of the update is reachable and the payload signature can be validated.

If a check fails, the fix is outside the installer. Typical causes and their remedies:

• Out of space on a partition — clear old logs and support bundles, or extend the appliance disk before continuing.
• Stale or expired certificates — replace the affected certificate and restart the relevant service; the update will not fix a broken trust chain for you.
• NTP or time drift — correct the time source and let the appliance settle, then re-run the checks.
• Database or service problems — restart the appliance services, or reboot the appliance, then re-run the checks before attempting anything else.

If no issues are found then you can click on the link to open Appliance Management.

Step 5 — Log in to the Appliance Management Interface

• Login to VMware vCenter Server Management (this will likely be your VCSA root username and password)

This is the VAMI on https://<vcsa-fqdn>:5480. If you cannot reach it, the platform services controller or the appliance's own services are not healthy, and the update cannot proceed. Working DNS and a trusted certificate make this a lot less painful — if you have replaced the appliance certificate with a CA-signed one, see VMware vCenter OVA Certificate Trust.

Step 6 — Select the update and stage it

• Click on Update

• Select the update and expand it and click on run Pre-update checks

The appliance runs the same checks again here, from the perspective of the local MACHINE rather than the vSphere Client. This is the last cheap exit point: if these pass, you are committing to the update.

• If the Pre-update checks passed then click on Stage Only (Staging will pre-load the update to VCSA to reduce downtime.)

Staging is the part of the process people skip and regret. It downloads and unpacks the payload onto the appliance while the environment keeps running normally, so the install phase afterwards only has to apply what is already local. On a slow WAN link or with a large update this can take a long time; doing it outside the downtime window is the whole point. You can safely stage days before the install if you want, as long as you have the space and nobody changes the update level in the meantime.

Step 7 — Install the update

• After the update has been staged you can now click on Install

• Agree to the stuff

It will run some pre update checks

• Give it your VCSA Administrator password

• Make sure you have a backup.

Now the install will do its thing.

During this phase the vSphere Client becomes unavailable, alarm email stops, and DRS stops making recommendations. Anything that depends on vCenter — including some backup products, monitoring integrations and self-service portals — will log errors. This is expected, and it is why the maintenance window exists. Do not log in to the appliance and try to restart services that look stuck: the installer does restart them as part of its sequence.

Step 8 — Verify the result

After the install is done you can now login to your updated VCSA.

Then confirm all of the following before you declare success and remove the snapshot:

• Log in to the vSphere Client with an SSO account and check that the inventory, permissions and tags are intact.
• Check the version and build number. From a shell: vpxd -v and cat /etc/applmgmt/appliance/software_version. Compare it against the build you intended, which is also visible from the ESXi side — the method in ESXi Build Number without vCenter is useful when the client is unavailable.
• Verify every ESXi host still shows as connected in the inventory, and that certificates are trusted rather than showing as expiring or invalid.
• Run a scheduled task manually (a clone, a snapshot or a backup job) to prove the database and the services that depend on it are working.
• Check the VAMI's health and services pages for anything red or amber.

Only then remove the snapshot. Keep it for a couple of days if the environment is important — a snapshot costs you space, but discovering a broken integration a week later without one costs you a lot more.

Rollback and recovery

There is no "undo" button in the VAMI. Your recovery options, in order of preference:

1. Revert the snapshot. Fast, but it takes the environment back in time completely, including any changes made to inventory objects after the snapshot was taken. This is why the snapshot exists.
2. Restore the file-based backup. Slower, and it also rewinds to the backup point, but it works when the VM itself or the appliance disk is unusable. Restore it to a new appliance if possible, so the broken one stays available for inspection.
3. Re-deploy and re-point. For a badly damaged appliance, deploy a new VCSA at the correct version and migrate the hosts and inventory. More work, least risk of carrying forward corruption.

A snapshot rollback is also the correct answer when the install completes but a dependent component is broken in a way the pre-update checks could not catch. Reverting is usually faster than trying to repair a mixed-version environment.

The same discipline applies to the hosts themselves. Once vCenter is healthy, patch ESXi with Lifecycle Manager where you can, or follow ESXi Manual Update when you cannot. And if you have not automated your host configuration capture, vCenter ESXi Config Backup Script shows how to keep a rolling copy of each host's configuration so a rebuild is a restore rather than a rebuild.

FAQ and common problems

The appliance cannot reach the depot. Check default gateway and DNS on the appliance, and any proxy configured in the VAMI. If the environment is air-gapped, use the offline ISO instead and mount it or point the installer at a local repository — the same staging and install steps apply.

A pre-update check fails and I do not understand it. Read the check name literally. They map to concrete conditions: disk space, a service that is not running, a certificate about to expire, an unresolvable name, or a file permission problem. Fix the underlying condition and re-run; do not look for a flag to skip the check.

Can I update the appliance while hosts are out of date? Sometimes, within the interoperability rules, but check the interoperability report rather than assuming. The report is generated against the current environment state, so re-run it if anything changed since you first looked.

How much downtime should I plan for? Staging: however long the download and unpack take — do it in advance. Install: 20 to 60 minutes typically, longer with a large inventory. Add 15 minutes either side for checks and verification, and never plan an appliance update back to back with another change.

Should I use the CLI instead? Yes, if you need to script it or the UI is misbehaving. SSH to the appliance and use the appliance shell's software-packages utility to list, stage and install updates, or software-packages install --iso for an offline ISO. The checks and the sequencing are the same code underneath; the only thing you lose is the pretty progress bar, so be ready to tail the installer log while it runs.

Follow the order above — backup, interoperability, pre-update checks, stage, install, verify — and a VCSA update becomes routine instead of memorable.