Mount interface

The mount interface securely exposes filesystem locations on the host (via the 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.

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.

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.

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, both subject to Workshop’s validation rules.

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:

$ workshop connections --all

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

This means a source directory is mounted to the target:

$ 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:

$ 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:

$ workshop disconnect ws/mount-sdk:cache --forget
$ workshop refresh ws

See also

Explanation:

Reference: