SSH Access¶
SSH is a fully supported way to administer Qumulo cluster nodes, including running the qq CLI. This page shows how to get a shell on a node deployed by this provider, and covers the per-cloud details: which key gets you in, which user you log in as, and how to reach the provisioner VM during cluster operations.
Get onto a node¶
Node IP addresses are already in your Terraform state. The qumulo_filesystem_aws, qumulo_filesystem_azure, and qumulo_filesystem_gcp resources all expose a computed primary_ips attribute:
Then connect:
Set ec2_key_pair on the qumulo_filesystem_aws resource at deploy time; the key pair is attached to every cluster node.
The ubuntu username is correct for the default AMI (the latest Canonical Ubuntu 24.04) and any Ubuntu AMI. If you set ami_id to a RHEL AMI, use ec2-user instead.
No key pair? Use Session Manager. The provider attaches the AmazonSSMManagedInstanceCore policy to the cluster node role automatically, so SSM works out of the box, without a key pair and without opening port 22. You need AWS CLI v2 with the Session Manager plugin, and your IAM principal must be allowed to call ssm:StartSession on the instance:
You land as ssm-user. Switch to the node's primary user (the one with the qq environment) with sudo su - ubuntu (or sudo su - ec2-user on RHEL AMIs).
Cluster node VMs are created with the admin user qumulo. If you set ssh_public_key on the qumulo_filesystem_azure resource, the matching private key gets you in:
Password authentication is also enabled on cluster node VMs: log in as qumulo with the resource's admin_password value. This is handy when the optional ssh_public_key was never set, though key authentication is the better default.
The provider does not inject SSH keys on GCP. Access is governed by your project's standard mechanisms (instance metadata keys or OS Login), so gcloud compute ssh works the way it does for any other instance in the project:
gcloud provisions a key for your account via your project's mechanism. If you already manage keys yourself, plain ssh <user>@<node-internal-ip> works too. Nodes run the public Ubuntu 24.04 LTS image (ubuntu-os-cloud/ubuntu-2404-lts-amd64) unless you pinned a custom image.
These are your own servers, so you already hold the credentials: the same ip, ssh_user, and key or password you configured in the connection profile's nodes block (see provider configuration). ssh_user defaults to root and ssh_port to 22:
This applies to both qumulo_filesystem_baremetal and qumulo_filesystem_edge_baremetal. Installing Qumulo Core does not change your SSH access; the provider provisions over the same SSH path you use.
You need a network path to the nodes
The provider itself never attaches public IPs to cluster nodes, so in the typical private-subnet deployment you reach them over VPN, VPC/VNet peering, a bastion or jump host, or a workstation inside the network. The provider opens port 22 to every CIDR in allow_cidrs (AWS security group, Azure NSG, GCP firewall rule), so your source IP must be covered by that list. Two per-cloud exceptions:
- On AWS with Bring-your-own security groups, ingress is whatever your own security group allows.
- On GCP the cluster subnet's own CIDR is always allowed in addition to
allow_cidrs.
Finding your nodes¶
Every cloud resource is named from deployment_unique_name, a computed attribute of the form <deployment_name>-<random suffix>. deployment_name defaults to the lowercased name. Cluster nodes are named <deployment_unique_name>-node-<n>, where n is 1, 2, 3, ... on new clusters. Deployments created by older provider versions may use 6-character alphanumeric suffixes instead. Read the value from state:
Cluster nodes carry a Qumulo-Cluster tag whose value is the deployment unique name:
VMs live in the resource group you set via the resource's resource_group_name:
az vm list --resource-group <resource-group> --show-details \
--query "[?starts_with(name, '<deployment_unique_name>-node-')].{Name:name, IP:privateIps}" \
--output table
If you configured a custom naming block with a vm_name template, filter on your template's expansion instead of the default -node- pattern.
Instances carry a qumulo-deployment label whose value is the deployment unique name (the provisioner, when present, carries it too):
Nothing to discover: node IPs are exactly the ip entries in your connection profile's nodes block.
Provisioner VM¶
Cluster operations (create, scale, node replacement, configuration updates) run on a temporary provisioner VM named <deployment_unique_name>-provisioner. You rarely need a shell on it, but it is the right place to watch a long-running operation from the inside. Bare metal deployments have no provisioner VM; provisioning runs over SSH to your nodes directly.
The provisioner instance is launched without an EC2 key pair, so use Session Manager (its IAM role also has AmazonSSMManagedInstanceCore):
aws ec2 describe-instances \
--filters "Name=tag:Name,Values=<deployment_unique_name>-provisioner" \
"Name=instance-state-name,Values=running" \
--query "Reservations[].Instances[].InstanceId" --output text
aws ssm start-session --target <provisioner-instance-id>
The instance terminates itself when the run completes, so it is only findable while an operation is running.
The provisioner's admin user is adminuser, not qumulo. When ssh_public_key is set on the resource, the same key gets you in and password authentication is disabled. Without a key, log in with the resource's admin_password:
az vm show --resource-group <resource-group> \
--name <deployment_unique_name>-provisioner --show-details \
--query "{Name:name, IP:privateIps}" --output table
ssh -i <keyfile> adminuser@<provisioner-private-ip>
The VM deallocates itself when the run completes, and the provider deletes and recreates it on the next operation.
Troubleshooting¶
| Symptom | Likely cause |
|---|---|
Permission denied (publickey) |
Wrong username for the AMI (ubuntu for Ubuntu, ec2-user for RHEL), or the private key does not match the ec2_key_pair set at deploy. |
Connection timed out on port 22 |
Your source IP is not in allow_cidrs, a NACL is blocking traffic, or you have no route to the private subnet. |
SSM TargetNotConnected |
The SSM agent finishes registering about a minute after boot. Wait and retry. If it persists, confirm the instance still has its IAM instance profile. |
SSM AccessDeniedException |
Your local IAM principal lacks ssm:StartSession on the instance ARN. |
| Symptom | Likely cause |
|---|---|
Permission denied (publickey) |
Wrong username (qumulo for cluster nodes, adminuser for the provisioner), or the private key does not match the ssh_public_key set at deploy. |
Connection timed out |
Your source IP is not in allow_cidrs, the NSG is blocking, there is no route from your source to the VNet, or the VM is stopped. |
| Cannot reach the node from my laptop | You need a VPN, peered VNet, Azure Bastion, or jump host. The provider does not create any of these. |
| Key works for cluster nodes but not the provisioner (or the reverse) | Username mismatch: cluster nodes use qumulo, the provisioner uses adminuser. |
| Symptom | Likely cause |
|---|---|
Permission denied (publickey) |
Your key is not on the instance. Retry with gcloud compute ssh, which provisions one, or check your project's OS Login / metadata key setup. |
Connection timed out |
Your source IP is not in allow_cidrs, or you have no route to the VPC's internal IPs (nodes have no external IPs). |
| Symptom | Likely cause |
|---|---|
Permission denied |
The credentials differ from the ssh_user plus key or password in the connection profile's nodes block. |
| Host key verification failed | The node was reinstalled or its host key changed; if you pinned ssh_host_key in the profile, update it. |