Home Integrated Products VxRail Blogs

Take VxRail automation to the next level by leveraging APIs

Wed, 03 Aug 2022 21:32:15 -0000

Read Time: 0 minutes

Karol Boguniewicz

VxRail REST APIs

The Challenge

VxRail Manager, available as a part of HCI System Software, drastically simplifies the lifecycle management and operations of a single VxRail cluster. With a “single click” user experience available directly in vCenter interface, you can perform a full upgrade off all software components of the cluster, including not only vSphere and vSAN, but also complete server hardware firmware and drivers, such as NICs, disk controller(s), drives, etc. That’s a simplified experience that you won’t find in any other VMware-based HCI solution.

But what if you need to manage not a single cluster, but a farm consisting of dozens or hundreds of VxRail clusters? Or maybe you’re using some orchestration tool to holistically automate the IT infrastructure and processes? Would you still need to login manually as an operator to each of these clusters separately and click a button to maybe shutdown a cluster, collect log information or health data or perform LCM operations?

This is where VxRail REST APIs come in handy.

The VxRail API Solution

REST APIs are very important for customers who would like to programmatically automate operations of their VxRail-based IT environment and integrate with external configuration management or cloud management tools.

In VxRail HCI System Software 4.7.300 we’ve introduced very significant improvements in this space:

Swagger integration - which allows for simplified consumption of the APIs and their documentation;
Comprehensiveness – we’ve almost doubled the number of public APIs available;
PowerShell integration – that allows consumption of the APIs from the Microsoft PowerShell or VMware PowerCLI.

The easiest way to start using and access these APIs is through the web browser, thanks to the Swagger integration. Swagger is an Open Source toolkit that simplifies Open API development and can be launched from within the VxRail Manager virtual appliance. To access the documentation, simply open the following URL in the web browser: https://<VxM_IP>/rest/vxm/api-doc.html (where <VxM IP> stands for the IP address of the VxRail Manager) and you should see a page similar to the one shown below:

Figure 1. Sample view into VxRail REST APIs via Swagger

This interface is dedicated for customers, who are leveraging orchestration or configuration management tools – they can use it to accelerate integration of VxRail clusters into their automation workflows. VxRail API is complementary to the APIs offered by VMware.

Would you like to see this in action? Watch the first part of the recorded demo available in the additional resources section.

PowerShell integration for Windows environments

Customers, who prefer scripting in Windows environment, using Microsoft PowerShell or VMware PowerCLI, will benefit from VxRail.API PowerShell Modules Package. It simplifies the consumption of the VxRail REST APIs from PowerShell and focuses more on the physical infrastructure layer, while management of VMware vSphere and solutions layered on the top (such as Software-Defined Data Center, Horizon, etc.), can be scripted using similar interface available in VMware PowerCLI.

Figure 2. VxRail.API PowerShell Modules Package

To see that in action, check the second part of the recorded demo available in the additional resources section.

Bringing it all together

VxRail REST APIs further simplify IT Operations, fostering operational freedom and a reduction in OPEX for large enterprises, service providers and midsize enterprises. Integrations with Swagger and PowerShell make them much more convenient to use. This is an area of VxRail HCI System Software that rapidly gains new capabilities, so please make sure to check the latest advancements with every new VxRail release.

Additional resources:

Demo: VxRail API - Overview

Demo: VxRail API - PowerShell Package

Dell EMC VxRail Appliance – API User Guide

VxRail PowerShell Package

VxRail API Cookbook

VMware API Explorer

Author: Karol Boguniewicz, Sr Principal Engineer, VxRail Tech Marketing

Twitter: @cl0udguide

Tags:

Getting Started

Ansible Modules for Dell VxRail are available publicly from the standard code repositories: Ansible Galaxy and GitHub. You don't need a Dell Support account to download and start using them.

Requirements

The requirements for the specific version are documented in the "Prerequisites" section of the description/README file.

In general, you need a Linux-based server with the supported Ansible and Python versions. Before installing the modules, you have to install a corresponding, lightweight Python SDK library named "VxRail Ansible Utility," which is responsible for the low-level communication with the VxRail API. You must also meet the minimum version requirements for the VxRail HCI System Software on the VxRail cluster.

