DEV Community: Alexandre Couedelo

How to stay informed about recent trends in tech?

Alexandre Couedelo — Tue, 12 Jul 2022 14:03:37 +0000

Use knowledge to your advantage.

Continue reading on Geek Culture »

How to create Ansible Inventory with Terraform?

Alexandre Couedelo — Thu, 26 May 2022 10:43:44 +0000

Terraform is the go tool to provision your infrastructure and all the VM you need to run your applications.

Continue reading on FAUN Publication »

How to Create SSH keys with Terraform?

Alexandre Couedelo — Tue, 17 May 2022 08:07:20 +0000

Terraform allows you to set up servers in the cloud without much hassle. To access those servers with your CI/CD tools, however, requires…

Continue reading on FAUN Publication »

How to Configure GitHub Environments with Terraform?

Alexandre Couedelo — Wed, 04 May 2022 20:49:10 +0000

Did you know that GitHub Actions supports the definition of environments?

Continue reading on FAUN Publication »

What is Terraform Cloud and why you might need it?

Alexandre Couedelo — Sat, 12 Mar 2022 18:15:28 +0000

Terraform Cloud is the managed solution offered by Hashicorp to run Terraform configurations 💡. It is in some manner a “CI/CD tool” to manage Infrastructure as Code (IaC). It eliminates the need for you to configure a dedicated task in your CI/CD (Jenkins, Bamboo, Circle CI, etc.) and also provided a tailor-made UI, remote state management, and private module registry.

While it is always possible to use terraform as a CLI in any CI/CD this always comes with frustration when it comes to creating the perfect workflow to plan and apply changes to your infrastructure. If you work a lot with those tools Terraform and Ansible you will realize that dedicated tools add a lot of value.

Terraform Cloud is I deal if you are working on your personal project as it is Free. I also like to use it as it offers a central UI for all your project and a state-management. Otherwise, you have to create a resource with your cloud provider to manage your state S3 for AWS, Cloud Storage for GCP, Blob Storage for Azure. I believe you won’t find the same effortless management of Terraform scripts with another provider so Terraform Cloud is the best place to get started with Terraform.

In this article, I will give you a tour of Terraform Cloud and the necessary explanations to get started. This piece is part of a series I created on How to create infrastructure for a small self-hosted project. You can find all the code here: https://github.com/xNok/infra-bootstrap-tools, but this article does not how much prior requirements if it is not being a little bit familiar with Terraform.

Register on Terraform Cloud.

Simple task! Just go to https://cloud.hashicorp.com/products/terraform and click on Try cloud for free , complete the form, validate your email and let's meet at the next step.

Create a Workspace in Terraform Cloud.

Once you registered it is time to create your first workspace. Terraform workspace is a feature design to manage environments (aka. different setup using the same underlying terraform logic). For instance, you could have a workspace dev and a workspace prod. However, you can use workspaces how you’d like. Here is how to create a workspace.

Here are the steps:

Click on create a new workspace
Name your workspace (choose a naming convention to keep things in order)
(Optional) define the Terraform working directory this is the folder holding the main.tf you wish to execute.
Create the workspace

Terraform Cloud free remote backend option is a game changer. You can configure as follow:

terraform {
  backend "remote" {
    hostname = "app.terraform.io"
    organization = "nokwebspace"

    workspaces {
      name = "infra-bootstrap-tools-digitalocean"
    }
  }
}

It is considered best practice to place the remote backend configuration in a file called backend.tf

Now you need to log in to your Terraform cloud using an API key. First, run the command and follow the instruction from the prompt.

terraform login

Then create an API key using the UI. The small GIF below will show you how.

Create a small example

I was working on DigitalOcean for my https://github.com/xNok/infra-bootstrap-tools tutorials, so this example uses digital Ocean Terraform provider, but do not worry nothing fancy at all simple create a “project” (some kinda folder for resources).

