Deploying Cloud Native Qumulo on AWS with the Qumulo Terraform Provider

This section explains how to deploy Cloud Native Qumulo (CNQ) on AWS by preparing your infrastructure, environment, and authentication; deploying and configuring your Qumulo cluster; mounting the Qumulo file system; and performing post-deployment actions such as adding and removing nodes

For an overview of CNQ on AWS, its prerequisites, and limits, see How Cloud Native Qumulo Works.

Prerequisites

This section explains the prerequisites to deploying CNQ on AWS.

Qumulo Core

• Deployment Version: This deployment requires Qumulo Core 7.9.2 (or higher), which includes the required Ubuntu kernel and software upgrades and fixes.

  Tip
  To deploy the latest release, leave the cluster_version variable empty.

• Metrics: To allow your Qumulo cluster to report metrics to Qumulo, your AWS VPC must have outbound Internet connectivity through a NAT gateway or a firewall. Your cluster shares no file data during this process.

  Important
  Connectivity to the following endpoints is required to successfully deploy a Qumulo cluster and form a quorum:

  • api.missionq.qumulo.com
  • api.nexus.qumulo.com

AWS

• VPC: Configure your VPC to use the S3 gateway VPC endpoint, attached to the route table that serves your cluster subnet.

  Important
  It isn’t possible to complete deployment without this configuration.

• AWS Region: Your Region must have a sufficient EC2 On-Demand vCPU quota for your node count and for a temporary Provisioner instance.

  Tip
  Because a quota shortage can look identical to a capacity shortage, we recommend checking your service quotas before beginning deployment.

Tools and authentication

• Install the following tools:
  • Terraform 1.11 (or higher)
  • Git CLI
  • AWS CLI

• Authenticate to the AWS API

  Important
  Unless you use the AdministratorAccess managed IAM policy for your user or role, your custom IAM role or user must include the following AWS services:

  • ec2:*
  • elasticloadbalancing:*
  • iam:*
  • kms:*
  • logs:*
  • s3:*
  • secretsmanager:*
  • ssm:*
  • sts:*

  For role definitions and ready-to-use policy statements, see AWS Bring Your Own IAM Roles in the Qumulo Terraform Provider documentation.

Working with the Qumulo-terraform-aws Repository

The Qumulo-terraform-aws repository contains Terraform configurations that let you deploy S3 buckets and a CNQ cluster with 1 or 3–24 nodes that adhere to the AWS Well-Architected Framework and have fully elastic compute and capacity.

This deployment uses the Qumulo Terraform Provider, which greatly simplifies Terraform operations by ensuring that:

• Persistent storage and compute deploy together in a single Terraform workspace
• Node operations use a single variable and a single terraform apply command

Working With the terraform apply Command

This section explains the most common scenarios that cause the terraform apply command to fail.

Symptom	Potential Resolution
The command waits for a long time for EC2 capacity	This is normal behavior. For more information, see Create the Necessary Resources.
The command fails early in the process with an S3 access error	The cluster subnet has no S3 gateway VPC endpoint. Add a VPC endpoint and then associate it with the subnet's route table. Note It isn’t possible to use a NAT gateway in this scenario.
The command fails completely and removes the resources that it has created	This is expected cleanup behavior. To resolve the issue, inspect the Provisioner's logs, make any changes, and then run the terraform apply command again.

Working with the Provisioner

The Provisioner is a temporary EC2 instance (m5.xlarge by default) that configures your Qumulo cluster. The Terraform Provider launches it during cluster creation, scaling, and node replacement operations, and stops it when an operation completes.

To monitor the Provisioner’s status, watch the Terraform operations in your terminal or inspect the Provisioner’s entries in your CloudWatch Logs, for your deployment’s AWS Region.

Part 1: Deploying Your Qumulo Cluster

This section explains how to prepare the required files, configure your deployment, and create the resources necessary for your Qumulo cluster.

Step 1: Prepare the Required Files

During the following process, Terraform downloads the Qumulo Terraform Provider from Qumulo’s registry. Later, the Provider installs Qumulo Core on your cluster’s nodes.

1. To clone the Qumulo-terraform-aws repository and check out a specific release, run the following commands.

   git clone https://github.com/Qumulo/Qumulo-terraform-aws.git
   cd Qumulo-terraform-aws
   git checkout v7.0
   

2. To understand the deployment variables, review the terraform.tfvars.example and README files.

Step 2: Configure the Deployment

1. Edit the backend.tf file, add the name of an S3 bucket for the Terraform state, and specify the Region for the deployment. For example:

   terraform {
     backend "s3" {
       bucket               = "my-bucket-for-tf-state"
       key                  = "tf-state/cnq/terraform.tfstate"
       region               = "us-west-2"
       use_lockfile         = true
       workspace_key_prefix = "tf-state-workspace"
     }
   }
   

   Important
   

   • We don't recommend making further changes to this part of the configuration.
   • For production deployments, we don't recommend storing the Terraform state locally. Instead, use the S3 backend and enable versioning on the state bucket. This configuration makes it possible to recover a previous state file if a particular state becomes corrupted or gets overwritten.

2. Run the terraform init command.

   Terraform prepares the environment, downloads the Qumulo Terraform Provider from Qumulo’s registry, verifies its GPG-signed checksums, and displays the message Terraform has been successfully initialized!

   Note
   

   • The terraform init command reports that the Qumulo provider is self-signed. This is expected for providers hosted outside registry.terraform.io and isn't a security issue; Terraform still performs full signature and checksum verification. For more information, see Installation and Trust in the Qumulo Terraform Provider documentation.
   • If the terraform init command can't reach the Provider registry, allow outbound HTTPS to qumulo-terraform-registry.s3.us-east-1.amazonaws.com.

