SolidFire’s architecture and API provides a wide range of capabilities. However, implementation of some features, and the collection of some information, requires connecting to both SolidFire Nodes and Clusters. The Connect-SFCluster cmdlet provides the necessary parameters and capabilities to service a wide range of needs. In this post we’ll discuss the Connect-SFCluster cmdlet and the various ways it will be used with the SolidFire Tools for PowerShell.
Basic Connectivity
The most common use of the Connect-SFCluster cmdlet is to connect to the management virtual IP address, or MVIP, of the SolidFire cluster. Connecting to a cluster requires providing the target IP address, or FQDN, as well as appropriate credentials. In its simplest form you would have:
Connect-SFCluster xnode-api-dev1
Since credentials are not provided in the call the user will be prompted to input them. I will share more on credentials in a moment. Let’s first talk about targets for Connect-SFCluster.
Clusters vs Nodes
The SolidFire API provides a wide range of API calls, but not all of them are designed to be directed at the cluster itself. There are many calls that are designed to be targeted to individual nodes, such as Get-SFConfig.
This cmdlet would require that we connect directly to the node we wish to query. We can do that using the -Node parameter.
Connect-SFCluster -Target xnode-01 -UserName admin -Password yourpassword -Node
The Node parameter serves as a switch to notify the cmdlet that you are connecting to a node. This is required in order to execute node-specific cmdlets. The credentials you provide will have to be a cluster admin credential, which has access to the nodes.
Managing Credentials
You may have noticed that I have made the connections using a few parameters related to providing credentials. Since scripts are often run without human interaction it will be necessary to provide the connection credentials within the script. The Connect-SFCluster enables a couple of ways to handle this.
If you’d like to enter the credentials at execution you can enter the following:
Connect-SFCluster -Target xnode-api-dev1 -UserName admin -Password yourpassword
This puts your credentials in plain text, which is not advisable. I’m not a fan of this method in a script, though it may be fine when working directly in the shell.
My preferred method of managing credentials is by building a PSCredential object using the cmdlet Get-Credential. This cmdlet will prompt the user for credentials with a dialog box. Those credentials are then stored in a PSCredential object that persists with the session.
This allows you to use the same credential object for multiple connections.
$cred = Get-Credential Connect-SFCluster -Target xnode-api-dev1 -Credentials $cred
I know what you’re saying. “Josh, that requires human interaction and may not work in a scheduled script.”
You are absolutely correct. PowerShell supports storing these credentials into a file which can be read in later. I’ll touch on this in a future post.
Downgrading API Versions
Automation capabilities is one of the key tenets of a SolidFire system and one of the many features that transform how our customers provide services in their environments. Our customers invest time and energy developing scripts and tools that leverage our API. We recognize this and make previous Element OS versions of the API available on the system to ensure customers can upgrade without having to do rewrites in the event that API calls change due to new features or capabilities. This allows our customers to upgrade with confidence, and allows SolidFire to continue to innovate and not be burdened with maintaining excessive legacy code.
We have incorporated this capability into the SolidFire tools for PowerShell as well. We provide the ability to select an earlier API version using the -VersionAPI parameter.
Let’s say you recently upgraded to the latest Element OS, Oxygen (8.0). You can simply update the Connect-SFCluster command to maintain consistent operations with what you had with Element OS Nitrogen (7.0.
Connect-SFCluster -Target xnode-api-dev1 -Credential $cred -VersionApi 7
If a version is not specified using the -VersionApi parameter the cmdlet will query the cluster for the most recent installed version and use that for the connection.
Global Variables
SolidFire simplifies operations and allows organizations to consolidate multiple workloads on a single cluster. Many customers maintain multiple clusters and for each cluster there is certainly multiple nodes. This presents some challenges when working with so many distinct targets, especially since there are cmdlets that are node-specific as mentioned previously.
We help simplify this with the use of global variables, much like you see with PowerCLI and their use of $defaultviserver(s). When a connection is made using Connect-SFCluster the SolidFire Tools for PowerShell stores that information into both the $sfconnection and $sfconnections global variables. Multiple connections are stored in $sfconnections while $sfconnection stores only the last connection made.
This functionality works with both nodes and clusters together, which allows users the ability to easily leverage this connection information to specifically target cmdlets to certain node or cluster connections. You’ll note in the upcoming 1.0 release the ability to direct cmdlets using the -Target parameter and only required to provide the name of the connection.
Simply enter $sfconnections.Name to see all of the available names.
Closing Notes
I know this is quite a bit of content on a single cmdlet, but it can’t be overstated how important and valuable being able to create and manage connection information in your SolidFire environment. We’ll continue to work hard to make the SolidFire Tools for PowerShell as easy to use as possible. In upcoming posts I’ll start discussing how to deploy resources on a SolidFire cluster and manage various aspects of the system. In the mean time check out our GitHub PowerShell repo. Thanks for reading and always I welcome your questions and comments.