Like in any terraform project after creating the [backend.tf](http://backend.tf) I create a [versions.tf](http://versions.tf) to configure my provider

versions.tf

Simple this configuration comes straight from the provider documentation: 💪

terraform {
  required_providers {
    digitalocean = {
      source = "digitalocean/digitalocean"
      version = "2.17.1"
    }
  }
}

provider "digitalocean" {
  # Configuration options
  # will use DIGITALOCEAN_ACCESS_TOKEN env variable
}

[backend.tf](http://backend.tf) done ☑️, [versions.tf](http://versions.tf) done ✅, next main.tf

main.tf

Now you are going to start writing some terraform code. Nothing difficult and this cost nothing, just a test.

/**
 * # DigitalOcean Project
 *
 * Projects let you organize your DigitalOcean resources 
 * (like Droplets, Spaces, and load balancers) into groups.
 */
resource "digitalocean_project" "infra-bootstrap-tools" {
  name        = "infra-bootstrap-tools"
  description = "Startup infra for small self-hosted project"
  purpose     = "IoT"
  environment = "Development"
}

Validating the Script locally

terraform plan

Note when running this script locally you will need to set DIGITALOCEAN_ACCESS_TOKEN with your DigitalOcean API key

Provisioning the infra with Terraform Cloud

This is where the show starts 🎇. The last setup required is to set DIGITALOCEAN_ACCESS_TOKEN in terraform cloud. Terraform Cloud recently added the notion of variable set that I found amazing to manage account API credentials. With a variable set, I can define all my DigitalOcean related variable (API key, organization name, admin email, etc.)

Variable Set

Once you have set your credentials simply commit and push your code to GitHub. If you go back to workspaces you see the status updated to planned.

Next, inspect your workspace, look at the UI. You will notice that each resource gets a separate view to give you the time to carefully inspect your plan.

Your review is done you can go ahead and hit confirm and Push .

There you go new resource created with Terraform Cloud.

Terraform apply completed

What you should do next?

Explore the added feature of Terraform Cloud

Done working for the day on your project? Launch a destroy plan.

Add notifications to your Slack Channels

Complex workflow with Run Triggers

Run plan on pull-requests

Conclusion

The Free offering of Terraform Cloud offers all you need for an open-source project (remote state and plan/apply workflow) so I don’t see any reason not to take advantage of this opportunity 😇.

For corporate usage is a very good product made by the creators of Terraform. If don’t have anything better already then just hop on.

I will use Terraform Cloud in my personal projects. I am building this repository https://github.com/xNok/infra-bootstrap-tools to demonstrate how to build a minimal (but scalable) infrastructure for a simple self-hosted application. I am sharing the setup I have been using for over many years and writing articles about all the DevOps-related knowledge. So have a look and follow along 🤟.

Experiment with Vagrant and Ansible - Docker Swarm for Small Self-hosted Projects

Alexandre Couedelo — Thu, 24 Feb 2022 20:44:36 +0000

Experimenting with Docker Swarm and having only a single node is a bit sad 😞. Luckily in my previous tutorial, you learn how to create *A Disposable Local Test Environment using Vagrant and Ansible.* If you followed along you know a little bit more about Vagrant and Ansible *but nothing worth showing off* 🤯*,* so let up our game and create a multi-VM Docker Swarm cluster.

This involves using Vagrant to create multiple VM, then using Ansible to install docker on each machine, before creating a Docker Swarm cluster with all our nodes. On this is in place you have a solid foundation to experiment with Docker

I want to remind you that the goal of this tutorial series is to document what I consider the bare minimum for a small self-hosted side project. I invite you to visit my repository for more information: https://github.com/xNok/infra-bootstrap-tools. At this point, we are doing the groundwork of setting up a server to host the application we will deploy later as docker containers.

Provisioning Multiple VMs with Vagrant

Like in the previous tutorial we use Vagrant to create virtual machines. The difference is that this time we are provisioning 3 VMs so the file became sensibly bigger. I will explain the content of this file in the next section.

Here is the new updated Vagrantfile . Before running vagrant up there are two more things you need to set up: ansible.cfg and inventory The code will be below this big Vagrantfile .

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|
  # Every Vagrant development environment requires a box. You can search for
  # boxes at https://vagrantcloud.com/search.
  config.vm.box = "generic/ubuntu2004"

  # We are moving to a more complex example so to avoid issues we will limit the RAM of each VM
  config.vm.provider "virtualbox" do |v|
    v.memory       = 1024
    v.cpus         = 1
    v.linked_clone = true
  end

  #########
  # Nodes: host our apps 
  #########

  config.vm.define "node1" do |node|
    node.vm.network "private_network", ip: "172.17.177.21"
  end

  config.vm.define "node2" do |node|
    node.vm.network "private_network", ip: "172.17.177.22"
  end

  #########
  # Controller: host our tools
  #########
  config.vm.define 'controller' do |machine|

    # The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine
    machine.vm.synced_folder ".", "/vagrant",
       owner: "vagrant", group: "vagrant", mount_options: ["dmode=755,fmode=600"]

    # /!\ This is only usefull because the tutorial files are under .articles/xyz
    # otherwise Ansible would get the roles from the root folder
    machine.vm.synced_folder "../../roles", "/vagrant/roles",
      owner: "vagrant", group: "vagrant", mount_options: ["dmode=755,fmode=600"]

    machine.vm.network "private_network", ip: "172.17.177.11"

    machine.vm.provision "ansible_local" do |ansible|
      # ansible setup
      ansible.install         = true
      ansible.install_mode    = "pip_args_only"
      ansible.playbook        = "playbook.yml"
      # ansible.version = "2.10.7"
      ansible.pip_install_cmd = "sudo apt-get install -y python3-pip python-is-python3 haveged && sudo ln -s -f /usr/bin/pip3 /usr/bin/pip"
      ansible.pip_args        = "ansible==2.10.7"
      # provsionning
      ansible.playbook        = "playbook.yml"
      ansible.verbose         = true
      ansible.limit           = "all" # or only "nodes" group, etc.
      ansible.inventory_path  = "inventory"
    end
  end
end

So the two last things you need 😅. Create an ansible.cfg file, we are fine-tuning ansible configuration to work with our setup. You won’t have an interactive shell so we won’t be able to accept SSH fingerprints. This configuration will also be essential to have ansible your working in your CI/CD since we are facing the same constraint.

[defaults]
host_key_checking = no

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes

Last we need to manually define the inventory file. Since we selected the IPs in the private network this is a simple task. Not that we also take advantage of our synced_folder to obtain the SSH keys required for ansible to connect to node1 and node2 .

node1      ansible_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key
node2      ansible_host=172.17.177.22 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node2/virtualbox/private_key
controller ansible_host=172.17.177.11 ansible_connection=local

[nodes]
node[1:2]

[managers]
controller

Now you can provision the infra with Vagrant

Vagrant up

Focus on the Vagrantfile

First, we select the Vagrant box we use as a base. This time I use ubuntu instead (generic/ubuntu2004 ) I found it easier for installing the latest version of Ansible on the controller. Notice that I added virtualbox specific configurations. Since you are running multiples VMs it is important to control the size of each VM as to not starve your PC resources. Also, I used the linked_clone option to speed up the process, that way VirtualBox will create a base VM (that will stay turned off) and clone this VM to create the other three.

  # Every Vagrant development environment requires a box. You can search for
  # boxes at https://vagrantcloud.com/search.
  config.vm.box = "generic/ubuntu2004"

  # We are moving to a more complex example so to avoid issues we will limit the RAM of each VM
  config.vm.provider "virtualbox" do |v|
    v.memory       = 1024
    v.cpus         = 1
    v.linked_clone = true
  end

Next, we have the two worker node definition. This step is straightforward. What is new here is that we set fix IPs to our VM, this makes it easier to create a static Ansible inventory.

  #########
  # Nodes: host our apps 
  #########

  config.vm.define "node1" do |node|
    node.vm.network "private_network", ip: "172.17.177.21"
  end

  config.vm.define "node2" do |node|
    node.vm.network "private_network", ip: "172.17.177.22"
  end

Before starting with the controller I want you to look at the Vagrant documentation and notice that there is two Ansible provider ansible and ansible_local . I used the second one so I don't have to bother installing ansible and I find that this approach is closer to the CI/CD approach you will use later in the series. As a result, to create two nodes we will provision three machines one of which is the controller and has the responsibility of running ansible and provisioning the other machines.

First, we create two synced_folder to give the VM access to our playbook and roles. That way we can update any Ansible code and use it immediately in the VM. Note that to avoid permission issues I forced the uid and guid as well as restricting files read/write access to the user only. The reason is that Ansible uses SSH keys stored in this folder (see inventory file) and permission for those keys needs to be that way.

  #########
  # Controller: host our tools
  #########
  config.vm.define 'controller' do |machine|

    # The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine
    machine.vm.synced_folder ".", "/vagrant",
       owner: "vagrant", group: "vagrant", mount_options: ["dmode=755,fmode=600"]

    # /!\ This is only usefull because the tutorial files are under .articles/xyz
    # otherwise Ansible would get the roles from the root folder
    machine.vm.synced_folder "../../roles", "/vagrant/roles",
      owner: "vagrant", group: "vagrant", mount_options: ["dmode=755,fmode=600"]

    machine.vm.network "private_network", ip: "172.17.177.11"

    machine.vm.provision "ansible_local" do |ansible|
      # ansible setup
      ansible.install         = true
      ansible.install_mode    = "pip_args_only"
      ansible.playbook        = "playbook.yml"
      # ansible.version = "2.10.7"
      ansible.pip_install_cmd = "sudo apt-get install -y python3-pip python-is-python3 haveged && sudo ln -s -f /usr/bin/pip3 /usr/bin/pip"
      ansible.pip_args        = "ansible==2.10.7"
      # provsionning
      ansible.playbook        = "playbook.yml"
      ansible.verbose         = true
      ansible.limit           = "all" # or only "nodes" group, etc.
      ansible.inventory_path  = "inventory"
    end
  end

The more complicated part comes in the provision section. I want to use the latest 2.x version of ansible to use the latest version of docker_swarm and docker_swarm_info modules. The issue is that ansible made a lot of structural changes between 2.7 and 2.10. So a little bit of hacking is required to install the desired version. I found this method on Github and it works like a charm.

Setting up Docker with Ansible

Our playbook is about to become a little bit more complicated on top of that installing docker is something you may want to reuse in several projects. I will assume you are somewhat familiar with Ansible and took the time to play a little bit with the hello-world playbook you used in the first tutorial.

There are multiple ways to create roles with ansibles but I want to keep is as simple as possible. But you should know that the recommended way to create roles is to use ansible-galaxy init . See the documentation here. The downside of this approach is that it creates a folder and files you may not use. Let’s keep things simple and create the minimal structure.

Ansible looks for a folder called roles and then a subfolder with the name of that role here docker , finally, the first thing Ansible does is to read the main.yml from the meta folder of that role to get collect metadata information about it.

mkdir -p roles/docker/meta
touch roles/docker/meta/main.yml

The meta/main.yml only requires you to specify dependencies for this role, meaning other roles that you would expect to execute before this one.

dependencies: []
  # List your role dependencies here, one per line. Be sure to remove the '[]' above,
  # if you add dependencies to this list.

Finally, we need to defines so tasks to complete the docker installation. It is a good practice exercise to look at the official docker installation documentation and turn it into an Ansible role: https://docs.docker.com/install/linux/docker-ce/debian/. Create the file /tasks/main.yaml

mkdir -p roles/docker/tasks
touch roles/docker/tasks/main.yml

Then the content of main.yml should look along those lines:

#################################################
# OR INFRA Role: Docker
# Source: https://docs.docker.com/install/linux/docker-ce/debian/
#################################################
---
###
# GENERAL Setup
###
- name: Install required system packages
  apt: name={{ item }} state=latest update_cache=yes
  loop: [ 'apt-transport-https', 'ca-certificates', 'software-properties-common']

- name: Add Docker GPG apt Key
  apt_key:
    url: https://download.docker.com/linux/debian/gpg
    state: present

- name: Add Docker Repository
  apt_repository:
    repo: deb [arch=amd64] https://download.docker.com/linux/{{ansible_distribution | lower }} {{ansible_distribution_release}} stable
    state: present

- name: Update apt and install docker-ce
  apt: name={{ item }} state=latest update_cache=yes
  loop: ['docker-ce', 'docker-ce-cli', 'docker-compose', 'containerd.io']

- name: Ensure docker users are added to the docker group.
  user:
    name: "{{ item }}"
    groups: docker
    append: true
  with_items: [vagrant, ubuntu]

- name: Start docker
  service:
    name: docker
    state: started
    enabled: yes

########
# Testing Setup
# Pull, start, stop a hello-world container
########
- name: Pull default Docker image for testing
  docker_image:
    name: "hello-world"
    source: pull

- name: Create default containers
  docker_container:
    name: "hello-world"
    image: "hello-world"
    state: present

- name: Stop a container
  docker_container:
    name: "hello-world"
    state: stopped

Update your playbook.yml file to specify that we want to use this role against all our VMs.

- name: This is a hello-world example
  hosts: all

  roles:
  - docker

  tasks:
    - name: Create a file called '/tmp/testfile.txt' with the content 'hello world'.
      copy:
        content: hello-world
        dest: /tmp/testfile.txt

Now it is time to run Vagrant

vagrant up

Once the provisioning is completed you should have three VMs with docker setup.

Setting up Docker Swarm with Ansible

To complete our setup we will need to create three more roles:

docker-swarm-controller will install the required python package on the host running Ansible to controller and manager the swarm. This includes notably the python docker package.
docker-swarm-manager will initialize the swam and join all the targeted nodes as manager
docker-swarm-node will join all the targeted nodes as workers nodes.

Here is the final Ansible playbook:

- name: This is the base requirement for all nodes
  hosts: all

  roles:
  - {name: docker, become: yes}

- name: This setup the Docker Swarm Manager
  hosts: managers

  roles:
  - {name: docker-swarm-controller, become: yes} # this role is for the host running Ansible to manager the swarm
  - {name: docker-swarm-manager, become: yes}    # this role is for creating the swarm and adding host as manager

- name: This setup nodes and join the swarm
  hosts: nodes

  roles:
  - docker-swarm-node # this role is for the host to join the swarm

`docker-swarm-controller`

This role is straightforward I don’t think I need to comment on it.

#################################################
# OR INFRA Role: Docker Swarm Controller
# Machines running ansible need some special python package
# Source: 
#    https://github.com/arillso/ansible.traefik
#    https://geek-cookbook.funkypenguin.co.nz/ha-docker-swarm/traefik/
#################################################
---
###
# GENERAL Setup
###
- name: Install required system packages
  apt: name={{ item }} state=latest update_cache=yes
  loop: ['python3-pip', 'virtualenv', 'python3-setuptools']

- name: Install python stuff required
  pip:
      executable: pip3
      name: [jsondiff, passlib, docker]

`docker-swarm-manager`

You need to be careful here you can only init a docker swarm once. As a convention, the first node of the group managers will be used as the founder of the swarm. Notice that this role uses a variable swarm_managers_inventory_group_name . I like my variables to be verbose 😂. We need to read facts about our nodes, this variable tells us what group in the inventory is used for managers

You may be wondering what hostvars[groups[swarm_managers_inventory_group_name][0]].result.swarm_facts.JoinTokens.Manager do? When Ansible executed Init a new swarm with default parameters we asked Ansible to register some information with register: result this is simply the path to collect the information about the join token that the other nodes need to join the swarm as a manager. Get join-token for manager nodes effectively persisted the join token on each of the managers as a fact. More about Ansible facts and Variables here.

#################################################
# OR INFRA Role: Docker Swarm Manager
# Source: 
#    https://github.com/arillso/ansible.traefik
#    https://geek-cookbook.funkypenguin.co.nz/ha-docker-swarm/traefik/
#################################################
---
###
# GENERAL Setup
###

###
# SWARM Setup
###
- name: Init a new swarm with default parameters
  docker_swarm:
    state: present
    advertise_addr: "{{ ansible_host }}"
  register: result
  when: inventory_hostname == groups[swarm_managers_inventory_group_name][0] # only on the first manager

###
# Manager Setup
###
- name: Get join-token for manager nodes
  set_fact:
    join_token_manager: "{{ hostvars[groups[swarm_managers_inventory_group_name][0]].result.swarm_facts.JoinTokens.Manager }}"

- name: Join other managers
  docker_swarm:
    state: join
    join_token: "{{ join_token_manager }}"
    advertise_addr: "{{ ansible_host }}"
    remote_addrs: "{{ groups[swarm_managers_inventory_group_name] | map('extract', hostvars, ['ansible_host']) | join(',') }}"
  when: inventory_hostname != groups[swarm_managers_inventory_group_name] # exclude the first manager

`docker-swarm-node`

This role is very similar to the previous one except that this time we get the join worker token and register our node as workers.

#################################################
# OR INFRA Role: Docker Swarm Node
# Source: 
#    https://github.com/arillso/ansible.traefik
#    https://geek-cookbook.funkypenguin.co.nz/ha-docker-swarm/traefik/
#################################################
---
###
# GENERAL Setup
###
- name: Get join-token for worker nodes
  set_fact:
    join_token_worker: "{{ hostvars[groups[swarm_managers_inventory_group_name][0]].result.swarm_facts.JoinTokens.Worker }}"

###
# Add Nodes
###
- name: Add nodes
  docker_swarm:
    state: join
    advertise_addr: "{{ ansible_host }}"
    join_token: "{{ join_token_worker }}"
    remote_addrs: "{{ groups[swarm_managers_inventory_group_name] | map('extract', hostvars, ['ansible_host']) | join(',') }}"

Testing that the Docker Swarm is working

Let’s see if everything looks ok in our cluster. SSH to the controller node:

vagrant ssh controller

Use the command docker node ls to see your cluster

vagrant@ubuntu2004:~$ docker node ls
ID                            HOSTNAME                 STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
odumha179h5qbtln5jfoql9xc *   ubuntu2004.localdomain   Ready     Active         Leader           20.10.12
opeigd4zdccyzam3yjaakdfzk     ubuntu2004.localdomain   Ready     Active                          20.10.12
yjy282nbmzcr5gx90rvvacla2     ubuntu2004.localdomain   Ready     Active                          20.10.12

Conclusion

Quickly setting up VMs and creating Ansible roles is the fastest way for me to test a simple setup at no cost. This is why Vagrant and Ansible make such a great team to create a Disposable Local Test Environment.

As of now, your Docker Swarm is totally empty. In future tutorials let's create a simple stack you can reuse for almost all your projects. You can check my Github repository https://github.com/xNok/infra-bootstrap-tools to find more tutorials and build the following infrastructure.

Resolving common problems

Sometimes when provisioning multiple machine issues occur. You should not restart everything from ground zero but use the power of Ansible and Vagrant to resume operation from where the problem occurred.

When the provisioning fails (ansible error) you can restart the provisioning with:

vagrant provision controller

It happened to me that an error occurred to a node (SSH errors or node unreachable) in that case reload only the node that creates problems.

vagrant reload node1

References

https://github.com/geerlingguy/ansible-role-docker

https://github.com/ruanbekker/ansible-docker-swarm

https://github.com/atosatto/ansible-dockerswarm

Docker_swarm module - join_token parameter for ansible not working

A Disposable Local Test Environment is Essential for DevOps / SysAdmin

Alexandre Couedelo — Tue, 15 Feb 2022 22:26:19 +0000

Working on your infrastructure setups and testing your automation script can be tedious if you don’t have a proper test environment that enables a fast iteration loop. The best when automating your server provisioning with Ansible scripts is to be able to set up servers a local server step by step then play all the steps from the ground up and make sure everything goes as planned. Once the local and iterative design phase is complete you will be ready to create an automated pipeline to set up an actual production environment.

Why Ansible you may ask? Ansible is simple and easy to learn if you have some Linux administration knowledge. We are configuring a Linux server after all you can’t escape that part.

With a small project spread across several articles, I want to show you what I consider the minimum requirement for a small self-hosted project. I invite you to check my Github repository for other articles and more details about the whole project.

In this article, you will see how to get started and set up a local testing environment. You will learn about Vagrant a tool to create local virtual machines on the fly.

Getting Started with Vagrant

First, install Vagrant. Simply go to the main page and download the product for your platform. Once Vagrant is installed you can need a hypervisor, the most popular is VirtualBox because it can run on Linux, Windows, and Mac OS. With both requirements installed (Vagrant + VirtualBox) you can get started spawning a Linux Debian ****virtual machine and start experimenting.

To create a VM, you need to understand the Concept of a Vagrant Box. Put simply Boxes is the way Vagrant packages environments so they can be shared via a registry such as Vagrant Cloud. Let’s search for a Debian box that fit your need. This one should do the job: generic/debian10

Two steps to getting your box running:

vagrant init generic/debian10
vagrant up

The first command created a file called Vagrantfile that describes how to provision your environment. The file created with the init command simply specifies that we want to use the Vagrant box generic/debian10 as a base.

Vagrant.configure("2") do |config|
  # Every Vagrant development environment requires a box. You can search for
  # boxes at https://vagrantcloud.com/search.
  config.vm.box = "generic/debian10"
end

The second command vagrant up starts and provision the VM. Once your box is running you can SSH into and play with it.

vagrant ssh

At that point, you could start making procedures about how to install everything you need. But this approach would no be to be maintainable and reproducible. This is why you need to also learn about Vagrant provisioners.

Vagrant and Ansible

Ansible is a simple automation tool that can orchestrate pretty much any task you would need to configure and maintain your infrastructure. Ansible work best when you are dealing with actual machines (servers or virtual machines), I would not recommend using it to provision Cloud infrastructure as it lacks a state management capabilities you can find in other tools such as Terraform. But here we will be dealing with configuring Linux servers so ansible works best here.

In order to make the bridge between Vagrant and Ansible, you will use the Ansible *Provisioners.* Provisioners are tools that vagrant will use to set up your virtual machine and Vagrant support the most command tools on the market and offers the ability to create your own provisioner to meet your needs. But let’s focus on the Ansible Local Provisioner, that way you don’t even have to worry about installing Ansible on your local machine Vagrant will install it inside your virtual machine.

Vagrant.configure("2") do |config|
  # Every Vagrant development environment requires a box. You can search for
  # boxes at https://vagrantcloud.com/search.
  config.vm.box = "generic/debian10"

    # The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine
  config.vm.synced_folder ".", "/vagrant"

  config.vm.provision "ansible_local" do |ansible|
    ansible.playbook = "playbook.yml"
  end
end

Vagrant makes it easy for you to run your ansible provisioning scripts against the virtual machine it created for you. You should see a folder .vagrant at the root of your project (this folder should be ignored by git, if not add it to your .gitignore).

Next you need to create an “hello-world” playbook called playbook.yaml:

- name: This is a hello-world example
  hosts: all
  tasks:
    - name: Create a file called '/tmp/testfile.txt' with the content 'hello world'.
      copy:
        content: hello-world
        dest: /tmp/testfilprovisioning

You are ready to try out your first ansible provisioning with Vagrant

$ Vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Checking if box 'generic/debian10' version '3.6.8' is up to date...
==> default: Clearing any previously set forwarded ports...
==> default: Fixed port collision for 22 => 2222. Now on port 2200.
==> default: Clearing any previously set network interfaces...
==> default: Preparing network interfaces based on configuration...
    default: Adapter 1: nat
==> default: Forwarding ports...
    default: 22 (guest) => 2200 (host) (adapter 1)
==> default: Running 'pre-boot' VM customizations...
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address: 127.0.0.1:2200
    default: SSH username: vagrant
    default: SSH auth method: private key
==> default: Machine booted and ready!
==> default: Checking for guest additions in VM...
==> default: Mounting shared folders...
    default: /vagrant => E:/Nokwebspace/infra-bootstrap-tools
==> default: Running provisioner: ansible_local...
    default: Installing Ansible...
    default: Running ansible-playbook...

PLAY [This is a hello-world example] *******************************************

TASK [Gathering Facts] *********************************************************
ok: [default]

TASK [Create a file called '/tmp/testfile.txt' with the content 'hello world'.] ***
changed: [default]

PLAY RECAP *********************************************************************
default                    : ok=2    changed=1    unreachable=0    failed=0

If you make changes to the playbook you can simply run only the provisioning stage

vagrant provision

Once you are done or want to take a break simply stop the VM.

vagrant halt

Conclusion

You are ready to start working on your next infrastructure provisioning project. Having a disposable test environment is essential and Vagrant will soon become your favorite tool.

You can check my Github repository https://github.com/xNok/infra-bootstrap-tools to find more tutorials and build the following infrastructure.

How to Build a Custom Split Mechanical Keyboard: Bill of material

Alexandre Couedelo — Mon, 31 Jan 2022 05:01:09 +0000

One Step further In the world of Open-Source Ergo Split Keyboards

Continue reading on Medium »

Multi-Cloud is NOT the solution to the next AWS outage.

Alexandre Couedelo — Mon, 03 Jan 2022 12:04:49 +0000

There are many things you can do first in terms of disaster recovery.

Continue reading on FAUN Publication »

A Split Mechanical Keyboard, You Can Build Yourself!

Alexandre Couedelo — Thu, 23 Dec 2021 17:06:21 +0000

A Split Mechanical Keyboard, You Can Build Yourself! 🎅

In the world of Open-Source Ergo Split Keyboards

Ferris split keyboard courtesy of Pierre Viseu Chevalier

Since I started working from home, I have been obsessed with creating the most ergonomic workplace for myself. Standing desks, ergonomic stools, etc.

But up until now, nothing I could reasonably build myself. 😢

But a month ago, everything changed. I read about the benefit of split keyboards. A Keyboard cut halfway through in the middle prevents your wrists from tilting inward and relaxing your arms and shoulders.

I discovered a massive community of passionate makers: r/ErgoMechKeyboards , many videos ,and Github repositories with exciting designs to copy and do yourself. ✨

In this Story, I have summarized all the knowledge I have gathered so far and will walk you through creating your Keyboard.

What skills do you need to create one of these beauties?

Quite a lot, actually! It should range from electronic to 3D modeling to soldering and buying stuff. On top of that, it is not an expensive project; it should range from $50 to $150. But if you are passionate or curious about engineering in general, it is an excellent first project as it is accessible by anyone.

The main activities are:

Designing and Printing a PCB (Printed Circuit Board)
Buying and Assembling the electronic components
Designing and manufacturing the casing to protect the electronic and look event cooler 😎.

I) Designing and Printing a PCB

This is what a PCB looks like.

Ferries Sweep PCB courtesy of Pierre Viseu Chevalier, David Barr, Ibnu Daru Aji, Duccio

To create a keyboard, you essentially have two options:

1) You create a case and mechanically attach the key switches to the case and solder cables between the switches.
2) Print a PCB and solder the keys and other components.

