Configuring a Portal Relationship Between Two Qumulo Clusters

This section explains how to use the Cloud Data Fabric functionality in Qumulo Core by creating a spoke portal on one cluster, proposing a portal relationship to another cluster (which creates the hub portal), and authorizing the relationship by using the qq CLI.

Configuring a Portal Relationship Between Two Qumulo Clusters

This section explains how to configure a portal relationship between two Qumulo clusters by using the qq CLI.

Important

Before you begin to implement Cloud Data Fabric in your organization, we strongly recommend reviewing the How Portal Relationships between Qumulo Clusters Enable Cloud Data Fabric in Qumulo Core and Known Limits sections.
For any questions, contact the Qumulo Care team.

Prerequisites

Two clusters with the same version of Qumulo Core
Network connectivity on TCP port 3713 from the cluster that shares a portion of its file system for the spoke portal root directory to the cluster that will share a portion of its file system for the hub portal root directory
PRIVILEGE_PORTAL_GLOBAL_READ for viewing the status for a hub portal or spoke portal and retrieving general portal information
Spoke portals
- PRIVILEGE_PORTAL_SPOKE_EVICT: Control automatic cache management for active spoke portals by configuring a free threshold
- PRIVILEGE_PORTAL_SPOKE_READ: View the status of a single spoke portal
- PRIVILEGE_PORTAL_SPOKE_WRITE: Create a spoke portal and propose a relationship with a hub portal
Hub portals
- PRIVILEGE_PORTAL_HUB_READ: View the status of a specific hub portal
- PRIVILEGE_PORTAL_HUB_WRITE: Authorize a hub portal and confirm a relationship with a spoke portal

Important

If both of the clusters use Active Directory, they must be joined to the same domain or each cluster must be joined to Active Directory domains that have a two-way trust relationship to each other.
In Qumulo Core 7.5.0.1 to 7.5.1, it is possible for a Qumulo cluster to host only up to 32 hub portals or up to 32 spoke portals.

Step 1: Create the Spoke Portal

This section explains how to create the spoke portal on one cluster and propose the creation of a portal relationship to another cluster (which creates the hub portal).

On one cluster, choose a location for the spoke portal root directory. For example, /remote/projects.
To propose an initial portal relationship, run the qq portal_create command and specify the spoke portal root directory, the IP address of the proposed hub portal host cluster, and the proposed hub portal root directory on that cluster. For example:
```
qq portal_create \
  --spoke-root /remote/projects \
  --hub-address 203.0.113.0 \
  --hub-root /projects
```
The spoke portal enters the Pending portal relationship state. The following is example output.
```
ID  State    Status    Type  Spoke Root        Hub Host     Hub Portal ID
==  =======  ========  ====  ================  ===========  =============
2   Pending  Inactive  RW    /remote/projects  203.0.113.0  4
```
Hub Portal ID 4 is the ID that the hub portal host cluster allocates for this portal relationship. You can use it to authorize the relationship on the hub portal host cluster as described later.
Note
- We recommend using floating IP addresses.
- Qumulo Core doesn't support fully qualified domain names (FQDNs) for this operation.
- Portal IDs are unique within each cluster. It isn't possible to use a portal ID from a spoke portal to identify the other side of the relationship, or the other way around.
When Qumulo Core can’t establish a connection from the spoke portal host cluster to the hub portal host cluster, it displays an error message. Try re-establishing the portal relationship.

When the portal relationship is established, both spoke portal and hub portal enter the Pending portal relationship state.

Note
In this state, the spoke portal root directory is empty and Qumulo Core doesn’t transfer any data until the hub portal authorizes the portal relationship.

To check the status of a cluster, run the qq portal_list command. The following is example output.

From the spoke portal host cluster

Role   ID  Type  State    Status    Peer         Root Count
=====  ==  ====  =======  ========  ===========  ==========
Spoke  2   RW    Pending  Inactive  203.0.113.0  1

From the hub portal host cluster

Role  ID  Type  State    Status    Peer         Root Count
====  ==  ====  =======  ========  ===========  ==========
Hub   4   RW    Pending  Inactive  203.0.113.1  1

Step 2: Authorize the Portal Relationship

This section explains how to authorize the portal relationship from the hub portal to the spoke portal.

Caution
This action makes both clusters in the portal relationship unavailable for less than 30 seconds while the systems reconfigure.

To find the hub portal ID, run the qq portal_list command.

