Use pre-existing network storage

Use the pre-existing-network-storage module to define and mount file systems that already exist outside of your current deployment group. This module connects your Compute Engine instances to storage that was created previously or is managed independently.

This module supports the following file system types:

For a complete list of inputs and outputs, see the pre-existing-network-storage module in the Cluster Toolkit GitHub repository.

Before you begin

Before you begin, verify that you meet the following requirements:

  • You have installed and configured Cluster Toolkit. For installation instructions, see Set up Cluster Toolkit.
  • You have an existing cluster blueprint. You can use and modify an existing blueprint or create one from scratch. For a working example of a blueprint configured for the pre-existing-network-storage module, see the examples/machine-learning/a4x-maxgpu-4g-metal/a4xmax-bm-slurm-blueprint.yaml file. For more information about creating and customizing blueprints, see Cluster blueprint.
  • To view a complete list of blueprints, go to the Cluster blueprint catalog page.
  • The storage system must already be provisioned and accessible.
  • You must know the server_ip (or equivalent identifier such as a host name) and the remote_mount path (export or bucket name) before deployment.

Required roles

To get the permissions that you need to mount pre-existing network storage, ask your administrator to grant you the following IAM roles on your project:

  • Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
  • Service Account User (roles/iam.serviceAccountUser)
  • If using Cloud Storage: Storage Object Viewer (roles/storage.objectViewer) - the source bucket
  • If using Google Cloud Managed Lustre: Managed Lustre Viewer (roles/lustre.viewer) - the Managed Lustre instance

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Mount an NFS share

To mount a standard NFS share, provide the server IP address and the remote export path.

- id: homefs
  source: modules/file-system/pre-existing-network-storage
  settings:
    server_ip: SERVER_IP
    remote_mount: REMOTE_MOUNT
    local_mount: /home
    fs_type: nfs

Replace the following:

  • SERVER_IP: the IP address of your NFS server, such as 10.1.2.3.
  • REMOTE_MOUNT: the exported path or directory on the NFS server, such as nfsshare.

Mount a Cloud Storage bucket

To mount a Cloud Storage bucket, set the fs_type field to a value of gcsfuse. The remote_mount setting must be the bucket name, without the gs:// string.

We recommend that you use the implicit_dirs mount option to treat object paths as directories, which is useful for files that are created by other sources.

- id: data-bucket
  source: modules/file-system/pre-existing-network-storage
  settings:
    remote_mount: my-bucket-name
    local_mount: /data
    fs_type: gcsfuse
    mount_options: defaults,_netdev,implicit_dirs

Mount a Lustre file system

You can mount both generic self-managed Lustre and Google Managed Lustre instances.

Self-managed Lustre

For self-managed Lustre, provide the Metadata Server Network ID (MGS NID) in the server_ip field, including the @tcp suffix.

- id: lustrefs
  source: modules/file-system/pre-existing-network-storage
  settings:
    fs_type: lustre
    server_ip: 192.168.227.11@tcp
    local_mount: /scratch
    remote_mount: /exacloud

Managed Lustre configuration

For Managed Lustre, set the fs_type field to a value of managed_lustre. Supported operating systems include Rocky Linux 8 and Ubuntu 22.04.

- id: lustrefs
  source: modules/file-system/pre-existing-network-storage
  settings:
    fs_type: managed_lustre
    server_ip: 192.168.227.11@tcp
    local_mount: /scratch
    remote_mount: /mg_lustre

Mount the storage

The Cluster Toolkit offers two methods for mounting network storage: automatic mounting with module relationships or manual mounting with output runners.

Automatic mounting

When you connect the pre-existing-network-storage module to a compatible compute module (such as a Slurm partition or VM group) by using the use keyword, Cluster Toolkit automatically handles client installation and mounting.

For a complete list of supported modules, see the compatibility matrix section on GitHub.

Manual mounting

If you need to mount the storage manually, such as in a custom startup script, then you can use the module's client_install_runner and mount_runner outputs.

The module provides these runners for the following fs_type values:

What's next