There are several advantages to the second approach. First soldering is much easier; you just have to solder key switches in the sockets created on the board. The board itself is strong enough to hold the keys and make the Keyboard usable without a case. As a result, you can create an ultra-light keyboard and save you some effort in the process of making it for a few $.

I.1) Choosing the layout

The first step is choosing how your Keyboard will look like. How many keys? The spacing between the keys, etc.

Compare existing split keyboard layouts here. As a first step, see what is available and print the layout to get a real feel of the Keyboard.

☑️ Screen and Print keybord layouts from: https://jhelvy.shinyapps.io/splitkbcompare/

Me printing the layout of a Corne

I'd like you to reflect on the fact that you are most likely only frequently using half of the keys on your Keyboard. A standard keyboard usually has just above 100 keys. You may have noticed that most of those keyboards rarely have more than 50 keys, and this is perfectly fine.

People using split Keyboard type the same way you type on your phone keyboard: At first, you only have the letters, then you press the "?123" symbol so you can type number and some of the symbols; then, if you want more symbols you type the "=<" key.

Ultimately you will program the layout of your Keyboard so you will be able to do whatever you want.

⚠️Not all layout on https://jhelvy.shinyapps.io/splitkbcompare/ are open source, so you won’t be able to get the file for printing the PCB

I.2) Designing the PCB

