In my last home lab blog post, I talked about working with Nutanix Community Edition (CE).  I’ve been spending a lot of time with CE while migrating my home lab workloads over to it.

One of the things I’ve been working on is increasing the storage in my lab cluster. When I originally built my lab cluster, I used the drives that I had on hand.  These were a mixed bag of consumer-grade 1TB SATA and NVME SSDs that worked with my PowerEdge R630s.  It worked great, and I was able to get my cluster built.  

Then I stumbled onto some refurbished Compellent SAS SSDs on eBay, and I wanted to upgrade my cluster.  

While there are some blog posts that cover adding or replacing drives in CE, those posts are for older versions.  The current version of CE at the time of this post is CE 2.1, and it has some significant changes compared to the older versions.  Those directions would work to a point – I could get the new disk imported into my CE cluster, but they would disappear if I shut down or rebooted the host.

You’re probably asking yourself why this is happening.  It’s Nutanix. I should be able to plug in a new disk and have it added into my cluster automatically, right?

Technical Differences Between CE and Commercial Nutanix   

There are some differences between the commercial Nutanix products and CE.  While CE is using the same bits as the commercial AOS offering, it is designed to run on uncertified hardware.  CE can run on NUCs or even as a nested virtual machine as long as you meet the minimum storage requirements.

Commercial Nutanix products will use PCI Passthrough to present the storage controller to the CVM, and the CVM will directly manage any SATA or SAS disks that are installed. This only works with certified SAS HBAs that are found in enterprise-grade servers. CE does not pass the storage controller through to the CVM virtual appliance. Most hardware used in a home lab will not have a supported storage controller, and even if one is present, there is a good chance that the hypervisor boot disk will also be attached to this storage controller.

CE gets around this by passing each SATA or SAS disk through to the CVM individually by reference values like the WWN and Device ID.  This means that you can move the drives to different slots and they will still mount in the same place on the CVM.  CE will also map the disk’s device name as its drive slot – so if a disk’s device name in /sda, for example, CE will map it to slot 1.  This is a little different than a commercial Nutanix system where the disk slot is mapped to a physical slot on the server or HBA.

The disk’s Device ID, UUID and WWN are also provided to the CVM, and this can cause some fun errors if the mounting order or device name changes.  If an existing disk mounted as /sda changes to /sdb, CE will still try to assign it to Slot 1. You may see errors in the Hades log that say “2 disks in one slot” that prevent you from using the new disk.

Adding or replacing disks should be pretty simple then. We just need to edit the CVM’s definition file and update it with the new drive information. Right?  

You’d think that, but that leads right into the second problem I mentioned earlier: the new drives would disappear when the host was rebooted. And to make this issue a little worse, I would see errors about unmounted or missing drives in Prism after the reboot.

So what’s happening here?

After looking into this and talking with the CE lead at Nutanix, I learned that the CVM definition file is regenerated on every host reboot. So if I make a change to the CVM definition, it will be rolled back to its “known configuration” the next time the host is powered on.  Generally speaking, this is a great idea, but in this case, we want to change our CVM configuration and don’t want it to revert on a reboot.

We’ll need to edit a file called cvm_config.json on our host to make our changes permanent. 

There is just one other little thing. The CVM’s disk device names are determined by the order they are listed in the cvm_config.json file. The first disk on the list will be named /sda, second disk as /sdb, etc. And as I said above, the Hades service that manages storage equates the new disk’s device name with the disk slot, and existing disks may also be assigned to that slot if it previously used that device name. This could prevent you from using the new disk and generate “two disks in one slot” error messages in the Hades log if the mounting order changes..

Adding and/or Replacing Disks

So how do we add or replace a disk on Nutanix CE?  Here are the steps that I took in my lab to replace SATA SSDs with SAS SSDs.  NVME drives are PCI Passthrough devices, and I won’t be covering them in this post.

This process will be making changes to your lab environment. Make sure you have backed up any important data before taking these steps, and remember that you are doing these at your own risk.

Removing an Old Disk

The first step I like to take when replacing a disk is to remove the disk I am replacing.  This step isn’t required, but I like to remove the disk first to evacuate any data from it before I make any changes.  If you’re just adding a new disk and not replacing an old one, you can skip to the next section.

To remove our disk, we need to start in Prism. Go to the dropdown menu located at the top of the screen and select Hardware

Click Table (1) and then Disks (2)

Locate the disk you want to remove. The easiest way to do this is by searching for the disk’s serial number.  Right click on the disk and select Remove.  I will also write down the serial number because I will need it later.

This will start the process of evacuating data from the disk, and it may take some time to complete. After the data has been evacuated from the disk, it will be unmounted and removed from the list.  

Entering Maintenance Mode

Before we can shut down the host to replace our disks, we need to prepare the host and/or cluster for maintenance.  There are two ways to do this, and the option you select will depend on how many hosts are in your CE cluster.

If you have a 3 or 4 node CE cluster, then you can place your host into maintenance mode.  This will migrate all running VMs to another host and shut down the CVM for you.  The steps to put a host into maintenance mode are:

Click on Table -> Hosts.

Right click on the host you want to put into maintenance mode and select Enter Maintenance Mode.

