External Data Volumes


Overview

You can access the External Data Volumes (EDV) administration screen by going to the Domino administration page and navigating to External Data Volumes: Data -> External Volumes.

External data volumes must be registered with Domino before they can be used. All registered external data volumes appear in a standard table, which display the EDV name, type, description, and volume access (see Volume Properties). 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.


Setting up Kubernetes PV and PVC

Note

Set up of Kubernetes persistent volumes (PV) and persistent volume claims (PVC) must be done by a Kubernetes administrator.

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. Currently, the supported types are NFS, SMB, and EFS. Finally, the PVC must be created in the Domino compute namespace.

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

Note

Remember to adjust the Domino compute namespace and PVC names appropriately before using the examples.

NFS PV/PVC Example

Below is a simple static provisioning example that can be used to create the required PV and PVC. Administrators are free to 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

Below is a simple static provisioning example that can be used to create the required PV and PVC. For more detailed configuration information, please refer to 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

Below is a simple static provisioning example that can be used to create the required PV and PVC. For more detailed configuration information, please refer to 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.


Registering external data volumes

To register an EDV with Domino, click the Register External Volume button on the upper right hand size of the EDV administration page. This will open a modal with the EDV registration wizard. The wizard will guide administrators to registering the EDV by configuring various EDV properties (see Volume Properties).

  1. Volume

    The first step in the wizard is to select the volume type. The current supported volume types are NFS, EFS, and Windows Share(SMB).

    The Available Volumes list will show all candidate volumes of the selected type. The name of these volumes is the name of the backing Kubernetes persistent volume claim (PVC).

    edv-admin-register-volume

  2. Configuration

    The second step in the wizard is to configure the volume.

    edv-admin-register-configuration

    • Name. (Required). This field will default to the selected PVC name that was selected, but can be changed. A good practice is to name EDV such that it is recognized by users based on the supporting use case or some organization defined convention.
    • Mount Path. (Required). This specifies the relative mount path for the EDV for supported executions. This field will default to the selected PVC name that was selected, but can be changed. This field must be unique to all registered EDVs. There are a few reserved words. See Volume Properties.
    • Mount as read-only. This checkbox specifies the mount type—whether the EDV is mounted by as read-only or read-write. Default is read-only (checked). Note that 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.
  3. Access

    The third step in the wizard is to define the volume access. See Volume Properties and Authorization.

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

    edv-admin-register-access

Note

Regardless of the setting here, Domino Administrators (SysAdmin) will always be able to access any external data volume.

Viewing registered external data volume details

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

edv-admin-view-details


Editing registered external data volumes

To edit the details of a registered EDV, click on the vertical three dots on the right-hand side of its entry in the admin EDV table. This will expose the Edit action. Click Edit to edit the EDV details.

edv-admin-edit-details

A modal with editable fields appear where users can change EDV properties.

edv-admin-edit-details-modal


Unregistering external data volumes

To unregister an EDV, click on the vertical three dots on the right-hand side of its entry in the admin EDV table. This will expose the Unregister action. Click Unregister to unregister the EDV.

edv-admin-unregister

A confirmation modal appears where users can confirm the unregistration by clicking Unregister, or cancel out of the operation altogether by clicking Cancel.

edv-admin-unregister-confirm


Configuring censorship

Multiple users collaborating on the same project may not all have the same level of volume access. EDVs added to the project should 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, we offer options to manage the visibility of the EDV in the user interface with two levels of censorship. The levels of censorship allow administrators to choose between security and discoverability needs.

  • Full censorship. Only the existence of any inaccessibe 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 Domino administrators to gain volume access. This is the default level of censorship.

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


KeyShortLived.ExternalDataVolumesFullCensor
Value: boolean
Default: false
When this is true, the censorship level is full censorship.
When this is false, the censorship level is inactive censorship.