Once you have set yourself to mind a layout, you can customize it. Search on Google or on Github for the source to get started. Theoretically, you could just download the file and send it to the PCB manufacturing. But why tunning your chance to have a genuinely unique keyboard?

I learned the basics about how to customize a PCB from this video. I highly recommend watching it. But here is a quick summary of what you need.

☑️ You will need a software to edit the PCB such as KiCad: https://www.kicad.org

For the sake of this example, I downloaded the PCB Gerber File for Sweepv2.1.

Sweepv2.1 in KiCad Gerber Viewer

❗️️️️❗️ ️️️️️If you want to have a quike look to a Gerber file archive you can use this Online Gerber Viewer (I found it much clearer to understand the different layers)

PCB manufacturers literally use Gerber Files to print your order layer bay layer. See the different layers on the right side. In the archive, you open containers with one file per layer.

*.xln is the Drill layer, = Where to make holes.
*.gm1 the board Edges = how to cut the PCB to detached from the mainboard.
*B_Cu.gbl and *F_Cu.gtl are the front and back copper layer = where to print copper wire to create connectivity.
*B_Mask.gts and *F_Mask.gbs are the back and front solder masks = was to print the protective layer on top of the copper layer. This layer is ofter green and gives there distinctive color to the PCB. Luckily more colors are available 😉.
\ **B_Silk.gbo* and \ **F_Silk.gto* are the back and front silkscreen = the decorative prints on top of the solder masks, usually used to write references dor the component to solder.

