Skip to main content
Version: 1.0

Updating Ballast

A Ballast release is three binaries built together: the centre, Ballast Manager and the Windows agent. On an appliance, all three are uploaded through Ballast Manager's Updates page. The agents on your hosts are then updated from the console.

Your hosts are not affected while the centre restarts. Each agent keeps enforcing the last desired state it was given, and reports back when the centre answers again.

This guide is for the Rocky Linux appliance, which is where Ballast Manager runs.

Before you start​

  1. Read the release notes for the version you are moving to. Each release has a "Before you upgrade" list.
  2. Download all three binaries for the release from the Downloads page, and check each one against SHA256SUMS as described there. The names carry the version, for example ballast-centre-1.0.2. There is no need to rename them: Manager identifies the centre and Manager binaries by the version built into them, and the agent only has to be a .exe.
  3. Take a backup. In Ballast Manager, open Backup and select Back up now. See Backup and restore.

Open Ballast Manager​

In the console, go to Settings, Ballast Manager and select Open Ballast Manager. It runs on the appliance on port 9444, for example https://ballast.example.com:9444/, and has its own password, kept on the appliance rather than in the centre's database.

Ballast console Settings, Ballast Manager page listing what Manager is for, with a button that opens it

Select Updates in Manager's left-hand menu.

1. Check what is running​

The top of the Updates page shows the version of each part:

Ballast Manager's Updates page, What is running: Centre, running 1.0.1, reported by the centre itself; Centre, on disk 1.0.1, the same build it is running; Manager 1.0.1; Windows agent 1.0.1, served to hosts on onboarding, matching the centre

  • Centre, running is the version the centre itself reports.
  • Centre, on disk is the binary that will run the next time the centre starts. It normally matches the running version.
  • Manager is Ballast Manager itself.
  • Windows agent is the ballast-agent.exe the centre gives to hosts, both when a host is onboarded and when an agent is updated from the console.

2. Update the centre​

Under Update the centre, choose the ballast-centre file you downloaded and select Upload and restart the centre.

Ballast Manager's Update the centre section: a note that the new binary is run once before it replaces anything and the old one is kept, a file picker for ballast-centre, the Upload and restart the centre button, and Go back to it for the kept build

Manager runs the new binary once to confirm it works on this machine before it replaces anything, sets the running binary aside, restarts the centre on the new one and waits for it to answer. Each step is listed on the page as it happens. If the new centre does not come back healthy, Manager puts the previous binary back and starts it again without being asked.

Ballast Manager's Updating the Ballast centre card, finished in 2 seconds, with six ticked steps: Uploaded 1.0.2, replacing 1.0.1; checking the new binary will actually run on this machine; setting the running binary aside so it can be put back; stopping the centre and putting 1.0.2 in place; starting it and waiting for it to answer; running 1.0.2, backed by PostgreSQL, with the previous build kept

When it has finished, reload the console. Its footer shows the new version next to Centre connected. If you run the console as an installed app, close the window and open it again: an open app window keeps showing the build it last loaded.

3. Replace the Windows agent file​

Under Update the Windows agent, choose the ballast-agent .exe from the same release and select Replace the agent.

Ballast Manager's Update the Windows agent section: the path of the agent file the centre serves, its size and when it was last updated, a file picker for ballast-agent.exe and the Replace the agent button

This replaces the file the centre gives to hosts. It does not touch any host by itself.

Do this before updating the hosts. The console updates a host with whatever file is here, so a host updated before the agent file is replaced gets the old agent again, and still shows as outdated afterwards. If the agent file and the centre are different versions, the Updates page says so under Windows agent. This is what it looks like straight after the centre is updated and before the agent file is replaced:

Ballast Manager's What is running panel after a centre update: Centre, running 1.0.2; Centre, on disk 1.0.2; Manager 1.0.1; Windows agent 1.0.1, with a warning that it does not match the centre and that a host updated to it reports 1.0.1, which reads as an update that did not take

Once the new agent file is in place, the warning goes and the Windows agent shows the same version as the centre.

4. Update the agents on your hosts​

In the console, go to Settings, Agents. Once the centre is updated, every host still on the previous agent is listed as outdated. Select Update all outdated.

Ballast console Settings, Agents: the Agent version panel reads 3 of 3 outdated, with an Update all outdated (3) button, and three hosts each showing v1.0.1 and update

In the dialog:

  • Choose the credential used to reach the hosts over WinRM.
  • Confirm each host's address. A host whose management address is on a converged virtual switch may not report one, so fill it in if it is empty.
  • Leave ticked the hosts you want updated, then select Deploy to the number of hosts ticked. Hosts that are reporting are ticked for you. A host that is not reporting to this centre, for example one that is shut down, is listed separately and left unticked.

Ballast console Update all agents dialog: notes that it pushes agent 1.0.2 over WinRM and that each host waits for its running jobs, a credential picker, two reporting hosts ticked with their WinRM addresses, a third host listed under Not reporting to this centre and unticked, and a Deploy to 2 hosts button

Each update runs in the background: follow it in the Tasks bar and in the host's Activity. A host waits for its own running jobs to finish before its agent is stopped, and is given no new jobs meanwhile. A host still busy after 20 minutes is left alone and reported as failed rather than interrupted, so you can try it again later.

To update one host on its own, right-click it and choose Update agent, or select the update marker beside its agent version on the host's Summary.

:::caution A host that is not reporting to this centre

Updating an agent reinstalls it against this centre: it writes this centre's address and certificate into the agent service. If a host listed as not reporting has been moved to another centre, updating it from here takes it back. The dialog warns you when a ticked host is not reporting.

:::

Updating Ballast Manager​

Manager can be updated before or after the centre. The two are replaced independently.

Under Update the manager, choose the ballast-manager file and select Upload and restart the manager.

Ballast Manager's Update the manager section: a note that the page goes away for a few seconds while Manager restarts, that the binary is run once before it is put in place and the running build is kept, a file picker for ballast-manager and the Upload and restart the manager button

The page goes away for a few seconds while Manager restarts on the new build. As with the centre, the new binary is run once before it is put in place, and the running one is kept. If the new build will not start, the appliance puts the kept one back and starts it again on its own.

Going back to the previous version​

  • Centre: the build it replaced is kept. Under Update the centre, select Go back to it.
  • Manager: the previous build is put back automatically if a new one fails to start.
  • Agents: upload the older ballast-agent.exe under Update the Windows agent, then update the hosts again. Manager accepts an agent that does not match the centre, because going back is sometimes the right call, but it says so on the Updates page.

If something does not look right​

  • A host still shows the old agent version after updating. The agent file in Manager was probably not replaced first. Check Windows agent at the top of the Updates page, replace it, and update the host again.
  • The console looks the same as before. Reload the page, or close and reopen the installed app window.
  • A host shows only two adapters, NIC1 and NIC2, and no switches, storage or VMs. Its agent is running the development stub, which an agent installed by hand before 1.0.2 did unless it was given -hyperv powershell. Update its agent from the console, which reinstalls it on the real backend.