Data storage

When a URcap container needs to store data (logs, database records, etc.), then it should make use of a URCap mount. These mounts are specified in the manifest.yaml. We call these data storage types “mounts”, because directories from the host is mounted into the container allowing for data to survive reboots and container upgrades. Each showcased mount type is presented along with an example manifest.yaml snippet. A fully fledged example can be found in the corresponding data storage SDK sample.

URcap mount types

A URCap can make use of the following mount types:

1. Persistent

2. Permanent

3. Tmpfs

4. RemovableStorage

1. Persistent mounts

Use a persistent mount if you need data written by your URCap container to survive reboots and upgrades to the URCap itself. If you do not use a persistent mount, then data written by your URCap container will be lost if for whatever reason the container stops running. Note that persistently mounted data is deleted when your URCap is deleted. If you want this data to live on after deletion, then read up on the ‘permanent’ mount type section below.

The following is an example from the SDK sample where a container named data-storage. This data-storage is then given a folder due to the persistent-keyword on the left side of the colon, that will persist after reboots of the robot. Inside the container it is then possible to put files/logs/configurations in /data/persistent which will stay there.

metadata:
    vendorID: universal-robots
    urcapID: persistent-storage-demo
    version: 1.0.0
    #...
artifacts:
    containers:
    - id: data-storage
      image: data-storage:latest
      mounts:
        # example: persistent:/etc/urcap/config
        # example: persistent:/var/log/urcap
        - mount: persistent:/data/persistent
          access: rw

Be aware that the persistent mount obscures already existing data baked into your image. I.e. if you have data already residing at /data/persistent, then this data will appear to be gone.

2. Permanent mounts

A “permanent” mount works like a “persistent” mounts, but extends it with one important difference: Data is not deleted when the associated urcap is deleted.

The following example creates a permanent mount in ‘/app/data’.

...
artifacts:
    containers:
    - id: data-storage
      image: data-storage:latest
      mounts:
        - mount: permanent:/app/data
          access: rw

3. tmpfs mounts

In contrast to persistent mounts, tmpfs mounts are temporary filesystems residing in memory or the host’s swap space. All content in tmpfs is cleared when the container stops, leading to high-speed but non-persistent storage. tmpfs mounts are ideal for storing sensitive information that should not be written to disk or temporary data that doesn’t need to persist. However, note that data in tmpfs mounts is lost during URCapX updates/upgrades.

In this example the container will receive a temporary folder which is located at /data/temporary.

metadata:
    vendorID: universal-robots
    urcapID: tmp-storage-demo
    version: 1.0.0
    #...
artifacts:
    containers:
    - id: data-storage
      image: data-storage:latest
      mounts:
        # example: tmpfs:/usr/local/urcap/tmp
        # example: tmpfs:/tmp
        - mount: tmpfs:/data/temporary
          access: rw

4. Removable Storage

Use the RemovableStorage option if your container needs access to contents of USB drives attached to the robot.

In the following example the contents of an inserted usb stick will be mounted and made accessible at /data/removable/<usb_stick_id>.

metadata:
    vendorID: universal-robots
    urcapID: removable-storage-demo
    version: 1.0.0
    #...
artifacts:
    containers:
    - id: data-storage
      image: data-storage:latest
      mounts:
        # example: RemovableStorage:/etc/container
        # example: RemovableStorage:/mnt
        - mount: RemovableStorage:/data/removable
          access: rw

Data shadowing

Regardless of the volume mount type, data loss can occur when a mount is placed ontop of an existing directory in a container.

When a mount “shadows” a directory with pre-existing data, the data becomes obscured and inaccessible for the duration of the mount. It’s crucial to note that this does not result in permanent data deletion or loss, but from the perspective of applications running inside the container, it seems as though the data has been lost.

To avoid obscuring crucial data, ensure that the target directory for volume mounts is specifically designed for this purpose and does not contain data required while the volume is mounted.