Well, this is not entirely true. Once you understand each layer's use, nothing stops you from customizing a PCB to your heart content 👼. Before editing the board, you need to know what component you want to fit in, and this is the object of the next section 😈.

II) Choosing the components

II.1) Choosing the switches

The first thing you need to know is that there are essentially three types of mechanical switches.

Clicky switches are the noisy ones. The typical switches you associate with a mechanical keyboard give you this satisfying click sound at the end of a stroke.
Tactile switches are not as noisy but give you tactile feedback when you press the key.
Linear switches are more and more common and provide no feedback or noise as you type, design for a smooth and soothing typing experience.

Types of mechanical switches

Second the nuance you can find high vs. low profile. This choice is often associated with choosing Cherry MX VS. Kailh Chocolate.

❗️️️️ ❗️️️️ T️here is more brand of key switches I invite you to read more about it here. Most manufacturer provided both type of profile, but i notice that in Open-source built Kailh was choosen for their low profile key and Cherry MX for their high profile key.

High Profile vs. Low Profile courtesy of u/songcq

The choice should be influenced by the feeling you are looking for in your Keyboard and whether you want your Keyboard to be compact or not. For a compact Keyboard, you need to go for low-profile switches.

☑️ You will need to select you switches and the download the specs (datasheet). This Github repository contains datasheets for most manufacturer: https://github.com/keyboardio/keyswitch_documentation

