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
vdd

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

Code

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("http://169.254.169.254/instance_identity/v1/token?version=2021-10-12",
                          headers={'Metadata-Flavor': 'ibm'})
    return json.loads(result.text)['access_token']

def get_volume_attachments(access_token):
    result = requests.get("http://169.254.169.254/metadata/v1/instance/volume_attachments?version=2021-10-12",
                          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(get_disk_device(volume_attachment['id']))
            sys.exit(0)
    else:
        print(f"Unable to find disk by volume {args.volume_uuid}")
        sys.exit(1)

if __name__ == '__main__':
    main()

Conclusion

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.