This is a summary of requirements for the latest available version (1.4.0) at the time of writing this blog:

Ansible Modules for Dell VxRail	VxRail HCI System Software version	Python version	Python library (VxRail Ansible Utility) version	Ansible version
1.4.0	7.0.400	3.7.x	1.4.0	2.9 and 2.10

Installation

You can install the SDK library by using git and pip commands. For example:

git clone https://github.com/dell/ansible-vxrail-utility.git

cd ansible-vxrail-utility/
pip install .

Then you can install the collection of modules with this command:

ansible-galaxy collection install dellemc.vxrail:1.4.0

Testing

After the successful installation, we're ready to test the modules and communication between the Ansible automation server and VxRail API.

I recommend performing that check with a simple module (and corresponding API function) such as dellemc_vxrail_getsysteminfo, using GET /system to retrieve VxRail System Information.

Let's have a look at this example (you can find the source code on GitHub):

Note that this playbook is run on a local Ansible server (localhost), which communicates with the VxRail API running on the VxRail Manager appliance using the SDK library. In the vars section, , we need to provide, at a minimum, the authentication to VxRail Manager for calling the corresponding API function. We could move these variable definitions to a separate file and include the file in the playbook with vars_files. We could also store sensitive information, such as passwords, in an encrypted file using the Ansible vault feature. However, for the simplicity of this example, we are not using this option.

After running this playbook, we should see output similar to the following example (in this case, this is the output from the older version of the module):

Cluster expansion example

Now let's have a look at a bit more sophisticated, yet still easy-to-understand, example. A typical operation that many VxRail customers face at some point is cluster expansion. Let's see how to perform this operation with Ansible (the source code is available on GitHub):

In this case, I've exported the definitions of the sensitive variables, such as vcpasswd, mgt_passwd, and root_passwd, into a separate, encrypted Ansible vault file, sensitive-vars.yml, to follow the best practice of not storing them in the clear text directly in playbooks.

As you can expect, besides the authentication, we need now to provide more parameters—configuration of the newly added host—defined in the vars section. We select the new host from the pool of available hosts, using the PSNT identifier (host_psnt variable).

This is an example of an operation performed by an asynchronous API function. Cluster expansion is not something that is completed immediately but takes minutes. Therefore, the progress of the expansion is monitored in a loop until it finishes or the number of retries is passed. If you communicated with the VxRail API directly by using the URI module from your playbook, you would have to take care of such monitoring logic on your own; here, you can use the example we provide.

You can watch the operation of the cluster expansion Ansible playbook with my commentary in this demo:

Getting help

The primary source of information about the Ansible Modules for Dell VxRail is the documentation available on GitHub. There you'll find all the necessary details on all currently available modules, a quick description, supported endpoints (VxRail API functions used), required and optional parameters, return values, and location of the log file (modules have built-in logging feature to simplify troubleshooting— logs are written in the /tmp directory on the Ansible automation server). The GitHub documentation also contains multiple samples showing how to use the modules, which you can easily clone and adjust as needed to the specifics of your VxRail environment.

There's also built-in documentation for the modules, accessible with the ansible-doc command.

Finally, the Dell Automation Community is a public discussion forum where you can post your questions and ask for help as needed.

Conclusion

I hope you now understand the Ansible Modules for Dell VxRail and how to get started. Let me quickly recap the value proposition for our customers. The modules are well-suited for IaC use cases, thanks to automating holistic workflows and idempotency. They are maintained by Dell and supported by the Dell Automation Community, which reduces risk. These modules are much easier to use than the alternative of accessing the VxRail API on your own. We provide many examples that can be adjusted to the specifics of the customer’s environment.

Resources

To learn more, see these resources:

On-demand recording of the recent Tech Exchange Live session: "Infrastructure as Code with VxRail," where I dive a bit deeper into the Ansible Modules for VxRail, and my colleague Steffen from VMware discusses the basics of Terraform integration with VxRail.
Ansible Modules for Dell VxRail on GitHub, which is the central code repository for the modules. It also contains complete product documentation and examples.
Try the new VxRail API Hands-on-Lab available in the Dell Technologies Demo Center, which we introduced at Dell Technologies World earlier this year. Module 3: Cluster Expansion or Scaling Out allows you to get hands-on experience with the modules without the need to have access to a VxRail system. Your Dell account team can help you access the lab.