You need to validate that the key switches you are selecting are compatible with your PCB. Otherwise, you will need to do some edits to make sure they properly fit.

Circuit Board Layout for Keith Choc Blue

II.2) Choosing the keycaps

The only thing that matters is selecting key switches that match the brand you choose (Cherry MX VS. Kailh Chocolate). Aside from that, just have fun and explore the many options available on the market.

Fun Keycaps for Mechanical Keyboard from Etsy

If you want to push this project a bit further, you can decide to print your own keycap.

☑️ You can screen for existing 3D model with online libraries like : https://www.yeggi.com/

Me searching for 3D Models on Yeggi

II.3) Choosing the micro-controller

The microcontroller est the brain for your keyboard. It converts keystrokes into understandable code used by your PC by implementing the Keyboard Protocol.

Luckily you won’t have to code to much thanks to the community and the Open-source keyboard firmware QMK. With QMK you only need to define the keymap using an online configurator, for instance, then flash the microcontroller.

The most popular options are:

Pro Micro most common microcontroller board, you are bringing Arduino’s power to your board.
Elite-C higher-end microcontroller, ideal if you plan to add features over time.
Nice!nano if you want to create a vluthouth keyboard

A microcontroller board might be the most expensive element of this build especially given that you need two of them so you could opt-in for onboard keyboards. The controller board I listed essentially relies on ATMEGA32U4. If you have the skills and knowledge you could consider going for SMT assembly and have your microcontroller solder on the board.