Tip
To retrieve portal configuration information, run the qq portal_list_spokes and qq portal_list_hubs commands.
To authorize the proposed portal relationship, run the qq portal_authorize_hub command and specify the hub portal ID and the IP address that the current cluster can use to contact the cluster that proposed the relationship. For example:
```
qq portal_authorize_hub \
  --id 4 \
  --spoke-address 203.0.113.1
```
Note
Portal IDs are unique within each cluster. It isn't possible to use a portal ID from a spoke portal to identify the other side of the relationship, or the other way around.

The following is example output.
```
ID  State       Status  Hub Root   Spoke Host   Spoke Name  Spoke Type
==  ==========  ======  =========  ===========  ==========  ==========
4   Authorized  Active  /projects  203.0.113.1  qfsd-edge   RW
```
After a few seconds, the spoke portal enters the Authorized portal root directory state as well. You can now use the spoke portal root directory.

Configuring Additional Spoke Portal Root Directories for an Existing Portal Relationship

In Qumulo Core 7.6.2 (and higher), it is possible to configure up to 32 spoke portal root directories for each Qumulo cluster, for each portal relationship. This section explains how to configure an additional spoke portal root directory, how to remove access from a hub portal root directory, and how to remove a spoke portal root directory by using the qq CLI.

Tip
Configuring an additional spoke portal root directory can be useful when it is necessary to provide access to individual directories rather than the contents of the entire file system on the hub portal host cluster.

Prerequisites

PRIVILEGE_PORTAL_SPOKE_WRITE for modifying a spoke portal
PRIVILEGE_PORTAL_HUB_WRITE for modifying a hub portal

To Configure an Additional Spoke Portal Root Directory

For portal relationships in the Pending or Accepted state, you can configure an additional spoke portal root directory by proposing the additional spoke portal root directory and then authorizing the corresponding hub portal root directory.

To propose the additional spoke portal root directory from the spoke portal host cluster, run the qq portal_propose_spoke_root command and specify the portal ID, the spoke portal root directory path, and the hub portal root directory path. For example:

qq portal_propose_spoke_root \
  --id 2 \
  --spoke-root-path /remote/archive \
  --hub-root-path /archive

The following is example output.

Role   ID  Type  State     Status  Peer
=====  ==  ====  ========  ======  ==========
Spoke  2   RW    Accepted  Active  203.0.113.0

Root State    Local Path         Remote ID
============  =================  ==============================
Authorized    /remote/projects/  107592715270601080910970355714
Unauthorized  /remote/archive/   107592715270601080910970355715

To authorize the corresponding hub portal root directory from the hub portal host cluster, run the qq portal_authorize_hub_root command and specify the portal ID and the hub portal root directory path. For example:

Note
It is possible to use an existing hub portal root directory which you have already authorized. In this scenario, the additional spoke portal root directory will be in the Authorized state immediately.
```
qq portal_authorize_hub_root \
  --id 4 \
  --hub-root-path /archive
```
The following is example output.
```
Role  ID  Type  State     Status  Peer
====  ==  ====  ========  ======  ===========
Hub   4   RW    Accepted  Active  203.0.113.1

Root State  Local Path
==========  ==========
Authorized  /projects/
Authorized  /archive/
```

To Remove Access from a Hub Portal Root Directory

Run the qq portal_deny_hub_root command and specify the portal ID and the hub portal root directory path.

Important
It isn’t possible to use the portal_deny_hub_root command to restrict access to a subdirectory of a hub portal root directory. For example, if hub portal root directories are nested, removing access from a child hub portal root directory doesn’t deny access from the corresponding parent hub portal root directory.

For example:

qq portal_deny_hub_root \
 --id 4 \
 --hub-root-path /archive

Qumulo Core removes the authorization from the hub portal root directory. The following is example output.

Role  ID  Type  State     Status  Peer
====  ==  ====  ========  ======  ===========
Hub   4   RW    Accepted  Active  203.0.113.1

Root State    Local Path
============  ==========
Unauthorized  /archive/
Authorized    /projects/

To Remove a Spoke Portal Root Directory

Run the qq portal_delete_spoke_root command and specify the portal ID and the spoke portal root directory path.

Important

This operation doesn't affect any data on the hub portal host cluster, any unsynchronized data in the spoke portal root directory, or the portal relationship.
To restore the spoke portal root directory, you can propose a new spoke portal root directory.
When there are no more spoke portal root directories that correspond to a particular hub portal root directory, Qumulo Core removes that hub portal root directory from the portal relationship automatically.

