---
myst:
  html_meta:
    "description lang=en": "How to restrict Kasm Workspaces to a specific Docker network. "
    "keywords": "Kasm, How to, How-to, Docker, Networking"
    "property=og:locale": "en_US"
---
```{title} Restricting Workspaces to Docker Networks
```

# Restricting Workspaces to Docker Networks

Workspaces allows the administrator to restrict certain Docker workspace images to only provision on specified custom docker networks.
This may be useful if there is a need to use specialized networking such as [macvlan](https://docs.docker.com/network/macvlan/)/[ipvlan](https://docs.docker.com/network/ipvlan/) or {doc}`Bridged Network Source NAT <bridged_network_source_nat>`.
But, it is also useful to provision sessions on groups of Agents to achieve a more simple multi-enclave architecture similar
to what can be accomplished with the use of multiple {doc}`Deployment Zones <../guide/zones/deployment_zones>` or with
Agents that have certain characteristics (e.g specialized hardware) that are helpful to be grouped and associated with 
certain workspace images. 


In this guide we will demonstrate how to:

1. Create custom docker networks on Agents
2. Configure an image to use one or more custom networks
3. Allow the user to select a network at runtime


## Architecture

For this example, we are using in multi-server deployment, with a single webapp, and 4 Agents,
each in different enclaves.

```{figure} /images/docker_networks/architecture.png
:align: center
**Multi Server Network Architecture**
```

## Creating Custom Networks

Workspaces installs a customer bridged docker network named `kasm_default_network`. By default, all sessions are created
on this network. For this example, we will create an additional custom bridged docker network that represents the target
enclave.

1. SSH to the desired Agent.

2. Create a custom docker network.

```Bash
sudo docker network create z_enclave_2
```


```{note}
The docker network names used in this example are intentionally prefixed with {code}`z_` . Due to a quirk
{code}`docker` will choose the default route for the container based on the name of the docker network ordered
alphabetically. We name these custom networks accordingly so that they won't cause interruptions with the Kasm
service containers or user workflow.
```

3. Repeat this step for each Agent. In our example, creating the `z_enclave_2` network on all the Agents in enclave 2
and `z_enclave_3` on all the Agents in enclave 3.
   
## Workspace Configuration

1. Log into the Workspaces UI as an admin.
2. Select **Workspaces** -> **Workspaces**.
3. Click **Edit** next to the desired Workspace from the arrow menu (e.g Chrome).
4. Check **Restrict Image to Docker Network** and add the custom networks (e.g `z_enclave_2` and `z_enclave_3`). Note.
   Custom networks will appear in this list a few minutes after they are created on an active Agent.
5. Check **Allow Network Selection**. This will allow the user to choose from the listed networks when they launch a session.


```{figure} /images/docker_networks/workspace_configuration.webp
:align: center
**Workspace Configuration**
```

6. Click **Save**. 


## Launching the Workspace

1. From the Workspaces launcher, click on the previously modified Workspace. A dropdown will appear with a list of the networks defined.
2. Select the desired network and launch the session. Selecting **Auto** will provision the session on any Agent with one of the previously specified networks.


```{figure} /images/docker_networks/launch.webp
:align: center
**Network Selection**
```