Create and Connect a Client

Get the System JWT from Azure Portal

1. Log in to the Azure portal.
2. Click the managed application that you created (it should be in the resource group that was defined during the deployment).

3. Click the managed resource group.
4. You will see a list of all the resources created for the cluster.
5. Click the Key vault.
6. Go to the Access Control menu.

7. Click Add Role Assignment.
8. Select the Key Vault Secrets User role.
9. Click Next.
10. Click Add Member.

11. Choose the user that will be able to read the JWT.
12. Click Review and Assign.
13. Go to the Secrets menu in the Key vault.

14. Click the system JWT or the Admin JWT of the default Project.
15. Click the current version of the secret.
16. Click Show Secret.
17. Copy the secret value.

Create a Client Virtual Machine

To connect to Lightbits volumes, you will need a VM to map the volumes to. This VM must be accessible via SSH using a direct SSH connection or a Bastion Host.

This section details how to deploy the client VM through the Azure portal. Use the checklist outlined in the Gathering Information About the Deployment Environment section for any inputs.

1. Access the Azure portal using the common link ms.portal.azure.com, and log in using your Azure credentials.
2. Once in the portal, use the search bar and search for Virtual Machines, and then click on the entry.

3. Inside the Virtual machines blade, click the + Create drop-down and select Azure virtual machine.
4. Inside the Create a virtual machine blade, select the Subscription and Resource group that will be used for the deployment.

5. Under Instance details, enter you Virtual machine name, Region, Image and Size. For the purposes of functional testing, we will use Ubuntu 22.04 and D2s_v3 as the selections. You can change these based on your requirements.

6. Under Administrator account, choose your authentication method. You can choose the same authentication that you used for the Lightbits cluster.

7. Leave the Inbound port rules as default and click Next: Disks.

8. Leave the Disks tab as default and click Next: Networking.

9. In the Network interface section, choose the vNet and subnet that will be used.

10. We will use a Public IP, so here we selected a public IP with a Basic network security group with SSH allowed. If you are using a bastion and NAT gateway, you can choose None.

11. Leave the rest as the defaults and select Review + create.

12. Here you can review the information, and when validation has passed, click Create to deploy the VM.

Azure will redirect you to a Deployment blade, where you can track the progress of the deployment.

Once the blade shows that the deployment is complete, validate the deployment by clicking Go to resource.

Connect to the Client Virtual Machine

For additional information, see the Azure documentation on Connecting to a VM.

Using an SSH Client

1. To SSH using an SSH client, you'll need the IP address of the virtual machine. To get the public IP address, navigate to the Azure portal and to the Virtual machines blade. Find your Virtual machine and get the public IP address.

2. Use your preferred SSH tool - such as PuTTY from Windows or a terminal from Unix - to SSH into the virtual machine.

Using a Bastion Host

1. To use a bastion host, navigate to the virtual machine that you want to connect to and click on the virtual machine name.

2. In the virtual machine overview blade, click Connect.

3. Click Bastion. If this is the first time you are using a Bastion inside the vNet, click Use Bastion.

4. Follow the process to create a Bastion subnet inside your vNet and wait for Azure to create the Bastion host. This process will take a few minutes. When the process is complete, you will be able to connect to the VM through the bastion host.

Configure the Client

1. SSH into the client virtual machine.
2. Check if nvme_tcp driver is enabled:

sudo modinfo nvme_tcp

3. If the response shows an error message, run the following to install the extras package for Azure Linux:

sudo apt install -y linux-modules-extra-azure

sudo modprobe nvme_tcp

4. Check client hostnqn:

cat /etc/nvme/hostnqn

5. If there is not a response or the file does not exist, install nvme-cli:

sudo apt install -y nvme-cli

6. Note the client's hostnqn. This will be used as the Lightbits volume "ACL" later.

Create Volume

Find Lightbits Node Virtual Machine

1. Navigate to the managed application resource group and click on the virtual machine scale set (VMSS).

2. In the VMSS blade, click Instances.

3. Click the first entry to bring up the virtual machine blade.

4. Here you can find the IP address of the instance too SSH from the client as a jump host or use a bastion.

Find Private Management and Discovery Address

1. Navigate to the managed application resource group and click the *-lb-private Load balancer.

2. Select Frontend IP configuration.

3. The discovery and management IP for the cluster is under IP address.

Create a Volume

1. SSH into a Lightbits virtual machine.
2. To export the JWT as an environment variable, paste the JWT code from the Get the System JWT from Azure Portal section.
3. Check that the JWT has been exported correctly by running:

echo $LIGHTOS_JWT

4. Create a volume:

lbcli -J $LIGHTOS_JWT create volume --project-name default --compression true --replica-count 3 --size 100GiB --acl {client_hostnqn} --name testvol0

5. Check that the volume is ready:

lbcli -J $LIGHTOS_JWT list volumes

6. Ensure that the State value is Available.

Map a Volume to the Client

1. SSH to the client virtual machine.
2. Run the connect command:

sudo nvme connect-all -a {lightbits_discovery_mgmt_address} -t tcp

3. Verify that the disk has been attached:

sudo nvme list

4. The output should look similar to:

5. You can see the paths that the volume is using by running:

sudo nvme list-subsys {volume_path}

6. The output looks similar to the below example. Here, there are three copies of data and three paths, each pointing to a Lightbits node that holds a copy of the volume. The primary node is currently 172.22.0.5.

7. The volume can now be given a filesystem and mapped to a directory on the client, or used in a raw block mode ready for workloads.