Skip to content
flexFS

Cloud IAM Setup

When flexFS servers run on cloud instances, they can authenticate to object storage using the cloud provider’s native identity system instead of static credentials. This is the recommended approach for production deployments because it eliminates the need to manage and rotate access keys.

The identities that need storage access are those of the metadata server and any proxy servers. For a block store created without --password, the metadata server passes mount clients the blockUser and blockPass from its own credentials file or, when that file has no blockPass, credentials from its host’s identity, so mount hosts do not need a role of their own. On AWS, GCP, and OCI the metadata server obtains those credentials through the same credential chain it uses for its own access; on Azure it uses only its host’s system-assigned (or a single user-assigned) managed identity (see the Azure section).

Amazon Web Services (S3)

Section titled “Amazon Web Services (S3)”

On AWS, flexFS can use EC2 instance roles to access S3 without static credentials.

1. Create an IAM policy

Section titled “1. Create an IAM policy”

Create a policy that grants the required S3 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket>",
        "arn:aws:s3:::<bucket>/*"
      ]
    }
  ]
}

Replace <bucket> with your bucket name.

S3 Express One Zone (directory buckets)

Section titled “S3 Express One Zone (directory buckets)”

For an S3 Express One Zone bucket, use the following policy instead. S3 Express One Zone uses session-based authentication, so a single s3express:CreateSession permission on the directory bucket authorizes the S3 data operations — the standard s3:* actions shown above are not required.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3express:CreateSession",
      "Resource": "arn:aws:s3express:<region>:<account-id>:bucket/<bucket>"
    }
  ]
}

Replace <region>, <account-id> (your AWS account ID), and <bucket> to match your bucket. Directory bucket names always end in --x-s3 (for example, my-flexfs-bucket--use1-az4--x-s3).

Save the policy document (standard or S3 Express) to policy.json, then create the policy:

Terminal window
aws iam create-policy \
  --policy-name flexfs-s3-policy \
  --policy-document file://policy.json

2. Create an IAM role

Section titled “2. Create an IAM role”
Terminal window
aws iam create-role \
  --role-name flexfs-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

3. Attach the policy to the role

Section titled “3. Attach the policy to the role”
Terminal window
aws iam attach-role-policy \
  --role-name flexfs-role \
  --policy-arn arn:aws:iam::<account-id>:policy/flexfs-s3-policy

4. Create an instance profile and attach the role

Section titled “4. Create an instance profile and attach the role”
Terminal window
aws iam create-instance-profile \
  --instance-profile-name flexfs-profile


aws iam add-role-to-instance-profile \
  --instance-profile-name flexfs-profile \
  --role-name flexfs-role

5. Attach the profile to your instances

Section titled “5. Attach the profile to your instances”

For new instances, specify the profile at launch:

Terminal window
aws ec2 run-instances \
  --instance-type c6gn.16xlarge \
  --iam-instance-profile Name=flexfs-profile \
  ...

For existing instances:

Terminal window
aws ec2 associate-iam-instance-profile \
  --instance-id i-0123456789abcdef0 \
  --iam-instance-profile Name=flexfs-profile

6. Configure flexFS with the instance role

Section titled “6. Configure flexFS with the instance role”

With the role attached, the instance provides credentials automatically — omit both --username and --password when creating the block store:

Terminal window
configure.flexfs create block-store \
  --providerCode aws \
  --regionCode <region> \
  --apiCode s3 \
  --bucket <bucket> \
  --prefix <prefix>

Credential chain

Section titled “Credential chain”

When no password is set (see the tip above), flexFS tries in order:

  1. EC2 instance metadata (IMDS v2) for instance role credentials
  2. Default AWS credential chain (environment variables, ~/.aws/credentials, IRSA and EKS Pod Identity, ECS task roles, etc.)

Next steps

Section titled “Next steps”