For example:

qq portal_delete_spoke_root \
 --id 2 \
 --spoke-root-path /remote/archive

Qumulo Core removes access to the hub portal root directory for any spoke portal host cluster clients. The following is example output.

Role   ID  Type  State     Status  Peer
=====  ==  ====  ========  ======  ==========
Spoke  2   RW    Accepted  Active  203.0.113.0

Root State    Local Path         Remote ID
============  =================  ==============================
Authorized    /remote/projects/  107592715270601080910970355714

Deleting a Portal Relationship Between Two Qumulo Clusters

When you delete the spoke portal and the hub portal (in any order), the portal relationship is deleted completely. This section explains how to delete a portal relationship between two Qumulo clusters by using the qq CLI.

Caution
This action makes both clusters in the portal relationship unavailable for less than 30 seconds while the systems reconfigure.

Prerequisites

A spoke portal or hub portal in any portal relationship state
PRIVILEGE_PORTAL_SPOKE_WRITE for deleting a spoke portal
PRIVILEGE_PORTAL_HUB_WRITE for deleting a hub portal

Step 1: Delete the Spoke Portal

You can initiate the deletion of a spoke portal in the Pending or Accepted portal relationship state. This section explains how to delete the spoke portal from a portal relationship.

Caution
When you delete a spoke portal, all synchronized changes remain on the hub portal and all unsynchronized changes on the spoke portal are lost.

To find the spoke portal ID, run the qq portal_list command. The following is example output.

Role   ID  Type  State     Status  Peer         Root Count
=====  ==  ====  ========  ======  ===========  ==========
Spoke  2   RW    Accepted  Active  203.0.113.0  1

To initiate the deletion of the spoke portal, run the qq portal_delete_spoke command and specify the spoke portal ID. For example:
```
qq portal_delete_spoke --id 2
```
The relationship becomes read-only and enters the Deleting state. Qumulo Core synchronizes any outstanding changes from the spoke portal to the hub portal and then removes the portal relationship from each cluster.
To monitor the deletion progress, run the qq portal_get_spoke command and specify the spoke portal ID. For example:
```
qq portal_get_spoke --id 2
```
The following is example output.
```
Role   ID  Type  State     Status  Peer
=====  ==  ====  ========  ======  ===========
Spoke  2   RO    Deleting  Active  203.0.113.0

Root State  Local Path         Remote ID
==========  =================  ==============================
Authorized  /remote/projects/  107592715270601080910970355715
```
When the synchronization process is complete and the spoke portal configuration is removed, Qumulo Core begins to reclaim the spoke portal’s cluster capacity in the background.

Note
A spoke portal with connectivity issues receives the Degraded status, which in turn can cause the deletion of a portal relationship to stall in the Deleting state. If it isn’t possible to restore connectivity between portals, you can run the qq portal_get_spoke command with the --force flag to delete a spoke portal with any status and in any state.

Step 2: Delete the Hub Portal

You can delete a hub portal in either the Pending or Accepted portal relationship state.

Caution
This action makes the spoke portal root directory and all cached data inaccessible.

To find the hub portal ID, run the qq portal_list command. The following is example output.

Role  ID  Type  State     Status  Peer         Root Count
====  ==  ====  ========  ======  ===========  ==========
Hub   4   RW    Accepted  Active  203.0.113.1  1

To delete the hub portal, run the qq portal_delete_hub command and specify the hub portal ID. For example:
```
qq portal_delete_hub --id 4
```
The relationship becomes read-only and enters the Deleting state. Qumulo Core synchronizes any outstanding changes from the spoke portal to the hub portal and then removes the portal relationship from each cluster.

Qumulo Core deletes the hub portal without affecting any of the data on the hub portal host cluster.
To monitor the deletion process, run the qq portal_get_hub command and specify the hub portal ID. For example:
```
qq portal_get_hub --id 4
```
The following is example output.
```
Role  ID  Type  State     Status  Peer
====  ==  ====  ========  ======  ===========
Hub   4   RO    Deleting  Active  203.0.113.1

Root State  Local Path
==========  ===========
Authorized  /projects/
```
Note
A spoke portal with connectivity issues receives the Degraded status, which in turn can cause the deletion of a portal relationship to stall in the Deleting state. If it isn’t possible to restore connectivity between portals, you can run the qq portal_get_spoke command with the --force flag to delete a spoke portal with any status and in any state.

Configuring a Portal Relationship Between Two Qumulo Clusters