Quickstart Guide
This guide will walk users through a few foundational Ansible terms and concepts, introduce the HyperCore collection, and provide guidance on writing playbooks.
Introduction
Scale Computing recently launched the SC//HyperCore Collection for Ansible. This exciting tool gives MSPs and distributed edge organizations the ability to implement declarative configuration management in their HyperCore fleet. Ansible is an IT automation tool designed to automate server provisioning and management via playbooks. These playbooks are similar to scripts, but have two key benefits, namely: they are human readable and idempotent, meaning they can be run several times and are smart enough to only take actions that are required (and skip those that aren’t) to put a HyperCore cluster in the desired state. These benefits make Ansible ideal for managing large HyperCore fleets.
Overview and Terminology
Before you can begin writing playbooks and automating HyperCore management, we must first cover a few important concepts. First, it is important to note that Ansible is a powerful tool that gives users the ability to accomplish the same task in a myriad of different ways. It gives users the building blocks needed to automate their own processes. Thus, this guide only scratches the surface of what can be accomplished with Ansible.
Second, Ansible commands need to be run from an “Ansible Server” (also called an “Ansible Control Host”). In some cases, this is actually a dedicated physical server or VM, however this is not always necessary. Users can run ansible from a workstation, this local machine contains the necessary playbooks to run against the servers being managed.
Third, Open SSH is the default communication standard used by Ansible for remote administration. Crucially, this is not how Ansible will communicate with HyperCore clusters, as will be demonstrated later in this guide. Now, let us turn to important terms and concepts.
Inventory
Ansible is incredibly useful for managing many HyperCore clusters. Ansible relies on an inventory file to establish which clusters you want to target with your playbooks. This file is most commonly formatted in either INI or YAML and lists your clusters. For larger organizations, the inventory is also the ideal location to organize your fleet, particularly when you desire different cluster states based on different criteria (location, size, purpose, etc.). The most basic YAML-formatted inventory file is organized like this:
all:
hosts:
mail.example.com:
children:
webservers:
hosts:
foo.example.com:
bar.example.com:
dbservers:
hosts:
one.example.com:
two.example.com:
Three.example.com:
hosts denotes individual target servers (in the case of HyperCore you could point to a FQDN or IP address of a node in the cluster) while children: and signifiers like webservers: and dbservers: organize hosts into different categories. A small HyperCore inventory might look something like this:
Example Text
Ansible Configuration File
When running Ansible commands and writing playbooks it is important to specify where your inventory is and other configuration specifics, like your Ansible collection path. This file serves as the center to all of your server interactions.
Upon installing Ansible, you will be provided with a default configuration file (ansible.cfg). The default configuration is a large file that you can choose to use, however it is also fine to create your own simplified version. The most important thing is to make sure your work is referencing the correct configuration file. The easiest way to achieve this is by including an ansible.cfg in the directory where you are working with Ansible or setting it as an environment variable.
For the purposes of this guide, you need to make sure your configuration file specifies where your inventory is located. All that is required is to set inventory = [folder that contains your inventory in your working ansible directory]. You can reference a specific file or an entire inventory folder. An example of a simple configuration file looks like this:
Ansible Configuration File Example
Ansible Module
Now that you are familiar with Ansible inventories and configuration files we can turn to the meat of Ansible and the HyperCore collection: modules. Ansible Modules are units of code that can control the servers that you are managing with Ansible. After installing Ansible, you will have access to a library of modules that give you the ability to execute specific tasks on remote servers through playbooks and individual commands. Scale Computing has made managing your HyperCore fleet via Ansible possible by developing our own set of modules that call existing cluster REST API endpoints. Extensive documentation on our current available modules can be found here.
For example: scale_computing.hypercore.vm is the module that will allow you to create, update, and delete virtual machines. When you begin writing playbooks, you will reference a specific module when attempting to automate a task associated with that said module is equipped to handle.
Ansible Playbook
Finally, playbooks are the most important piece of Ansible. Playbooks allow you to automate tasks that would normally need to be done more than once across the clusters in your fleet. While similar to scripts, playbooks are much easier to write because they are human readable. Additionally, we have in-depth documentation about every module available in the Ansible collection, with specific examples of how each module can be written as a task that is part of a playbook. Additionally, playbooks and Ansible are idempotent, meaning that they are smart enough to know if a cluster already has a desired configuration and skip tasks that do not need repeated.
At a high level, playbooks typically begin with the author specifying which hosts (in our case HyperCore clusters) are going to be targeted. They will then establish the method by which Ansible will connect to the remote hosts (in our case this will be connection: ansible.builtin.local). Once these have been established, the author can begin writing tasks in the order in which they will be carried out; calling out the necessary ansible modules and module parameters along the way.
In a future section, you will get an overview of how to start writing your own playbooks.