You can use External Data Volumes (EDV) to mount and access data that might exist on external remote file systems.

To access the External Data Volumes (EDV) administration page, go to Admin > External Data Volumes > Data > External Volumes.

External data volumes must be registered with Domino before they can be used.

All registered external data volumes are listed in a standard table, which display the EDV name, type, description, and volume access. In addition, for each registered EDV, the Projects column indicate which projects had added the EDV.

edv admin table

Unless otherwise specified, all the following actions assume you are on the EDV administration page.

Set up Kubernetes PV and PVC

Note

Domino runs on a Kubernetes cluster and EDVs must be backed by an underlying Kubernetes persistent volume (PV). That persistent volume must be bound to a persistent volume claim (PVC) which must be labeled with a key dominodatalab.com/external-data-volume. The value of that key represents the type of external data volume. The supported types are NFS, SMB, and EFS. Finally, the PVC must be created in the Domino compute namespace.

The following are example yaml files for creating PVs and PVCs for each of the supported EDV types.

Note

NFS PV/PVC example

The following is a simple static provisioning example that can be used to create the required PV and PVC. You can provision the PV that refers to the NFS share to expose in Domino using any mechanism appropriate for their environment.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
   name: pvc-nfs
   namespace: YOUR-DOMINO-COMPUTE-NAMESPACE    #change for your deployment
   labels:
      "dominodatalab.com/external-data-volume": "NFS"
spec:
   storageClassName: ""
   accessModes:
   - ReadWriteMany
   resources:
      requests:
         storage: 30Gi
   volumeName: pv-nfs
---
apiVersion: v1
kind: PersistentVolume
metadata:
   name: pv-nfs
spec:
   storageClassName: ""
   accessModes:
   - ReadWriteMany
   capacity:
      storage: 30Gi
   # Optionally explicitly specify a reference to the PVC that will be using this PV
   # Name and namespace must match the PVC created
   claimRef:
      apiVersion: v1
      kind: PersistentVolumeClaim
      name: pvc-nfs
      namespace: YOUR-DOMINO-COMPUTE-NAMESPACE   #change for your deployment
   persistentVolumeReclaimPolicy: Retain
   nfs:
      path: /mnt/export
      server: 10.0.0.26

EFS PV/PVC example

The following is a simple static provisioning example that can be used to create the required PV and PVC. For more detailed configuration information, see the EFS CSI documentation. Only the configuration options supported by the EFS CSI driver can be used.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
   name: pvc-efs
   namespace: YOUR-DOMINO-COMPUTE-NAMESPACE
   labels:
      "dominodatalab.com/external-data-volume": "EFS"
spec:
   storageClassName: ""
   accessModes:
   - ReadWriteMany
   resources:
      requests:
         storage: 30Gi
---
apiVersion: v1
kind: PersistentVolume
metadata:
   name: pv-efs
spec:
   storageClassName: ""
   accessModes:
   - ReadWriteMany
   capacity:
      storage: 30Gi
   # Optionally explicitly specify a reference to the PVC that will be using this PV
   # Name and namespace must match the PVC created
   claimRef:
      apiVersion: v1
      kind: PersistentVolumeClaim
      name: pvc-efs
      namespace: YOUR-DOMINO-COMPUTE-NAMESPACE   #change for your deployment
   persistentVolumeReclaimPolicy: Retain
   csi:
      driver: efs.csi.aws.com
      volumeHandle: <EFS file system id>:/<path>    #the path within the file system is optional

SMB PV/PVC example

The following is a simple static provisioning example that can be used to create the required PV and PVC. For more detailed configuration information, see the SMB CSI documentation. Only the configuration options supported by the SMB CSI driver can be used.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
   name: pvc-smb
   namespace: YOUR-DOMINO-COMPUTE-NAMESPACE
   labels:
      "dominodatalab.com/external-data-volume": "SMB"
spec:
   storageClassName: ""
   accessModes:
   - ReadWriteMany
   resources:
      requests:
         storage: 30Gi