When you enter maintenance mode, all VMs will be migrated to another host in the cluster before that host’s CVM is shut down.  It will stay in maintenance mode until you take it out of maintenance mode.

If you only have a single host in your cluster, you will need to shut down all powered-on VMs, manually stop the cluster from the CVM’s command line, and then shut down the CVM.

Once our CVM is shut down, we need to shut down our host to install our new drive or drives. AHV will not detect any new drives without a reboot. So we will need to reboot the server even if we are using enterprise-grade hardware with a storage controller that supports hot-adding drives.

Configuring AHV to Use New Disks

Once our new drives are installed, we can power our host back on.  When it has finished booting, we need to SSH into AHV.  We will need root privileges for the next couple of steps, so you will need to either use the root account or use an account with sudo privileges.  When I was doing this in my lab, I logged in as the admin user and ran sudo su – root to switch to the root user to perform the next steps.

Before we do anything else, we need to back up our CVM configuration file.  This is the file that AHV will use to regenerate the CVM’s virtual machine definition.  The command to back up this file is below.

Root user: cp /etc/nutanix/config/cvm\_config.json /etc/nutanix/config/cvm_config.backup
Admin user:sudo cp /etc/nutanix/config/cvm\_config.json /etc/nutanix/config/cvm_config.backup

Next, we need to validate that our new drives are showing up and mounted properly.  We also want to get the device name for the new drive because we will need that to get other information we need in the next step.  The command we need to run is lsblk or sudo lsblk if we’re not the root user.

Next, we need to retrieve our drive’s device identifiers.  These include the SATA or SCSI name and the WWN.  We will use these when we update our CVM config file to identify the drive that needs to be passed through to the CVM.  The command to retrieve this is below.

Root User: ls -al /dev/disk/by-id/ | grep <device name>
Admin User: sudo ls -al /dev/disk/by-id/ | grep <device name>

Next, we will need to generate a unique UUID for the drive we will be installing.  The command to generate a uuid is uuidgen. 

Finally, we will need to retrieve the drive’s vendor, product ID, and serial number. We can use the smartctl command to retrieve this. Smartctl works with both SATA and SAS drives.  The command to get this information is below.  If you are planning to install a SATA drive, you’ll want to mark the vendor down as ATA as this is how Nutanix appears to consume these drives.

Root user: smartctl -i /dev/<device name>
Admin user: sudo smartctl -i /dev/<device name>

So now that we’ve retrieved our new disk’s serial number, WWN, and other identifiers, we need to update our CVM definition file.  We do this by editing the cvm_config.json file we backed up in an earlier step.

Root user: nano /etc/nutanix/config/cvm_config.json
Admin user:sudo nano /etc/nutanix/config/cvm_config.json

The cvm_config.json file is a large file, so we will want to navigate down to the VM_Config -> Devices -> Disks section.  If we are replacing a disk, we’ll want to locate the entry for the serial number of the disk we’re replacing and update the values to match the new disk. 

If we are adding a new disk to expand capacity, you need to create a new entry for a disk.  The easiest way to do this in my experience is to copy an existing disk, paste it at the end of our disk block, and then replace the values in each field with the ones for your new disk.

There are a few  things that I want to call out here.  

• If your new disk is a SATA disk, the vendor should be ATA. If you are adding or replacing a SAS drive, you should use the vendor data you copied when you ran the smartctl command.
• The UUID field needs to start with a “ua-”, so you would just add this to the front of the UUID you generated earlier using the uuidgen command.  The UUID line should look like this: “uuid”: “ua-<uuid generated by uuidgen command>”,

Once we have all of our disk data entered into the file, we can save it and reboot our host.  During the reboot process, our CVM definition file will be regenerated and the new disks will be attached to the CVM virtual machine.  Once our host is online, we can SSH back into it to validate that our CVM still exists before powering it back on.  The commands that we need to run from the host to perform these tasks are:

virsh list --all
virsh start <CVM VM>

You can also view the updated CVM config to verify that the new disks are present with the following command:

Virsh edit <CVM VM>

Once our CVM is powered on, we need to SSH into it and switch to the nutanix user.  The nutanix user account is the account that all the nutanix services run under, and it is the main account that has access to any logs that may be needed for troubleshooting.  

The main thing we want to do is verify that the CVM can see our disks, and we will use the lsblk command for that.  Our new disks should be showing up at this point, so you can take the host out of maintenance mode or restart the cluster.

The new disk should automatically be adopted and added into the storage pool after the Nutanix services have started on the host.  

Troubleshooting

Additional troubleshooting will be needed if the disk isn’t added to the storage pool automatically, and/or you start seeing disk-related errors in Prism.  This post is already over 2000 words, so I’ll keep this brief.

The first thing to do is check the hades service logs.  This should give you some insight into any disk issues or errors that Nutanix is seeing.  You can check the Hades log by SSHing into the CVM and running the following command as the nutanix user: cat data/logs/hades.out

You may also need to add your new disk to the hcl.json file.  This file contains a list of supported disks and their features.  The hcl.json file is found in /etc/nutanix/.  Due to this post’s length, how to edit the file and add a new disk is also beyond the scope of this post.  I’ll have to follow this up with another post.

I would also recommend joining the Community Edition forums on the Nutanix .Next community.  Nutanix staff and community members can help troubleshoot any issues that you have.