II.4) Extra designed feature you may want to consider

Socket for the microcontroller board. Let's say you want to convert the keyboard into a wireless keyboard later socket would allow you to

Socket for the microcontroller board

Hot-swappable key switches socket. This would allow you to change the key switches at will and prevent you from having to solder the key switches to the board

Kailh Hot-Swap Sockets courtesy of u/davenelsondotcom

RGB LEDs. Just to make things fancy

Corne Split Keyboard from crkbd

OLED Arduino module. So you can have on the keyboard display

OLED Arduino module

Tenting support. Tenting consist of adding some inclination to the keyboard so your wrists have a more natural position

Split keyboard with Tenting

I am sure the is a lot more feature we can add to a keyboard 😆.

☑️ Select your features, study the componenents, make adjustement to your PCB.

III) Designing the case

Last but not least the case, the protective and decorative envelope for your keyboard.

Some people like the look of the PCB and choose to simply have cut acrylic sheets. The process is simple and requires no machining so it is one of the best options. On top of that if you opted for the LED this would for sure look awesome.

Corne Technician Keyboard Case from littlekeyboards.com

The second option is to have a 3D-printed case. The best would be to start from an existing design and adapt it.

☑️ You can screen for existing 3D model with online libraries like : https://www.yeggi.com/

Where to get all the parts?