The following links provide additional information:

Author: Karol Boguniewicz, Senior Principal Engineering Technologist, VxRail Technical Marketing
Twitter: @cl0udguide

HCI VxRail API UPS

Protecting VxRail From Unplanned Power Outages: More Choices Available

Thu, 16 Jun 2022 18:06:44 -0000

Read Time: 0 minutes

In my previous blog, Protecting VxRail from Power Disturbances, I described the first API-integrated solution that helps customers preserve data integrity on VxRail if there are unplanned power events. Today, I'm excited to introduce another solution that resulted from our close partnership with Schneider Electric (APC).

Why is it important?

Over the last few years, VxRail has become a critical HCI system and data-center building block for over 15,000 customers who have deployed more than 220,000 nodes globally. When HCI was first introduced, it was often considered for specific workloads such as VDI or ROBO locations. However, with the evolution of hardware and software capabilities, VxRail became a catalyst in data-center modernization, deployed across various use cases from core to cloud to edge. Today, customers are deploying VxRail for mission-critical workloads because it is powerful enough to meet the most demanding requirements for performance, capacity, availability, and rich data services.

Dell Technologies is a leader in data-protection solutions and offers a portfolio of products that can fulfill even the most demanding RPO and RTO requirements from customers. In addition to using traditional data-protection solutions, it is best practice to use a UPS to protect the infrastructure and ensure data integrity if there are unplanned power events. In this blog, I want to highlight a new solution from Schneider Electric, the provider of APC Smart-UPS systems.

The APC UPS protection solution for VxRail

Schneider Electric is one of Dell Technologies’ strategic partners in the Extended Technologies Complete Program. It provides Dell Technologies with APC UPS and IT rack enclosures offering a comprehensive solution set of infrastructure hardware, monitoring, management software, and service options.

PowerChute Network Shutdown in version 4.5 seamlessly integrates with VxRail by communicating over the network with the APC UPS. If there is a power outage, PowerChute can gracefully shut down VxRail clusters using the VxRail API. As a result of this integration, PowerChute can run on the same protected VxRail cluster, saving space and reducing hardware costs.

Solution components:

VxRail cluster with VxRail HCI System Software version 7.0.320, 4.7.540 or higher
Dell Smart-UPS Online 5kVA DLRT5KRMXLT or Dell Smart-UPS Online 3kVA DLRT3000RMXLA
UPS Network Management Card 3 (AP9640, AP9640, or AP9643) with NMC firmware version v2.2 or higher
Either a 1-Year or 3-Year PowerChute license for each VxRail node in the cluster (PowerChute Network Shutdown software version 4.5 or higher)

Key benefits of this solution include:

Unattended, graceful shutdown of virtual machines (VMs), followed by the VxRail cluster that avoids data corruption thanks to integration with the VxRail API.
Minimal downtime after critical events have passed with a pre-configured automated start-up sequence, which is useful at remote or unattended sites.
Full deployment within the VxRail cluster saves space and reduces hardware requirements since you don't have to deploy PowerChute on a separate machine outside the cluster.
Edge-ready with support for Edge-ready vSAN architecture with vSAN 2-node clusters.
Redundant VxRail API-based cluster shutdown. In a redundant UPS set-up, if one NMC3 is offline, PowerChute will connect to one or more available NMC3s to carry out the VxRail cluster shutdown.

How does it work?

This is easiest to describe using the following diagram, which covers the steps taken in a power event and when the event is cleared:

How PowerChute Network Shutdown works with VxRail

I highly recommend watching the demo of this solution in action, which is listed in the Additional resources section at the end of this blog.

Summary

Protection against unplanned power events should be a part of a business continuity strategy for all customers who run their critical workloads on VxRail. This practice ensures data integrity by enabling automated and graceful shutdown of VxRail clusters. Customers now have more choice in providing such protection, with the new version of PowerChute Network Shutdown software for APC UPS systems integrated with VxRail API and validated with VxRail.