3. Edit the terraform.tfvars file and specify the following required values for your deployment:

   • Basic Details: deployment_name, ec2_key_pair, and the region for your cluster

   • Networking: vpc_id and subnet_ids

     • Single-AZ (Availability Zone) Deployment: Specify 1 private subnet

     • Multi-AZ Deployment: Specify 3 subnets, one for each AZ

   • Cluster Configuration: instance_type and node_count (1, or 3–24)

     Note
     A 4-node cluster can support only a single-AZ deployment.

   • Soft Capacity Limit: If you don’t use the default limit, specify soft_capacity_limit_tb to set the initial capacity limit of your Qumulo cluster (in TB).

     Note
     It is possible to increase this limit at any time, but not to decrease it.

   • Cluster / Active Directory Name: cluster_name

   • Qumulo Core Version: cluster_version

     • Specific Release: Specify 7.9.2.1 (or higher)

     • Latest Release: Don’t enter a value

4. Specify the administrator password. The password variable accepts a plain-text value or an AWS Secrets Manager ARN.

   Important
   

   • The system treats the administrator password as sensitive: It never writes it to Terraform states and reads it anew for every Terraform run.
   • We strongly recommend passing a Secrets Manager ARN by rotating the secret in your store and allowing the next Terraform run to pick it up. Because secret handling functionality is located outside the Provider, you can also source the password from a HashiCorp Vault or another pipeline-integrated secrets store.

Step 3: Create the Necessary Resources

1. To authenticate to your AWS account, use the aws CLI.

2. Run the terraform apply command.

3. Review the Terraform execution plan and then enter yes.

   Terraform creates resources according to the execution plan and displays:

   • The names of the created S3 buckets

   • Your deployment’s unique name

   • The floating IP addresses for your Qumulo cluster (single-AZ deployments)

   • The primary (static) IP addresses

   • The Qumulo Core Web UI endpoint

   For example:

   cluster_soft_capacity_limit_tb = 500
   cluster_uuid = "12345a6b-7c89-0d12-3456-78fe9012f345"
   deployment_unique_name = "myname-deployment-ABCDE01EG2H"
   endpoint_ips = tolist([
     "203.0.113.1",
     "203.0.113.2",
     "203.0.113.3",
   ])
   endpoints = {
     "api" = "https://203.0.113.1:8000"
     "nfs" = "203.0.113.1:/<NFS Export Name>"
     "smb" = "\\\\203.0.113.1\\<SMB Share Name>"
     "web_ui" = "https://203.0.113.1"
   }
   primary_ips = tolist([
     "203.0.113.5",
     "203.0.113.6",
     "203.0.113.7",
   ])
   provisioner_log = "https://us-west-2.console.aws.amazon.com/cloudwatch/..."
   

Part 2: Mounting the Qumulo File System

1. To log in to your cluster’s Web UI, use the endpoint from the Terraform output and the username and password that you have configured.

   Important
   

   • The system treats the administrator password as sensitive: It never writes it to Terraform states and reads it anew for every Terraform run.
   • If you change the administrator password by using the Qumulo Core Web UI, Qumulo REST API, or qq CLI after deployment, although Terraform configuration remains unaffected, we recommend keeping your secrets store up to date with your cluster's settings, so that future redeployments use the correct value.

   You can use the Qumulo Core Web UI to create and manage the following:

   • NFS exports
   • SMB shares
   • Snapshots
   • Continuous replication relationships

   You can also join your cluster to Active Directory and configure LDAP.

2. Mount your Qumulo file system by using NFS or SMB and your cluster’s DNS name or an IP address from the Terraform output.

Part 3: Performing Post-Deployment Actions

This section describes the common actions you can perform on a CNQ cluster after deploying it: adding and removing nodes, increasing the soft capacity limit for a cluster, changing the EC2 instance type and deleting a cluster.

Adding Nodes to an Existing CNQ on AWS Cluster

1. Edit the terraform.tfvars file and set node_count to a higher value.

2. Run the terraform apply command.

3. Review the Terraform execution plan, confirm that it shows an in-place update, and then enter yes.

Terraform adds the nodes to your cluster and displays the additional primary (static) IP addresses.

Removing Nodes from an Existing CNQ on AWS Cluster

Removing nodes is a single Terraform operation. The Qumulo Terraform Provider handles the separate quorum removal and resource cleanup steps.

1. Edit the terraform.tfvars file and set node_count to a lower value.

2. Run the terraform apply command.

3. Review the Terraform execution plan and then enter yes.

The specified nodes are removed from your cluster.

Increasing the Soft Capacity Limit for an Existing CNQ on AWS Cluster

1. Edit the terraform.tfvars file and set soft_capacity_limit_tb to a higher value.

2. Run the terraform apply command.

3. Review the Terraform execution plan and then enter yes.

Terraform creates new S3 buckets as necessary, updates the IAM roles and S3 bucket policies, and increases the soft capacity limit.

Changing the EC2 Instance Type of a CNQ on AWS Cluster

The Qumulo Terraform Provider performs the replacement natively within the existing deployment.

1. Edit the terraform.tfvars file and specify the new instance_type.

2. Run the terraform apply command.

3. Review the Terraform execution plan, and then enter yes.

Deleting an Existing CNQ on AWS Cluster

1. After you back up your data safely, edit your terraform.tfvars file and set the deletion protection variable to false.

2. Run the terraform apply command, review the Terraform execution plan, and then enter yes.

3. Run the terraform destroy command.

4. Review the Terraform execution plan and then enter yes.

   Terraform deletes all of your cluster’s resources, including the persistent storage, and displays the Destroy complete! message with a count of destroyed resources.

Related Topics

• How Cloud Native Qumulo Works
• Deploying Cloud Native Qumulo on AWS with CloudFormation
• Supported Configurations and Known Limits