If you are new to VM management, it is good to do certain things manually and to learn how the system works. However, once you know the basics you quickly realise there is much more utility in automating the mundane repetitive task. Ansible is the tool that enables us to automate server setup in a flexible, error-resistant way. It has certain benefits over writing your own scripts in POSIX Shell or Bash, and we will get to these benefits over the course of this tutorial.<\/p>\n<\/p>\n
Before we get into the specific details, it is important to state what we are trying to accomplish, here. The playbook we are about to write will:<\/p>\n
root<\/code> user, allowing us to login as the root user using our public-private SSH Key pair. Here's an introduction to SSH and SSH keys<\/a><\/li>\n- Disable password-based authentication and allow only key-based logins which are much secure.<\/li>\n
- Update all the packages on the system. Equivalent to running
apt update; apt upgrade<\/code> on Ubuntu or dnf update<\/code> on CentOS and Fedora.<\/li>\n<\/ol>\nSo let's get started.<\/p>\n
Ansible Installation and Basics<\/h2>\n
On your Control Node, Ansible can be installed using your system's package manager or Python's Package manager pip<\/code>, since Ansible is written in Python. On macOS, it is recommended that you install it using pip<\/code> or pip3<\/code>:<\/p>\n$ pip install -U ansible<\/code><\/pre>\nOn Linux, you can get it straight from your system's package manager:<\/p>\n
$ apt install ansible # For Debian or Ubuntu based systems\n$ dnf install ansible # For RedHat, Fedora or CentOS based systems<\/code><\/pre>\nOn your Target Host no prior installation is necessary. As long as the Ansible Host has an SSH daemon running and, Python3 installed you are good. All the Linux VMs that you can get on SSDNodes (or any other cloud provider) would readily work with Ansible without any manual intervention. For this reason, Ansible is called an agentless automation engine<\/strong>. Because you don't have to install any specific software on the target.<\/p>\nSo now we also know how Ansible works. <\/p>\n
\n- It uses SSH to authenticate and take control of a Host, which means using it is as secure as our SSH connection, and we don't have to worry about additional security threats. <\/li>\n
- It uses Python3 (Python2 works but is deprecated, and not recommended) to run all the automation, checks and data collection on the hosts.<\/li>\n<\/ol>\n
Configuring Ansible<\/h2>\n
There are three key files needed on the control node:<\/p>\n
\n- Ansible Playbook(s)<\/strong> describing what automation to run on your hosts. This will be our main focus.<\/li>\n
- An inventory<\/strong> file listing all your hosts and grouping them together in logical ways. On most Linux distros this file is
\/etc\/ansible\/hosts<\/code><\/li>\n- Ansible's configuration file<\/strong>. On most Linux distros this file is
\/etc\/ansible\/ansible.cfg<\/code><\/li>\n<\/ol>\nFor the sake of consistency we would like to have everything, the configuration, the inventory and playbooks, in one folder. So we create a folder called playbooks and create the inventory and configuration files inside it:<\/p>\n
$ mkdir playbooks\n$ touch ansible.cfg inventory<\/code><\/pre>\nAnsible will automatically pick the current directory's ansible.cfg<\/code> file and override the main configuration with this one. Edit the ansible.cfg<\/code> file and add the following contents to it:<\/p>\n[defaults]\ninventory = .\/inventory<\/code><\/pre>\nThis will set the current directory's inventory<\/code> file to be the inventory for our playbooks. Because we are starting small, with just one VPS, we will add just one line to the inventory here, this will be the IP address (or Domain name) of your VPS. Make sure to use your actual IP address and not what is shown below<\/strong>:<\/p>\n127.0.0.1<\/code><\/pre>\nThe offical documentaion shows how you can create more complicated inventory capable of organizing hundreds of servers into dozens of categories<\/a>.<\/p>\nWe are targeting only one server, so we just added that one line here. If you want to save the playbooks to a git repo, make sure that you don't include the inventory file with it, especially if it contains sensitive information such as the IP Addresses of all your servers.<\/p>\n
Writing the playbook<\/h2>\n
A playbook is essentially a description of how you desire the host system to be, also known as the desired state of the system. It is written in YAML, which, if you are unfamiliar, is language similar to JSON or XML but much more human readable while simulatenously being unambigious to a computer program. Think of it as a way of describing and structuring data, rather than writing a set of instructions like in a script or a program.<\/p>\n
Create a file called initial-setup.yaml<\/code> and we can start building our playbook. The following first few lines <\/p>\n---\n- name: Initial Setup\n hosts: all\n remote_user: root\n<\/code><\/pre>\nThe beginning ---<\/code> describes the start of a YAML file, and is optional. Next, we create a list with each element of the list starting with -<\/code>. There are going to be lists within lists in our yaml file and this is the outermost list, with just one item in it.<\/p>\nThe first element of this outermost list contains an Object (objects are like dictionaries in Python3) and this object has the following attributes:<\/p>\n
\nname: Initial Setup<\/code> which sets the name of our playbook as Initial Setup<\/em><\/li>\nhosts: all<\/code> selects which hosts from our inventory file will this playbook act upon. We have decided to act on all the hosts inside the inventory.<\/li>\nremote_user: root<\/code> sets what user do we wish to SSH as into the remote host.<\/li>\n<\/ul>\nThe next item in this Object will be tasks<\/code> and herein will lie the bulk of our "configurations". I will show the tasks below as part of the larger playbook, because it is important to note that the indentation level on tasks<\/code> should be same as name<\/code>. However, tasks<\/code> itself has a list of, well, tasks<\/em> within it. Each task<\/em> is another object. an indentation level below tasks<\/code> and name<\/code>. And each task comes with a name and a module along with the action that the module is supposed to take.<\/p>\n---\n- name: Initial Setup\n hosts: all\n remote_user: root\n tasks:\n - name: Add SSH key for root\n lineinfile:\n path: ~\/.ssh\/authorized_keys\n create: yes\n state: present\n line: <COPY YOUR PUBLIC SSH KEY HERE><\/code><\/pre>\nSo the first task<\/em> here is named "Add SSH key for root" and it uses an Ansible module lineinfile<\/code> which makes sure that a specific line is present (or absent) in a given file. Here, the lineinfile<\/code> module also contains a dictionary of following parameters within it.<\/p>\n\npath: ~\/.ssh\/authorized_keys<\/code> specifies which file this particular task is concerned with.<\/li>\ncreate: yes<\/code> says that, if the file is absent, create it!<\/li>\nstate: present<\/code> specifics that we want a given line to be present.<\/li>\nline: <COPY YOUR SPECIFIC SSH KEY HERE><\/code> specifics what line we want there to be.<\/li>\n<\/ul>\nDifferent modules will have different parameters. For example, package<\/code> module will not have a path<\/code> or line<\/code> variables because the installation of a package has nothing to do with path or lines.<\/p>\nObviously, no one can remember how each module works and what parameters it takes. So, when you are writing your playbooks, the ansible documentation<\/a> will be your best guide. For example, the lineinfile<\/code> module has all its various parameters described, along with the default values, and examples, here<\/a>. The documentation is clean, easy to follow, and full of relevant examples.<\/p>\nYou can see in the docs that state: present<\/code> is already the default value. So you can skip that line from your playbook if you just want to ensure that the given line exists in the file.<\/p>\nAnsible's automation system has hundreds of built-in modules, and you can also access many more community provided modules from ansible-galaxy<\/a>. <\/p>\nRunning the playbook<\/h2>\n
To run the above playbook, switch to the directory where the playbook lives and use the ansible-playbook<\/code> command:<\/p>\n$ cd playbooks\/\n$ ansible-playbook initial-setup.yaml<\/code><\/pre>\nIf you have not set your SSH keys, and are going to login using password, install sshpass<\/code> on your local machine and use ansible-playbook<\/code> with the flag --ask-pass<\/code> to allow ansible to login using plain text password:<\/p>\n$ sudo apt install sshpass\n$ ansible-playbook --ask-pass initial-setup.yaml<\/code><\/pre>\nEnter the password for your VPS when prompted.<\/p>\n
The above command will be required only for the first time, since we are adding SSH keys as part of our server configuration.<\/p>\n
Idempotent<\/h2>\n
Why not write a bash script to automate something like that? Well, bash scripts don't have the same reliability as Ansible. If there is a bug in your bash script, even if it is the most minor of bugs, it can potentially clobber your VPS and can lock you out of it, or corrupt its data.<\/p>\n
Where as with Ansible it is much harder to unintentionally clobber the system. For example, if you run the above playbook again, it won't add the same SSH key twice to your authorized_keys<\/code> file. But if you just do a cat keyfile.pub >> authorized_keys<\/code> in bash, it will keep adding the line again and again each time you run the script. With more complicated setups a home made bash script won't be able check for errors, edge cases, or stay idempotent. Idempotent operations are those that can occur on a system one or more times and not change the system. It is only the first run that would matter.<\/p>\nSo if your inventory grows, or if you add a new task to your playbook, you can simply rerun the playbook, and not worry about the pre-existing tasks, or hosts being affected.<\/p>\n
Adding more stuff to our playbook and using Conditionals<\/h2>\n