<a id="exp-mount-interface"></a>

# Mount interface

<!-- @artefact mount interface -->

The mount interface securely exposes filesystem locations
on the host (via the [system SDK](https://ubuntu.com/workshop/docs//explanation/sdks/concepts.md#exp-system-sdk) only) or in the workshop
by mounting them inside the workshop.

By using the interface,
the SDK publisher enables the use of the mount mechanism in the workshop;
a host location also allows persisting data outside the workshop.

<!-- @artefact host data source -->

The interface defines a target directory inside the workshop,
to which a source directory is mounted at runtime.
Typically, it would provide resources to be consumed by the SDK,
accumulated over time or created
when the **workshop launch** or **workshop refresh** commands run:

- The slot is the provider,
  indicating that any data placed in its source directory
  can be used by a workshop via a plug.
- The plug is the consumer,
  indicating that the data will be available at the target directory,
  where the SDK, or the user presumably expects it.

<a id="exp-mount-plug"></a>

## Mount interface plug

An essential element here is the mount interface plug,
which is declared in the SDK definition.

A basic structure would include the name of the plug itself,
the interface (`mount`)
the intended target path inside the workshop (`workshop-target`)
and, optionally, whether the mount should be read-only (`read-only`).

**Workshop** will create the target path if it doesn’t exist.
Plugs may customize the permissions (`mode`) and ownership (`uid`, `gid`)
of any directories created.

Defining the plug in an SDK designates the target directory inside the workshop;
a directory on the host system that **Workshop** will create at runtime
will be mounted to it.

This allows the workshops using this SDK to use the host directory
(which **Workshop** allocates automatically and doesn’t expose otherwise)
to persist the files placed there from inside the workshop
in the host filesystem when the workshop stops.

<a id="exp-mount-slot"></a>

## Mount interface slot

To let SDKs in a workshop access the host filesystem,
**Workshop** provides a mount interface slot
that multiple mount interface plugs can access.

When the SDK is installed at runtime during launch and refresh operations,
**Workshop** checks the following for each plug that targets the slot:

- The plug can be installed.
- The plug can be auto-connected
  (for `mount`, it’s a yes).
- The `workshop-target` directory already exists in the workshop.

If the plug passes the checks, it is connected.

## Connection

The interface is connected automatically at launch or refresh
if the plug can be matched to the slot by its name
or via a `connections` entry in the [definition](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition),
both subject to **Workshop**’s
[validation rules](https://ubuntu.com/workshop/docs//explanation/interfaces/concepts.md#exp-interfaces-validation).

Establishing a connection means the source directory created by **Workshop**
is mounted to the target directory inside the workshop.
The source directory can be created:

- At a designated path inside the workshop,
  which needs a slot with `workshop-source` set
- At an internal location on the host,
  which **Workshop** assigns if no slot is set explicitly

If the directory is created on the host,
its contents are preserved between operations such as
**workshop refresh**, **workshop start**,
and **workshop stop**.

After the workshop has started,
the **workshop connect** and **workshop disconnect** commands
can be used to manage the connection manually.

To check if the interface is connected:

<!-- @artefact workshop connections -->
```console
$ workshop connections --all

  INTERFACE  PLUG                SLOT    NOTES
  ...
  mount      ws/mount-sdk:cache  :cache  manual
```

This means a source directory is mounted to the target:

<!-- @artefact workshop info -->
```console
$ workshop info ws

  name:     ws
  base:     ubuntu@22.04
  project:  /home/user/workshops/ws
  status:   ready
  notes:    -
  sdks:
    mount-sdk:
      tracking:   latest/edge
      installed:  2022-03-04  (1)
      mounts:
        cache:
          host-source:      .../8584e571/ws/mount/mount-sdk/cache
          workshop-target:  /home/workshop/.local/cache
```

Here, the source is set to an internal location (`...`)
that **Workshop** maintains on the host filesystem;
the SDKs can’t set host locations explicitly for security reasons,
but there’s a way to do it manually.

## Remount

The **workshop remount** command sets a new source directory on the host
for the target directory inside the workshop:

<!-- @artefact workshop remount -->
```console
$ workshop remount ws/mount-sdk:cache ~/.local/cache/
```

First, the remount operation is attempted atomically;
this usually succeeds if the new source is either a nonexistent directory
or an empty directory on the same filesystem as the current source.
Otherwise, the remount only occurs if the workshop has been stopped earlier,
which prevents data corruption.

To reset a remounted plug to its default source location,
use `workshop disconnect` with the `--forget` option,
then refresh the workshop:

<!-- @artefact workshop disconnect -->
<!-- @artefact workshop refresh -->
```console
$ workshop disconnect ws/mount-sdk:cache --forget
$ workshop refresh ws
```

## See also

Explanation:

- [Interface concepts](https://ubuntu.com/workshop/docs//explanation/interfaces/concepts.md#exp-interface-concepts)
- [Plugs and slots](https://ubuntu.com/workshop/docs//explanation/interfaces/concepts.md#exp-plugs-slots)
- [SDK definition](https://ubuntu.com/workshop/docs//explanation/sdks/concepts.md#exp-sdk-definition)
- [Workshop definition](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition)

Reference:

- [workshop connect](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-connect)
- [workshop connections](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-connections)
- [workshop disconnect](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-disconnect)
- [workshop launch](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-launch)
- [workshop refresh](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-refresh)
- [workshop remount](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-remount)
- [workshop start](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-start)
- [workshop stop](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-stop)