Link Agents keep themselves up to date, but the hosts they run on still need patching, restarts, and the occasional configuration change. This article explains how to take a Link Agent out of service without interrupting tests, how to install and roll back updates, and how to change an agent's tunnels while it runs.
Take an agent out of service with maintenance mode
Maintenance mode drains a Link Agent. The agent stops accepting new connections and lets its current connections finish, so tests that are already running through it complete normally. Use it before you patch, restart, or retire an agent's host.
The agent keeps running while it is in maintenance, and it does not shut itself down. When you are ready, either exit maintenance to return the agent to service, or shut it down.
If other agents serve the same tunnel, new connections go to them while this one drains. If it is the only agent on its tunnel, tests that start during maintenance can't reach your application, so schedule maintenance for a time when no tests run.
From the mabl app
- Go to Settings > Networking. For a company tunnel, open the Networking page of the company dashboard.
- In the Link Agents table, open the agent's Manage menu and choose Enter maintenance.
- Confirm with Enter maintenance.
The agent's status changes to Draining while connections finish, then to Drained when it has no active sessions. Once it's drained, it is safe to shut down. To return it to service, choose Manage > Exit maintenance.
Only workspace owners can manage the agents on workspace tunnels, and only account admins can manage the agents on company tunnels.
From the mabl CLI
mabl link-agents maintenance start {agent-id}
mabl link-agents maintenance end {agent-id}
By default, the agent waits as long as its connections take to finish. To limit the wait, add --drain-timeout {seconds} to maintenance start. Get the agent ID from mabl link-agents list or from Settings > Networking.
Maintenance mode requires Link Agent version 3.0 or later. Starting and ending maintenance are recorded in the activity feed.
Rolling maintenance for a tunnel with several agents
To patch every host of a tunnel without interrupting tests, work through the agents one at a time:
- Put one agent into maintenance mode and wait for it to show Drained.
- Patch or restart its host.
- Exit maintenance, or start the agent again if you shut it down, and confirm it shows Connected.
- Repeat with the next agent.
How updates are installed
The Link Agent checks for new versions and installs them automatically. It installs each new version beside the one that is running rather than over it. If an update is interrupted, the agent keeps running the version it had, and the previous version stays on disk so that you can go back to it.
While an update installs, the agent briefly runs its tunnels on the old and new versions side by side, until connections on the old version finish. Plan host memory for that overlap. See Sizing and scaling Link Agents.
On Settings > Networking, the Updates available count shows how many agents have a newer release available, and the Version column marks each one with the version it can update to.
Install an update now
To install the latest version without waiting, run the following from the Link Agent's directory:
bin/link-agent --update
The command installs the latest version, reports what it did, and exits. Restart the agent to run the new version.
For the Docker image, pull the newer image and restart the container instead. See Link with Docker.
Roll back an update
If a new version causes problems, go back to the previous one with the versions script in the Link Agent's bin directory. The script doesn't need the agent to start, so it works even when the new version won't run.
# List installed versions, marking the one that runs
bin/versions.sh --list
# Go back to the previous version
bin/versions.sh --rollback
# Run a specific installed version
bin/versions.sh --set {version}
bin\versions.bat --list
bin\versions.bat --rollback
bin\versions.bat --set {version}
Restart the Link Agent afterwards to run the version you chose. Let mabl know about the problem, so that it can be fixed in a later release.
Turn off automatic updates
To control when updates install, set disableAutoUpdates to true in the Link Agent configuration file. With automatic updates off, install updates yourself with bin/link-agent --update. Keep agents current, because older versions miss fixes and newer features.
Change tunnels without restarting
A Link Agent started with a configuration file watches the file and applies changes while it runs:
- A tunnel you add connects right away.
- A tunnel you remove stops taking new connections and lets its current ones finish, so running tests aren't interrupted. It then waits until you shut down the agent or remove the tunnel in the mabl app.
- Changes to proxy settings and connection filters apply to the running tunnels.
If the edited file can't be read or has an invalid setting, the Link Agent logs the problem and keeps running with its previous configuration. To turn off watching, start the agent with --no-config-reload.
Moving a workspace tunnel to your company works the same way. See Company-scoped Link tunnels.
Record who maintains an agent
Set pointOfContact in the configuration file to the person or team in your organization who maintains the agent, such as an email address or a team name:
pointOfContact: qa-platform-team@example.com
tunnels:
- apiKey: {your-api-key}
name: qa-env-01
The point of contact appears in the agent's details on Settings > Networking, so anyone who sees a problem with the agent knows whom to contact.
Stop an agent gracefully
When you stop a Link Agent with Ctrl-C, or when a service manager stops it, the agent lets in-flight connections finish before it exits. Press Ctrl-C a second time to stop waiting and exit right away.
To stop an agent for good and remove it from mabl, see Removing mabl Link tunnels.