Skip to content

Implement Runtime NVMe Instance Storage Discovery Using AWS EBS Symlinks#396

Draft
neddp wants to merge 3 commits intomainfrom
fix-nvme-instance-storage-discovery
Draft

Implement Runtime NVMe Instance Storage Discovery Using AWS EBS Symlinks#396
neddp wants to merge 3 commits intomainfrom
fix-nvme-instance-storage-discovery

Conversation

@neddp
Copy link
Copy Markdown
Member

@neddp neddp commented Feb 2, 2026

Problem

On AWS Nitro-based instances with NVMe devices, the kernel's PCIe enumeration order is non-deterministic. This means:

  • /dev/nvme0n1 could be the root EBS volume OR instance storage
  • /dev/nvme1n1 could be instance storage OR the root EBS volume
  • The order varies between boots and instance types
  • There is no guaranteed ordering

Solution

Implemented runtime discovery to reliably identify instance storage by excluding EBS volumes.

Discovery Algorithm

  1. Glob all NVMe devices: /dev/nvme*n1
  2. Glob EBS symlinks: /dev/disk/by-id/nvme-Amazon_Elastic_Block_Store_*
  3. Resolve each symlink to its target device
  4. Subtract EBS devices from all NVMe devices = instance storage
  5. Validate count matches CPI expectations
  6. Partition only the discovered instance storage devices

Why EBS Symlinks Are Reliable

AWS automatically creates persistent symlinks for all EBS volumes via udev rules:

/dev/disk/by-id/nvme-Amazon_Elastic_Block_Store_vol{volume_id}

Backwards Compatibility

Non-NVMe instances: No changes to behavior

  • Traditional Xen instances (/dev/xvdb, /dev/sdb) use CPI paths directly
  • Paravirtual instances work as before

This must be merged together with the CPI changes - cloudfoundry/bosh-aws-cpi-release#196


Pair @Ivaylogi98

Copy link
Copy Markdown
Contributor

@rkoster rkoster left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general I would have expected this logic to go into the https://github.com/cloudfoundry/bosh-agent/tree/main/infrastructure/devicepathresolver package.

p.logger.Debug(logTag, "Found NVMe devices: %v", allNvmeDevices)

// Identify EBS volumes via symlinks
ebsSymlinks, err := p.fs.Glob("/dev/disk/by-id/nvme-Amazon_Elastic_Block_Store_*")
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should somehow be passed in via the agent config in the stemcell builder, because it is IaaS specific.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created a new component instanceStorageResolver for the linux platform. It has 3 variants:

  • autoDetectingInstanceStorageResolver - the linux platform uses this one, it detects which storage resolver to use
  • awsNVMeInstanceStorageResolver - detects what are the instance storage devices; contains the new logic
  • identityInstanceStorageResolver - simple resolver for the traditional naming used before this change

@github-project-automation github-project-automation bot moved this from Inbox to Waiting for Changes | Open for Contribution in Foundational Infrastructure Working Group Feb 3, 2026
@neddp
Copy link
Copy Markdown
Member Author

neddp commented Feb 3, 2026

In general I would have expected this logic to go into the https://github.com/cloudfoundry/bosh-agent/tree/main/infrastructure/devicepathresolver package.

Thank you for the review! That's was a big oversight on my end, I'll look into it.

@rkoster
Copy link
Copy Markdown
Contributor

rkoster commented Feb 3, 2026

No worries 🙂

@beyhan
Copy link
Copy Markdown
Member

beyhan commented Feb 5, 2026

We discussed this during the FI WG meeting and this have to relay on the stemcell agent settings and agent strategy for disc handling.

@neddp neddp requested a review from rkoster February 9, 2026 14:27
@neddp neddp changed the title Implement Runtime NVMe Instance Storage Discovery Using EBS Symlinks Implement Runtime NVMe Instance Storage Discovery Using AWS EBS Symlinks Feb 9, 2026
@rkoster
Copy link
Copy Markdown
Contributor

rkoster commented Feb 12, 2026

As discussed during the working group meeting, focus is now on validating: cloudfoundry/bosh-aws-cpi-release#196 (comment)

@rkoster
Copy link
Copy Markdown
Contributor

rkoster commented Feb 19, 2026

As per: cloudfoundry/bosh-aws-cpi-release#196 (comment) this change is still needed. Please continue reviewing.

@rkoster rkoster requested review from a team and ramonskie and removed request for a team February 19, 2026 15:54
Copy link
Copy Markdown
Contributor

@rkoster rkoster left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still think this PR could be done in an IaaS agnostic way.


type awsNVMeInstanceStorageResolver struct {
fs boshsys.FileSystem
devicePathResolver DevicePathResolver
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The devicePathResolver field is stored in the struct but never used anywhere in the awsNVMeInstanceStorageResolver implementation. The DiscoverInstanceStorage method only uses fs for globbing and symlink resolution.

nvmeDevicePattern string,
) InstanceStorageResolver {
if ebsSymlinkPattern == "" {
ebsSymlinkPattern = "/dev/disk/by-id/nvme-Amazon_Elastic_Block_Store_*"
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would still like this to be passed in as configuration, so that the strategy can be iaas agnostic. This pattern might some day be re-usable.

neddp and others added 3 commits February 25, 2026 14:06
* Refactor instance storage discovery into configurable component

Implement auto-detection for instance storage disk type

* Fix windows tests

* Fix windows tests (but for real this time)
@neddp neddp force-pushed the fix-nvme-instance-storage-discovery branch from e7d00b4 to dcd857a Compare February 25, 2026 12:09
@rkoster
Copy link
Copy Markdown
Contributor

rkoster commented Mar 26, 2026

@neddp could you take a look at these failing unit tests?

@neddp
Copy link
Copy Markdown
Member Author

neddp commented Mar 26, 2026

Hi @rkoster,

We still haven't had the time to test the changes on an actual deployment. I will move the PR to draft until we can confirm everything is working fine.

We'll address the tests as well.

@neddp neddp marked this pull request as draft March 26, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Waiting for Changes | Open for Contribution

Development

Successfully merging this pull request may close these issues.

4 participants