Skip to content

Ansible & Semaphore

In this section Ansible and Semaphore technologies are introduced. Also, an example combining both platforms with the eManager will be presented.

Ansible

Ansible provides open-source automation that reduces complexity and runs everywhere. Using Ansible lets you automate virtually any task. It is known for its simplicity and flexibility, not only automates configuration management but also facilitates device monitoring.

Ansible is designed around the following principles:

  • Agent-less architecture: Low maintenance overhead by avoiding the installation of additional software across IT infrastructure.
  • Simplicity: Automation playbooks use straightforward YAML syntax for code that reads like documentation. Ansible is also decentralized, using SSH existing OS credentials to access to remote machines.
  • Scalability and flexibility: Easily and quickly scale the systems you automate through a modular design that supports a large range of operating systems, cloud platforms, and network devices.
  • Idempotence and predictability: When the system is in the state your playbook describes Ansible does not change anything, even if the playbook runs multiple times.

Semaphore

Semaphore is a continuous integration and delivery platform, offers seamless integration with monitoring tools, enabling users to incorporate monitoring into their development pipelines effortlessly.

Example of use with the eManager

This example is only a proof of concept to show how eManager can be integrated with these tools.

In this example we will:

  • manage two eManagers in our local WiFi Network
  • use Semaphore server running in PC via docker.
  • use asymmetric keys for user credentials.

Semaphore Dashboard

Note

The process detailed below has been tested with Debian 10 and Ubuntu 20.04.

eManagers settings

Here we generate a pair of asymmetric keys to simplify SSH login for the Semaphore server.

Security issues

Please, keep in mind that this process will make your PC gain free SSH access to all the eManagers. Also, make sure you don't share the content of ~/.ssh/semaphore_key to anyone.

  1. Connect the eManagers and the PC to the same WiFi network.
  2. Determine the WiFi IP of every eManager via 
    ip -c a show wlan0
    in each eManager terminal.
  3. Store all the IP addresses in a file for now. We'll use them all along this tutorial.
  4. We will use asymmetric keys in order to allow SSH access to the Semaphore server. Execute in your PC terminal 
    ssh-keygen -t ed25519 -N "" -f ~/.ssh/semaphore_key
    in order to generate aymmetric keys.
  5. Add this key to the list of authorized keys for each eManager. That is, for every eManager IP execute the following in your PC. Replace <eManager IP> by the corresponding IP address 
    IP=<eManager IP>
    then execute 
    SSH_COMMAND="exec sh -c 'cd; umask 077; mkdir -p ".ssh" && { [ -z `tail -1c .ssh/authorized_keys 2>/dev/null` ] || echo >> ".ssh/authorized_keys" || exit 1; } && cat >> ".ssh/authorized_keys" || exit 1;'"
PUB_KEY=$(cat ~/.ssh/semaphore_key.pub)
printf '%s\n' "${PUB_KEY}" | { ssh -a -x root@"${IP}" "${SSH_COMMAND}"; } || echo "Ups! Something went wrong."

Installing Semaphore and Ansible in your PC

  1. Install docker and Ansible in your laptop: 
    sudo apt update
sudo apt install docker-ce
sudo apt install ansible
  2. Let's create a new docker compose project. Create a new directory 
    mkdir semaphore_docker
  3. Create a docker-compose.yml file in semaphore_docker directory 
    cd semaphore_docker
nano docker-compose.yml
    with the following content: 
    services:
  mysql:
    restart: unless-stopped
    image: mysql:8.0
    hostname: mysql
    volumes:
      - semaphore-mysql:/var/lib/mysql
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: 'yes'
      MYSQL_DATABASE: semaphore
      MYSQL_USER: semaphore
      MYSQL_PASSWORD: semaphore
  semaphore:
    restart: unless-stopped
    ports:
      - 3000:3000
    image: semaphoreui/semaphore:v2.9.37
    volumes:
      - ./semaphore-example/:/data/demo-project
    environment:
      SEMAPHORE_DB_USER: semaphore
      SEMAPHORE_DB_PASS: semaphore
      SEMAPHORE_DB_HOST: mysql
      SEMAPHORE_DB_PORT: 3306
      SEMAPHORE_DB_DIALECT: mysql
      SEMAPHORE_DB: semaphore
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore/
      SEMAPHORE_ADMIN_PASSWORD: admin
      SEMAPHORE_ADMIN_NAME: admin
      SEMAPHORE_ADMIN_EMAIL: admin@localhost
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: gs72mPntFATGJs9qK0pQ0rKtfidlexiMjYCH9gWKhTU=
      ANSIBLE_HOST_KEY_CHECKING: False
    depends_on:
      - mysql
