Moving workspace tunnels to a company tunnel – mabl help

If several workspaces in your company each run their own Link Agents to reach the same private environments, you can replace those workspace tunnels with one company-scoped tunnel that every workspace shares. This article is for account admins who want to make that move. When you're done, one set of Link Agents serves every workspace, and no environment has to change.

Company-scoped tunnels require Link 3.0. If your Link Agents still use the legacy protocol, complete Migrating from legacy Link to Link 3.0 first.

How the move works

A tunnel is identified by its name. When a workspace tunnel and a company tunnel have the same name, the company tunnel takes precedence whenever it has a connected agent. Every test, training session, and database query in that workspace that uses the name goes through the company tunnel instead.

As a result, moving to a company tunnel doesn't require editing any environment. You start a company tunnel with the same name as the workspace tunnels, and traffic moves to it as soon as it connects. If the company tunnel has no connected agent, traffic falls back to the workspace tunnel, which is also how you roll back.

The move is simplest when every workspace already uses the same tunnel name for the same network, for example qa-env-01 in each workspace. One company tunnel with that name then takes over all of them at once.

What carries over

Environments, database connections, and deployment events keep working, because they refer to tunnels by name.
Link Agent configuration files carry over. A Link Agent can serve the company tunnel alongside its workspace tunnels while you move.
Your Link Agent hosts can serve the company tunnel. You don't need new machines unless you want them.

A few things change once traffic goes through the company tunnel:

Management. Account admins manage the tunnel's agents from the Networking page of the account dashboard, instead of workspace owners from Settings > Networking.
Tunnel access settings. The company's Link tunnel access settings on that Networking page decide who can reach the tunnel from the mabl Desktop App and CLI, and whether mabl support can reach it. A workspace's own settings no longer apply to the tunnel.
Activity. Events for the tunnel appear in the company dashboard's activity feed, rather than each workspace's activity feed.

Before you start

You need the account admin role.
Every Link Agent that will serve the company tunnel must run version 3.0 or later.
Every Link Agent that serves the company tunnel must be able to reach the applications that all of the workspaces test through that name. A company tunnel sends every workspace's traffic through the same agents, so an agent that can't reach one workspace's environment makes that workspace's tests fail.
Plan for the combined traffic of every workspace that will share the tunnel. See Sizing and scaling Link Agents.
If people in your company train tests over Link or run tunnel diagnostics, set up the company's Link tunnel access settings before you move, so they keep their access.

Plan the tunnel names

List the tunnel names each workspace uses. You can find them in the Tunnels table on each workspace's Settings > Networking page.

Workspaces that already share a name for the same network move together. Create one company tunnel with that name.
Workspaces that use different names for the same network have two options. Either create one company tunnel for each name, or choose one name, create a company tunnel with it, and update the other workspaces' environments to use it.
A workspace that needs its own tunnel, for example because it tests a network the others can't reach, should keep a name that the company tunnel doesn't use. A company tunnel takes over every workspace that uses its name.

Create a company API key

A company tunnel is served by Link Agents that start with a company API key.

Open the account dashboard: expand the workspace dropdown in the top right corner of the mabl app and click your company under Manage company.
Open the API keys tab and click Create key.
For the key type, choose Link Agent. Give the key a name, set an expiration, and click Create key.
Copy the key and store it securely. You won't be able to see it again.

Start the company tunnel

Choose whether to serve the company tunnel from the hosts that already run your workspace tunnels, or from new hosts.

On the hosts you already have

A Link Agent applies changes to its configuration file while it runs, so you can move one without restarting it.

On one of the hosts, add a tunnel entry to the Link Agent's configuration file with the same name as the workspace tunnel and the company API key:
```
tunnels:
  - apiKey: {workspace-link-agent-api-key}
    name: qa-env-01
  - apiKey: {company-link-agent-api-key}
    name: qa-env-01
```
Save the file, and wait until the company tunnel shows as connected on the Networking page of the account dashboard. From this point on, every workspace that uses qa-env-01 sends its traffic through the company tunnel.
Make the same change on each remaining host, so that the company tunnel has more than one agent.

On new hosts

Set up a Link Agent on each new host with the company API key and the same tunnel name as the workspace tunnels.
Wait until the agents show as connected on the Networking page of the account dashboard. From this point on, every workspace that uses the name sends its traffic through the company tunnel.

Confirm that traffic moved

On the Networking page of the account dashboard, check the Tunnels table. The Workspaces column lists the workspaces whose environments use the company tunnel.
In each workspace, run a plan that uses mabl Link and confirm that it passes.
On each workspace's Settings > Networking page, the workspace tunnel's traffic drops to zero as the company tunnel takes over.

Keep the workspace tunnels running until you're confident in the company tunnel. While they run, stopping the company tunnel's agents moves traffic back to them straight away.

Retire the workspace tunnels

Once the company tunnel is working, retire the workspace tunnels:

On a shared host, remove the workspace tunnel's entry from the configuration file and save it. The workspace tunnel stops taking new connections and lets its current ones finish, while the company tunnel keeps running.
On a host that only serves the workspace tunnel, shut down its Link Agent from Settings > Networking in that workspace. See Removing mabl Link tunnels.

After the workspace tunnels are gone, you can revoke the workspace "Link Agent" API keys that only they used.

Learn more