Auto Mode: document that third-party iSCSI CSI block volumes cannot mount on managed nodes

Open Beginner friendly
  • Is something wrong?
#1,261 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
aws, kubernetes, postgresql
Domain
cloud, documentation

Research direction

Start with the Amazon EKS Auto Mode Managed instances page and the FSx for NetApp ONTAP page named in the issue; also review the linked workload placement guidance. Document the iSCSI limitation on Auto Mode managed nodes, the managed node group alternative, and the mixed-cluster node preparation caveat. Done when readers can identify the limitation and route iSCSI workloads to the managed node group.

Written by the indexing model from the issue text.

Description

Page

Request

Please state on the Auto Mode pages that third-party CSI drivers that attach volumes over iSCSI cannot mount block volumes on Auto Mode managed nodes, and describe the supported alternative (a managed node group in the same cluster).

What happens

On an EKS Auto Mode cluster (Kubernetes 1.36, ap-northeast-1, 2026-11-10) with the NetApp Trident EKS add-on (v26.6.2-eksbuild.1) and Amazon FSx for NetApp ONTAP:

  • An NFS PVC mounted on Auto Mode managed nodes.
  • An iSCSI PVC was provisioned (Bound) but the Pod stayed in ContainerCreating with:
MountVolume.MountDevice failed ... failed to stage volume: unable to attach: open-iscsi tools not found on host

The managed nodes (Bottlerocket, EKS Auto, Standard, 2026.10.31) have no iscsiadm, iscsid, or /etc/iscsi/initiatorname.iscsi, and the Auto Mode documentation says you cannot install software on managed nodes. AWS Support confirmed this behavior and that a managed node group is the way to use iSCSI.

Points worth documenting

  1. Block storage over iSCSI from third-party CSI drivers is not available on Auto Mode managed nodes.
  2. A managed node group can be added to the Auto Mode cluster for those workloads, with the iSCSI tools installed through launch template user data.
  3. In a mixed cluster, a driver's own node-preparation feature (for Trident, nodePrep) can fail on the managed nodes and stop the driver's node pods there, which also breaks NFS volumes on those nodes. Installing the tools through user data on the managed node group avoids this.
  4. The eks.amazonaws.com/compute-type label (Control if a workload is deployed on EKS Auto Mode nodes) places the iSCSI workloads on the managed node group.

Today a reader finds out only after the Pod fails to start. The Amazon FSx for NetApp ONTAP page covers iSCSI with Trident but does not mention Auto Mode.

Test record (public): https://github.com/Yoshiki0705/FSx-for-ONTAP-Container-Datastore-Patterns/blob/main/docs/en/atx-containerization-fsxn-storage-verification.md (section 9.2)

Dominant language
Shell
Stars
454
Forks
788
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from awsdocs/amazon-eks-user-guide

All issues in awsdocs/amazon-eks-user-guide

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.