volumes:
  semaphore-mysql:
  4. Clone our git example: 
    git clone https://github.com/circutor-iot/semaphore-example
  5. Bring up the docker containers with 
    sudo docker compose up
  6. If everything went right the terminal should print 
    semaphore-1  |  You can login with admin@localhost or admin.
semaphore-1  | Run Semaphore with semaphore server --config /etc/semaphore/config.json
semaphore-1  | Loading config
semaphore-1  | Validating config
semaphore-1  | MySQL semaphore@mysql:3306 semaphore
semaphore-1  | Tmp Path (projects home) /tmp/semaphore
semaphore-1  | Semaphore v2.9.37
semaphore-1  | Interface 
semaphore-1  | Port :3000
semaphore-1  | Server is running
    Don't close this terminal until you are done with Semaphore.
  7. If the docker above is running, writing localhost:3000 in your browser should open your local Semaphore UI. Use credentials admin/admin. Then press SIGN IN.
  8. A Create New Project menu should appear. In this example we use eManagers example for the Project Name, and let the other fields empty. Then click CREATE. An empty project will appear.

semaphore empty project

Defining the Repository

Let's tell Semaphore where to find the ansible files. In our case we use the GitHub repo we cloned above. As a consequence, this Repository is just a local project.

Let's configure the Repository.

  1. Let's register a new empty key, this is an auxiliary key. Click Key Store and then click NEW KEY. Use None for the Key Name, choose None for type then press CREATE. semaphore None Key

  2. Let's configure the local Repository. Click Repositories and then click NEW REPOSITORY with the following fields 

    Name:        emanager-example
URL o path:  /data/demo-project
Branch:      -
Access key:  None

semaphore repository

Then press CREATE.

Note

The path /data/demo-project is mapped to semaphore-example in the docker-compose file.

Create an Environment

Let's create an empty environment. Click Environment and then click NEW ENVIRONMENT. Use Empty for the Environment Name and write {} in the Extra variables box. Then press SAVE.

Create an Inventory

In this section we tell Ansible Semaphore where to find the fleet of eManagers that should manage. This typically has two steps:

  • identify a list of IP corresponding to the eManagers.
  • choose the type of user credentials.

For the first step, edit in a new terminal the file semaphore_docker/semaphore-example/invs/devices/hosts. 

[devices]                                                                      
192.168.0.25 ansible_connection=ssh ansible_python_interpreter=/usr/bin/python3
192.168.0.38 ansible_connection=ssh ansible_python_interpreter=/usr/bin/python3
by adding/removing lines. Each line describes an eManager to be managed and its IP. Use the IPs obtained above.

For the second step, we will use the asymmetric keys created above.

  1. Execute 
    cat ~/.ssh/semaphore_key
    in the PC terminal. Copy the output to the clipboard.
  2. Open the Semaphore web. Click Key Store and then click NEW KEY. Fill the form as follows 
    Key Name:    SSH
Type:        SSH Key
Username:    root
Private Key: <PASTE the key copied in the last step>
    semaphore None Key
  3. Click Inventory and then click NEW INVENTORY. Fill the form as follows 
    Name:                   eManager fleet
User Credentials:       SSH
Sudo Credentials:       -
Type:                   file
Path to Inventory file: invs/devices/hosts
    semaphore inventory

Create a task

Our GitHub project contains three Playbooks,

  • install_wireguard.yml
  • ping_devices.yml
  • reboot.yml

Here we create a task that installs wireguard in our eManager fleet.

  1. In the Task Templates section, click NEW TEMPLATE.

  2. Choose the name you prefer, then must fullfill the different fields with the following information: 

    Name:               Install wireguard
Playbook Filename:  install_wireguard.yml
Inventory:          eManager fleet
Repository:         emanager-example
Environment:        Empty
    We let the other fields empty.

  3. Press CREATE.
  4. You can use same Inventory, Repository and Environment to create more tasks with the playbooks ping_devices.yml and reboot.yml

Run a task

Click the task you want to run from Task Templates. Then click RUN.

semaphore task