Prepare the AWS resources
Citrix SecurSpaces™ does not create or validate any of the AWS resources on this page. Provision them before anyone uses the feature.
Prerequisites common to Amazon EFS and Amazon S3 Files
Create a mount target in every Availability Zone
Create a mount target in every Availability Zone in which the node group can place workspace nodes. Take the Availability Zone list from the node group’s autoscaling group, not from where nodes happen to run today. EFS allows one mount target per Availability Zone, shared by all Mount Points on that file system.
A workspace scheduled into an Availability Zone with no reachable mount target hangs in ContainerCreating, and
Kubernetes cannot compensate. The mount target is not represented in Kubernetes, so this is the only symptom.
Mount target creation is slow. Wait until every mount target reports available before you create Mount Points.
Scope the NFS rule to a security group
The source of the mount target’s inbound NFS rule decides who can mount the file system. If you allow the whole VPC CIDR, every workload in the VPC can mount it, not only your workspace nodes.
Set the source of the inbound rule to the EKS worker node security group rather than an IP range:
aws ec2 authorize-security-group-ingress \
--group-id <mount-target-sg> --protocol tcp --port 2049 \
--source-group <eks-node-security-group-id>
<!--NeedCopy-->
Both halves of the rule are required:
- Mount target security group, inbound — TCP 2049, source is the node security group.
- Node security group, outbound — TCP 2049, destination is the mount target security group.
Most EKS node groups keep the default allow-all egress, so the outbound half is usually already satisfied. If your account restricts node egress, add it explicitly. A missing outbound rule produces the same symptom as a missing mount target: workspaces hang while starting, with no indication in Kubernetes.
Outbound rules on the mount target security group are not needed, because security groups are stateful.
Note
If you use EKS security groups for pods, the client is the pod security group rather than the node security group. If you must use a CIDR, scope it to the worker node subnet CIDRs, never the whole VPC. A security group limits reachability, not encryption. Keep
tlson the mount regardless.
Amazon EFS prerequisites
- Create the file system first. The driver cannot create it. Create New carves a fresh isolated access point on the file system you provisioned. It never creates a file system.
- Enable encryption at rest when you create the file system. Mount Points work either way, so nothing warns you later, and encryption cannot be enabled after creation.
-
Attach
AmazonEFSCSIDriverPolicyto the CSI driver role. It must includeDescribeMountTargets, which the mount helper uses to resolve the Availability Zone local mount target.
Enable automatic backups
EFS has no versioning, no snapshots, and no recycle bin. Without a recovery point that already existed when data was lost, a deletion is permanent.
A regional EFS file system created with the CLI, the API, or Terraform is created with automatic backups
disabled. Only the EFS console enables them for you. Pass --backup at creation, or enable it afterwards:
aws efs put-backup-policy --file-system-id <fs-id> --backup-policy Status="ENABLED"
aws efs describe-backup-policy --file-system-id <fs-id>
<!--NeedCopy-->
This attaches the default AWS Backup plan for EFS: daily backups with 35-day retention. Confirm that AWS Backup is offered in your Region, and budget for it separately from EFS.
Choose Elastic throughput
The CLI and API default to Bursting throughput, whose baseline scales with stored bytes. A Mount Point file system starts empty, so it converges on the minimum and caps at 35,000 read and 7,000 write IOPS. Elastic throughput raises this to approximately 250,000 and 50,000, which is what the many small-file operations in a workspace actually need.
aws efs update-file-system --file-system-id <fs-id> --throughput-mode elastic
<!--NeedCopy-->
Throughput mode is a file system attribute. It cannot be set on the StorageClass, and SecurSpaces cannot see or warn about it.
Note
Elastic throughput meters every gigabyte read and written, with writes charged at roughly twice the rate of reads. Size the change from your CloudWatch read and write metrics first, and do not switch during business hours. Elastic throughput does not reduce per-operation latency, so it is not a fix for slow small-file work.
Amazon S3 Files prerequisites
Amazon S3 Files requires the per-Availability-Zone mount targets described earlier, plus the following.
Note
Do not confuse Amazon S3 Files with Mountpoint for Amazon S3 (
s3.csi.aws.com), which is not POSIX compliant and is not a supported Mount Point backend.
Prepare the bucket
The S3 bucket must have versioning enabled and server-side encryption configured before you create the file system. Bucket versioning is also the only way to recover a deleted file on S3 Files.
The --accept-bucket-warning flag is not an “existing data” switch. S3 Files warns when a file system is scoped to
a prefix that holds a large number of objects, because recursive renames on such a file system are slow and costly.
The flag acknowledges that warning. It does nothing about versioning or encryption.
Create the service role
When you create the file system you pass an IAM role that S3 Files assumes to read and write your bucket and to manage the EventBridge rules that drive synchronization. The S3 console creates this role for you. From the CLI or Terraform you must author both the trust policy and the permissions policy.
A role with only a trust policy is accepted at creation time, but leaves synchronization unable to work.
The permissions policy must grant:
-
s3:ListBucketands3:ListBucketVersionson the bucket. -
s3:AbortMultipartUpload,s3:DeleteObject*,s3:GetObject*,s3:List*, ands3:PutObject*on the bucket contents. -
kms:GenerateDataKey,kms:Encrypt,kms:Decrypt,kms:ReEncryptFrom, andkms:ReEncryptTo. - EventBridge rule management scoped to
rule/DO-NOT-DELETE-S3-Files*, plus EventBridge read actions.
For the full policy documents, see the AWS documentation for working with Amazon S3 Files.
Warning
If the bucket uses SSE-KMS, the role cannot read or write a single object without the
kms:actions. Reads fail and writes never reach the bucket, both silently. Keep the KMS statement even on an SSE-S3 bucket, so the role still works if the bucket is switched to SSE-KMS later. If the key is a customer managed key, its key policy must also allow this role. An IAM policy alone is not enough.
The EventBridge rules named DO-NOT-DELETE-S3-Files... are how changes made directly in the bucket reach mounted
workspaces. Do not delete or disable them. Without them, cached files keep serving stale content.
Create the file system
aws s3files create-file-system --bucket <bucket-arn> [--prefix p/] --role-arn <service-role-arn>
<!--NeedCopy-->
Check versions and platform support
- In the cluster — the Amazon EFS CSI driver must be version 3.0.0 or later.
-
On any EC2 host you mount from directly — the
amazon-efs-utilsclient must be version 3.0.0 or later. -
AWS CLI — new enough to include the
s3filescommands. Verify withaws s3files help.
Attach AmazonS3FilesCSIDriverPolicy and AmazonS3FilesClientFullAccess to the controller identity, and
AmazonS3FilesClientFullAccess, AmazonElasticFileSystemsUtils, and S3 read on the bucket to the node identity.
See Scope IAM permissions
before you attach the account-wide managed policies.
Amazon S3 Files does not support cross-account static attach: the file system and bucket must be in the same AWS account as the cluster. It is not supported on EKS Fargate, EKS Hybrid Nodes, or Windows containers.
Scope IAM permissions
The EFS CSI driver authenticates through IAM roles for service accounts (IRSA).
Warning
Most AWS walkthroughs attach the node policies to the EC2 instance role of the managed node group. An instance role grant is not private to the CSI driver: any workload on that node that can reach the instance metadata service can use it. Because workspaces run customer-supplied code, treat every policy on the node role as one you have granted to your developers.
Give the node driver its own role bound to its service account rather than using the instance role:
- Enable the cluster OIDC provider.
- Create a role whose trust policy pins both the service account and the STS audience.
- Annotate
efs-csi-node-sawitheks.amazonaws.com/role-arn. Do the same forefs-csi-controller-sa.
Use the exact system:serviceaccount:<namespace>:<name> value. A wildcard subject, or a missing audience
condition, lets any pod in the cluster assume the role.
Scope client access to your file systems
All AWS managed S3 Files client policies use "Resource": "*" and cannot be limited to a file system. Anything
holding the node role is therefore authorized to mount every S3 Files file system in the account, and with
AmazonS3FilesClientFullAccess, to write to them as root.
Replace the managed policy with a customer managed policy that names your file systems and grants
s3files:ClientMount and s3files:ClientWrite on them. Add s3files:ClientRootAccess only where a mount genuinely
needs it.
Similarly, replace AmazonS3ReadOnlyAccess on the node role with an inline policy that grants s3:GetObject,
s3:GetObjectVersion, and s3:ListBucket scoped to the buckets that back Mount Points.
Note
A file system policy that omits a role does not revoke an account-wide identity grant. An allow in either the identity policy or the file system policy is sufficient. Either scope the identity policy, or add an explicit deny.
Harden instance metadata
Require IMDSv2 and set the metadata hop limit to 1 on the node group. Apply the steps in this order. Applied out of order, this silently breaks Mount Point provisioning.
- Confirm the driver uses its own role. Role credentials are injected when a pod is created, so annotating the service accounts is not enough. Until the pods restart, the driver falls back to the node role and appears to work. Restart the driver, confirm every pod reports a role ARN, and create one Mount Point successfully.
-
Change the launch template, so replacement nodes are created hardened. Set
HttpTokens: required,HttpPutResponseHopLimit: 1, andHttpEndpoint: enabled. -
Roll the change to running nodes one at a time, watching the
kube-systemnamespace for about 15 minutes after the first before continuing.
Metadata options are fixed when an instance launches. Changing the launch template does nothing to running nodes, and changing a running node does not survive its replacement.
Note
With
eksctl, usedisablePodIMDS: trueon the node group. The relateddisableIMDSv1key already defaults totrue, so setting it alone changes nothing, andeksctlwrites a hop limit of 2 withoutdisablePodIMDS. That leaves every pod able to borrow the node role.disablePodIMDScannot be combined withiam.withAddonPolicies, and is refused when a managed node group supplies its own launch template.
A hop limit of 1 stops ordinary pods from reaching the metadata service. Processes on the host and pods using
hostNetwork are unaffected, including the CSI node DaemonSet. The CSI controller runs on the pod network and is
affected: if it loses metadata access, new Mount Points fail while existing mounts keep working.