A common use case in the cloud is attaching/removing volumes dynamically. Identifying the attached disk device in the operating system of the VSI is not always obvious.

In IBM Cloud Virtual Server for VPC, the disk that is attached to the VSI is identified by the volume attachment identifier. Every volume has a UUID, but the attachment between the volume and the VSI also has a UUID. The UUID of that volume attachment is what can be used to identify the backing disk in the VSI.

UI-based example

Listing the volume attachment identifiers is simple with the ibmcloud CLI:

Drews-MBP ~ % ibmcloud is in-vols 0727_fa4230b2-e167-4a09-8d7c-2822bdb016bf
Listing volume attachments of instance 0727_fa4230b2-e167-4a09-8d7c-2822bdb016bf under account Drew Thorstensen's Account as user thorst@us.ibm.com...
ID                                          Name                          Volume                             Status     Type   Device                                            Auto delete   
0727-7db66159-5910-4ddc-a5b4-51f9333a9c3a   secrecy-robust-anyone-agile   test-metadata-volume               attached   data   0727-7db66159-5910-4ddc-a5b4-51f9333a9c3a-4xjjc   false   
0727-4b98cbf2-4e57-4b3b-9bd2-83f2439da3bc   breath-manger-bird-axiom      test-metadata-boot-1649335137000   attached   boot   0727-4b98cbf2-4e57-4b3b-9bd2-83f2439da3bc-5jx6t   true   

This shows two volumes attached to the VSI: the boot and then a data volume. If we log in to the VSI, we can see the volume disks:

[root@test-metadata ~]# ls -la /dev/disk/by-id
total 0
drwxr-xr-x. 2 root root 200 Apr  7 12:58 .
drwxr-xr-x. 7 root root 140 Apr  7 12:51 ..
lrwxrwxrwx. 1 root root   9 Apr  7 12:52 virtio-0727-4b98cbf2-4e57-4 -> ../../vda
lrwxrwxrwx. 1 root root  10 Apr  7 12:52 virtio-0727-4b98cbf2-4e57-4-part1 -> ../../vda1
lrwxrwxrwx. 1 root root  10 Apr  7 12:52 virtio-0727-4b98cbf2-4e57-4-part2 -> ../../vda2
lrwxrwxrwx. 1 root root  10 Apr  7 12:52 virtio-0727-4b98cbf2-4e57-4-part3 -> ../../vda3
lrwxrwxrwx. 1 root root   9 Apr  7 12:58 virtio-0727-7db66159-5910-4 -> ../../vdd
lrwxrwxrwx. 1 root root  10 Apr  7 12:58 virtio-0727-7db66159-5910-4-part1 -> ../../vdd1
lrwxrwxrwx. 1 root root   9 Apr  7 12:52 virtio-cloud-init- -> ../../vdc
lrwxrwxrwx. 1 root root   9 Apr  7 12:52 virtio-cloud-init-0727_fa42 -> ../../vdb

If we want to find the data volume named test-metadata-volume, we see that it is the vdd disk. The first 20 characters of the volume attachment identifier are used for the disk id. The symbolic link shows us the name of the disk that it maps to, as well.

Simplifying with the metadata service

Most users are looking for a quicker way to identify the disk name, and these users will also likely be starting with the volume rather than the volume attachment. Fortunately, this is easy to do.

Recently, IBM Cloud VPC introduced the metadata service. This capability allows the end user to query data about itself and get identity tokens and more from the VSI. One of the use cases it can help with is helping simplify getting the disk name based off a volume name.

The steps to find the disk name within a VSI from a given volume are as follows:

  • Deploy the VSI with metadata turned on
  • Get an instance identity token
  • Query the metadata service to list the volume attachments
  • Find the volume attachment that has the volume specified
  • Look up the disk name based off the volume attachment

Attached to this post is a script that can be used to retrieve the disk name for a given volume UUID (not the attachment UUID). The following is the sample output:

[root@test-metadata ~]# python3 scripts/find_disk.py -v 0727-7db66159-5910-4ddc-a5b4-51f9333a9c3a-4xjjc

In this case, the disk is named vdd within the VSI for volume 0727-7db66159-5910-4ddc-a5b4-51f9333a9c3a-4xjjc.