Once you have designed your keyboard you may be wondering: how do I get all the parts?

With your Gerber file you can get your PCB printed with:

For the components there is a bunch of dedicated stores online:

For the case and other 3D printed objects:

❗️️️️ ❗️️️️ Shipping fees seems to be the most expensive part of this build so try to find local manufacturer to reduce the costs.

Conclusion

I am about to order all the parts so I keep this section to share the build 😉.

Here is the follow-up article with the part I bought (about $40 per keyboard excluding shipping fees):

How to Build a Custom Split Mechanical Keyboard: Bill of material

References

Compare all split keyboard layouts: https://jhelvy.shinyapps.io/splitkbcompare/

More PCB editing tools: https://support.jlcpcb.com/article/22-how-to-generate-the-gerber-files

Opensource Keyboard — Corne lines

Opensource Keyboard — GergoPlex Line

https://www.youtube.com/watch?v=TpJQtzaThmM

Opensource Keyboard — Ferries Line

Opensource Keyboard— 3W6 Line

https://github.com/weteor/3W6

Opensource Keyboard — fifi line

https://github.com/raychengy/fifi_split_keeb

How to Evaluate the Maturity of DevOps Practices in your Company?

Alexandre Couedelo — Wed, 01 Dec 2021 18:58:59 +0000

Discover SMART Maturity Assessment Inspired by Lean Manufacturing

Continue reading on FAUN Publication »

Build a “Smarter” DevOps Roadmap - The SMART Maturity Assessment Method

Alexandre Couedelo — Tue, 23 Nov 2021 11:14:05 +0000

A tool that helps you build your DevOps Roadmap

Continue reading on Geek Culture »