AWS IAM permissions

The deploying credentials are the AWS identity that runs terraform apply for qumulo_filesystem_aws. This page lists what that identity, and the roles and keys around it, must be allowed to do.

Service access

Service	What the provider manages	When it is needed
IAM	Roles and instance profiles for the cluster nodes and the provisioner	Every cluster. Not needed for a role supplied through cluster_iam_role_arn or provisioner_iam_role_arn.
EC2	Instances, EBS volumes, and security groups	Every cluster. Security groups are not created when cluster_security_group_id and provisioner_security_group_id are set.
S3	The cluster's persistent storage buckets, and the <deployment_unique_name>-staging bucket	Every cluster. The staging bucket is created only when air_gapped = true and package_url is not set.
SSM Parameter Store	The /qumulo/<deployment_unique_name>/... parameters that carry provisioner status, the cluster UUID, and legacy module data	Every cluster

Specific actions

Action	When it is needed
ec2:ModifyInstanceAttribute	Every cluster, to lift deletion protection from an instance before terminating it
s3:GetBucketPolicy	Every cluster, to lift deletion protection from a bucket before deleting it
s3:PutBucketPolicy	Every cluster
s3:GetObject, s3:PutObject, s3:DeleteObject on arn:aws:s3:::<deployment_unique_name>-staging/*	Every operation that builds nodes, when air_gapped = true and package_url is not set. The provider copies the Qumulo Core packages from Nexus into the staging bucket, whose policy lets requests from the cluster's VPC read them without credentials
tag:GetResources	Every cluster, to find its S3 buckets by their Qumulo-Cluster tag on destroy, on update, and on refresh with deletion_protection
ssm:PutParameter on /qumulo/<deployment_unique_name>/last-run-status	Every cluster, to reset the provisioner status before each create, scale, replacement, and configuration update
ssm:AddTagsToResource on /qumulo/<deployment_unique_name>/last-run-status	Every cluster, to tag the status parameter. A failure to tag only logs a warning
ssm:GetParameter on /qumulo/<deployment_unique_name>/last-run-status, /qumulo/<deployment_unique_name>/uuid, /qumulo/<deployment_unique_name>/cluster-info, and /qumulo/<deployment_unique_name>/creation-version	Every cluster, to poll the provisioner status, read the cluster UUID, tell whether aws-terraform-cnq created the cluster, and check for leftover parameters when a refresh finds the cluster gone. A missing creation-version parameter is the normal result for a cluster the provider created
ssm:GetParameter on /qumulo/<deployment_unique_name>/bucket-names, and kms:Decrypt on the account's aws/ssm key	Every cluster. Every bucket lookup reads the bucket list that clusters built with aws-terraform-cnq keep in that SecureString parameter. For a cluster the provider created, the read returns "not found"
ssm:DeleteParameters on /qumulo/<deployment_unique_name>/cluster-info, /qumulo/<deployment_unique_name>/last-run-status, and /qumulo/<deployment_unique_name>/uuid	Every cluster, on destroy
ssm:GetParametersByPath and ssm:DeleteParameters on /qumulo/<deployment_unique_name>/	A cluster created by aws-terraform-cnq, on destroy, to remove the parameters that module wrote
secretsmanager:CreateSecret, secretsmanager:PutSecretValue, secretsmanager:DescribeSecret, secretsmanager:DeleteSecret, secretsmanager:TagResource on arn:aws:secretsmanager:<region>:<account>:secret:/qumulo/<deployment_unique_name>/provisioner-secrets-*	Every cluster. The provider writes the provisioner's run inputs to this secret before each run and deletes it when the run ends and on destroy. Secrets Manager appends a random suffix to the secret ARN, so the trailing -* is required. secretsmanager:RestoreSecret and secretsmanager:UntagResource on the same ARN are also needed when an earlier deletion of the secret is still pending
ec2:DescribeSubnets	Every cluster, to derive each subnet's availability zone
ec2:DescribeInstanceAttribute	When deletion_protection is set
logs:DescribeLogGroups, logs:CreateLogGroup, logs:TagResource	When audit_logging = true
iam:PassRole on the supplied role	When cluster_iam_role_arn or provisioner_iam_role_arn is set

logs:DeleteLogGroup is not required.

Warning

Without tag:GetResources, terraform destroy terminates the instances and then fails, leaving every <random>-<deployment_name>-qps-<N> bucket behind. The cluster stays in Terraform state while any of its resources remain, so after granting the permission, run terraform destroy again to finish the cleanup.

Note

Nodes reach the staging bucket through the VPC's S3 gateway endpoint, which is already a deployment prerequisite. The staging bucket holds only Qumulo Core packages, so it uses S3's default encryption even when kms_key_id is set: S3 does not serve SSE-KMS objects to requests without credentials.

Tag-enforcing permissions boundaries (S3 ABAC)

Some organizations bound the roles that deploy a cluster with a policy that allows s3:CreateBucket only when the request carries the qumulo-deployment tag, and that denies every other call on the bucket until S3 attribute-based access control (ABAC) is enabled on it. Under such a boundary the provider's default calls fail: it creates a bucket without tags, tags it afterwards with s3:PutBucketTagging, and never enables ABAC.

Set s3_bucket_abac = true on qumulo_filesystem_aws for these deployments. Leave it unset everywhere else: with the default false the provider makes exactly the calls described above and needs none of the permissions below.

With s3_bucket_abac = true the provider:

• creates each cluster bucket, and the staging bucket, with its tags in the CreateBucket call, then enables ABAC on it before any other call;
• changes bucket tags with s3:TagResource and s3:UntagResource, never replacing the whole tag set and never removing qumulo-deployment, Qumulo-Cluster, or the AWS partner tags;
• tags and enables ABAC on the buckets of an imported cluster, which may predate the qumulo-deployment tag;
• enables ABAC on a bucket before it deletes it, so a bucket left without ABAC by an interrupted create can still be removed.

It needs these permissions on the cluster's *-qps-* buckets, and on the <deployment_unique_name>-staging bucket when air_gapped = true:

Action	Used for
s3:TagResource	Creating a bucket with tags, adding and updating tags, and adopting an imported cluster
s3:UntagResource	A change to tags that removes a tag
s3:PutBucketAbac	Enabling ABAC after create, on import, and before delete
s3:GetBucketTagging	A change to tags, to compare the bucket's current tags with the new set

s3:PutBucketTagging is not called with s3_bucket_abac = true. tag:GetResources is still needed to find the buckets.

Changing s3_bucket_abac from false to true on an existing cluster tags its buckets with qumulo-deployment and enables ABAC on them during the next apply. Changing it back to false returns to the default calls and does not disable ABAC on any bucket. Changing it never replaces the cluster.

Customer-managed KMS key

Principal	Actions on the key	When it is needed
The IAM roles the provider creates	kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, kms:DescribeKey	When kms_key_id is set

The key must be in the same region as the cluster, or be a multi-region replica in that region.

Cross-account AMIs

Grant	Granted by	When it is needed
Launch permission on the AMI	The AMI owner's account	When ami_id or provisioner_ami_id names an AMI owned by another account
kms:Decrypt, kms:DescribeKey, kms:CreateGrant on the snapshot's key	The key policy in the AMI owner's account	When that AMI's backing snapshot is encrypted

Permissions boundaries

When permissions_boundary_arn is set, the provider attaches the same boundary to the cluster node role and the provisioner role. The boundary must allow the S3, EC2, KMS, Secrets Manager, and CloudWatch Logs permissions those roles use, or role creation fails with an IAM error.

Bring-your-own roles

A role supplied through cluster_iam_role_arn or provisioner_iam_role_arn must belong to exactly one instance profile. The cluster role's S3 policy must use the wildcard bucket pattern in AWS Bring Your Own IAM Roles.

Import

Importing an existing cluster needs further permissions, listed in the import reference.