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 company admins who want to make that move. When you're done, one set of Link Agents serves every workspace.

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.

If you can't reuse the workspace tunnel names, or you'd rather give the company tunnel a name of its own, start the company tunnel under a new name and add it to every environment with the mabl CLI instead. See Move to a company tunnel with a new name.

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. Company admins manage the tunnel's agents from the Networking page of the company 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 company 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 create one company tunnel with a new name and add it to every workspace's environments with the mabl CLI.
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 company 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 company 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 company 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 company 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.

Move to a company tunnel with a new name

Moving by name only works when the company tunnel can reuse the workspace tunnels' name. If workspaces use different names for the same network, or you want the company tunnel to have a name of its own, start the company tunnel under a new name and point the environments at it with two mabl CLI commands:

mabl link-agents add-to-environments adds a tunnel to every environment and database connection that already uses mabl Link, beside the tunnels they use today.
mabl link-agents remove-from-environments removes tunnels from them once the company tunnel serves them.

With --company-id, each command covers every workspace in your company. Company IDs end in -co. To find yours, see mabl resource IDs.

Both commands are dry runs until you add --execute. A dry run lists each environment and database connection that would change, with its tunnels before and after, and changes nothing. Run each command without --execute first, review the list, and then run it again with --execute. Save the output of the --execute run, since it records the tunnels each environment had before the change.

The steps below use qa-shared as an example name for the company tunnel.

What you need

Meet the requirements in Before you start.
Install mabl CLI 2.141.2 or later, and sign in with mabl auth login as a company admin.
Choose a name for the company tunnel that no workspace tunnel uses. If a workspace tunnel has the same name, the company tunnel takes it over as described in How the move works.

Start the company tunnel under the new name

Create a company API key.
Start one or more Link Agents with the company API key and the new tunnel name, either on the hosts you already have or on new hosts, as described in Start the company tunnel. For example, add this entry to the configuration file of an agent that already serves a workspace tunnel:
```
tunnels:
  - apiKey: {workspace-link-agent-api-key}
    name: qa-env-01
  - apiKey: {company-link-agent-api-key}
    name: qa-shared
```
Wait until the agents show as connected on the Networking page of the company dashboard.

No traffic goes through the company tunnel yet, because no environment names it.

Add the company tunnel to every environment

Preview the change:
```
mabl link-agents add-to-environments --company-id {company-id} --tunnel qa-shared
```
The command adds qa-shared to every environment that routes through mabl Link, and to every database connection or override that names a tunnel. It leaves environments without Link, and database connections that name no tunnel, as they are.

Review the list, then apply it:

mabl link-agents add-to-environments --company-id {company-id} --tunnel qa-shared --execute

Each environment now lists both its workspace tunnel and qa-shared. When an environment lists more than one tunnel, mabl sends each connection through one of them and tries another if the first can't reach the destination, so traffic starts to flow through the company tunnel while the workspace tunnels keep serving.

Confirm the company tunnel works

On the Networking page of the company dashboard, check the Tunnels table. The Workspaces column lists the workspaces whose environments use qa-shared.
In each workspace, run a plan that uses mabl Link and confirm that it passes.

Keep the workspace tunnels running until you're confident in the company tunnel. Until you remove them from the environments, you can back out by running mabl link-agents remove-from-environments --company-id {company-id} --tunnel qa-shared --execute.

Remove the workspace tunnels from the environments

Preview the change:
```
mabl link-agents remove-from-environments --company-id {company-id} --all-except qa-shared
```
With --all-except, the command removes every other tunnel from each environment and database connection that lists qa-shared, and leaves the ones that don't list it alone. If an environment in the preview still names a workspace tunnel you expected to remove, it doesn't list qa-shared, for example because someone created it after you added the tunnel. Run the add-to-environments command again to add qa-shared to it, then preview again.