---
apiVersion: v1
kind: PersistentVolume
metadata:
   name: pv-smb
spec:
   storageClassName: ""
   accessModes:
   - ReadWriteMany
   capacity:
      storage: 100Gi
   claimRef:
      apiVersion: v1
      kind: PersistentVolumeClaim
      name: pvc-smb
      namespace: YOUR-DOMINO-COMPUTE-NAMESPACE    #change for your deployment
   persistentVolumeReclaimPolicy: Retain
   csi:
      driver: smb.csi.k8s.io
      nodeStageSecretRef:
         name: SMB-SECRET-NAME
         namespace: NAMESPACE-OF-SMB-SECRET
      volumeAttributes:
         source: //10.0.0.11/Share        #SMB server address and path
      volumeHandle: volume-handle-unique  # must be unique id for the cluster
   mountOptions:
   - dir_mode=0777
   - file_mode=0777
   - vers=3.0

All properly labelled PVCs will be available candidates to register in the Domino EDV administration user interface.

Register external data volumes

To register an EDV with Domino, click Register External Volume on the EDV administration page. This opens the EDV registration wizard which guides you to register the EDV by configuring EDV properties.

Volume

Select the volume type. The supported volume types are NFS, Windows Share(SMB), and EFS. NFS is only supported volume type.

Available Volumes lists all candidate volumes of the selected type. The volume names are those of the backing Kubernetes persistent volume claim (PVC).
Configuration

Configure the volume.
- Required: Name. This field defaults to the selected PVC name, but can be changed. Domino recommends that you name the EDV so that it is recognized by users based on the supporting use case or some organization-defined convention.
- Required: Mount Path. This specifies the relative mount path for the EDV for supported executions. This field defaults to the selected PVC name, but can be changed. This field must be unique to all registered EDVs. There are a few reserved words.
- Mount as read-only. This checkbox specifies whether the EDV is mounted by as read-only or read-write. The default is read-only (selected). This is enforced at the Domino layer. More restrictive access controls at the Kubernetes or NFS layer overrule this setting. For example, if the PVC access mode is set to read only, it does not matter this field allows for read-write; the underlying permission of read only will be enforced.
- Description. Admin defined description for EDV.
Access

Define the volume access.
- Everyone. Allow EDV access to all logged-in users.
- Specific users or organizations. Limit EDV access to specific users and organizations.

Note

View registered external data volume details

To view a registered EDV details, click the Name of the EDV in the admin table.

edv admin view details

Edit registered external data volumes

To edit the details of a registered EDV, go to the end of the row for the entry in the admin EDV table. Then, click the vertical three dots and click Edit.

edv admin edit details

The Edit an External Volume page opens where you can change EDV properties.

edv admin edit details

Unregister external data volumes

To unregister an EDV, go to the end of the row for the entry in the admin EDV table. Then, click the vertical three dots and click Unregister.

edv admin unregister

A confirmation message opens and you can click Unregister to confirm, or click Cancel to cancel the unregistration.

edv admin unregister confirm

Configure censorship

Multiple users collaborating on the same project might not all have the same level of volume access. EDVs added to the project must not be accessible to users without volume access, and under no circumstance will a user without volume access to an EDV be able to mount that EDV in a supported execution. However, Domino offers options to manage the visibility of the EDV in the application with two levels of censorship. The levels of censorship allow you to choose between security and discoverability needs.

Full censorship. Only the existence of any inaccessible EDV is made known to the user; the quantity and any metadata (such as name or description) is not made known to the user. This is the level for those that want the highest level of security.
Inactive censorship. Inaccessible EDVs are made known to the user; the EDV metadata (such as name and description) is made known to the user. This is the level that promotes discoverability. With discoverability, users can escalate to you to gain volume access. This is the default level of censorship.

The level of censorship is configured by a feature flag: ShortLived.ExternalDataVolumesFullCensor.

Key: ShortLived.ExternalDataVolumesFullCensor

Value: boolean

Default: false

When this is true, the censorship level is full censorship.

When this is false, the censorship level is inactive