The following code can be embedded into your instance or user data to help quickly identify disk names within the VSI given the volume UUID.  Be sure to remember that the metadata service must be running for this to work properly:

# ======================================================================
#    Copyright 2022 IBM Corp.
#    Licensed under the Apache License, Version 2.0 (the "License");
#    you may not use this file except in compliance with the License.
#    You may obtain a copy of the License at
#      http://www.apache.org/licenses/LICENSE-2.0
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
# ======================================================================

import argparse
import json
import os
import requests
import sys

def init_argparse():
    parser = argparse.ArgumentParser(
        description=("Finds a local disk by UUID")
    parser.add_argument("-v", "--volume-uuid", required=True,
                        help=("The volume UUID."))

    return parser.parse_args()

def get_token():
    result = requests.put("",
                          headers={'Metadata-Flavor': 'ibm'})
    return json.loads(result.text)['access_token']

def get_volume_attachments(access_token):
    result = requests.get("",
                          headers={'Authorization': f"Bearer {access_token}"})
    return json.loads(result.text)['volume_attachments']

def get_disk_device(attachment_uuid):
    expected_path = f'/dev/disk/by-id/virtio-{attachment_uuid[:20]}'
    full_path = os.path.realpath(expected_path)
    return full_path.split('/')[-1]

def main():
    args = init_argparse()
    access_token = get_token()
    volume_attachments = get_volume_attachments(access_token)
    for volume_attachment in volume_attachments:
        if volume_attachment['device']['id'] == args.volume_uuid:
        print(f"Unable to find disk by volume {args.volume_uuid}")

if __name__ == '__main__':


The metadata service is a powerful service that makes it easy for a given instance to gather information about itself. Without needing to call out to any API, users can detect the disk name from within the VSI for a given volume UUID. These scripts can be extended to support additional use cases, including looking up the volumes and network interfaces.

To learn more about IBM Cloud VPC, please visit our website. You can also get USD 1,000 in credits to use toward any of your new VPC resources – including all compute, network and storage components.

Apply the VPC1000 code


More from Cloud

IBM Cloud VMware as a Service introduces multitenant as a new, cost-efficient consumption model

4 min read - Businesses often struggle with ongoing operational needs like monitoring, patching and maintenance of their VMware infrastructure or the added concerns over capacity management. At the same time, cost efficiency and control are very important. Not all workloads have identical needs and different business applications have variable requirements. For example, production applications and regulated workloads may require strong isolation, but development/testing, training environments, disaster recovery sites or other applications may have lower availability requirements or they can be ephemeral in nature,…

IBM accelerates enterprise AI for clients with new capabilities on IBM Z

5 min read - Today, we are excited to unveil a new suite of AI offerings for IBM Z that are designed to help clients improve business outcomes by speeding the implementation of enterprise AI on IBM Z across a wide variety of use cases and industries. We are bringing artificial intelligence (AI) to emerging use cases that our clients (like Swiss insurance provider La Mobilière) have begun exploring, such as enhancing the accuracy of insurance policy recommendations, increasing the accuracy and timeliness of…

IBM NS1 Connect: How IBM is delivering network connectivity with premium DNS offerings

4 min read - For most enterprises, how their users access applications and data is an essential part of doing business, and how they service those application and data responses has a direct correlation to revenue generation.    According to We Are Social’s Digital 2023 Global Overview Report, there are 5.19 billion people around the world using the internet in 2023. There’s an imperative need for businesses to trust their networks to deliver meaningful content to address customer needs.  So how responsive is the…

Kubernetes version 1.28 now available in IBM Cloud Kubernetes Service

2 min read - We are excited to announce the availability of Kubernetes version 1.28 for your clusters that are running in IBM Cloud Kubernetes Service. This is our 23rd release of Kubernetes. With our Kubernetes service, you can easily upgrade your clusters without the need for deep Kubernetes knowledge. When you deploy new clusters, the default Kubernetes version remains 1.27 (soon to be 1.28); you can also choose to immediately deploy version 1.28. Learn more about deploying clusters here. Kubernetes version 1.28 In…