Activities Updates via Ansible

This document tries to summarise the features at device and cloud level and provides a "usage path" that should be the guidance for users on how to use the feature.

Activities vs Ansible

To clarify the terminology used, with "activities" we define the protocol used by the cloud and the device to manage updates with request that do not have immediate feedback.
Instead of the plain and commonly used request/response used by EC and ESF for the "common" interaction where to a request from the cloud there is a response from the device, the Activities model is designed to support updates and communication in harsh environments, for example, scenarios where the device is connected to the cloud using a cellular connection.
If the cellular signal is not perfect it can happen that requests and responses can be lost.

The activities model tries to prevent this issue by introducing a model based on request and notifications. If one of those messages is lost, the system can recover and continue to operate.

Ansible and in particular ANSIBLE-V1 is the first implementation of the activities model. Being so close, in the following part of the document, activities, Ansible and ANSIBLE-V1 are considered sinonyms.

ESF Features and implementation

The Ansible stack is installed by default in ESF 7 and can be installed using a deployment package in all the ESF 6.x versions.
The target system is required to have Ansible and python-systemd packages in order to allow a correct functioning of the ESF updates via Ansible playbooks.

On ESF side, the web ui shows 2 new services: Ansible Cloud Client and Ansible Service

Ansible Cloud Client

This service allows to connect the ANSIBLE-V1 stack with the proper cloud connection.
It defaults to the default ESF cloud connection.

The service exposes also the target download location for the playbooks. The default value is tmp that is volatile. The customer can customize this value and, for example, configure a persisted location or a different and wider partition.

Ansible Service

This service allows the customer to define parameters that will be used by the Ansible Executor.
Right now, the framework can track the Inventory file configuration. This configuration will be passed by ESF to Ansible when lauching the Ansible executable.

Default Activities Log Manager

In addition to those Ansible related services, the framework has a specific LogManager instance that is responsible to parse and push to the cloud Activities-related log messages fetched from the journal.

The default configuration of the LogManager pushes to the cloud all the journal entries related to activities jobs.

FileSystem activities folders

For its execution the ANSIBLE-V1 stack stores its persistence in two main folders in /var/lib.

The two folders are:

• eth-localexecution-area
• eth-persisted-activities

The eth-persisted-activities contains persistence of all the activities requests received, and is the main source of information for the ANSIBLE-V1 stack to know which activities were requested and to restore the history of them when the gateway is rebooted. This folder is also the reference used by the stack to reply to specific cloud requests to know the activities processed by the gateway.

The content of this folder is a set of properties files.

The eth-localexecution-area folder, as the name says, is the working area for the activity execution. Every activity request opened and tracked in the previous folder has here a folder where the activities processor keep track of the execution.

Each activity execution contains 3 files: a log file that contains the output of the executor run(s), required_executions and performed_executions that are two files used to track the execution status.

When the content of required and performed executions match, then the activity is complete from the execution point of view.

EC Features and implementation

Since 5.9.0 Everyware Cloud has added support for Activities and Ansible playbooks.
The support is generic and not directly tied to Ansible for obvious reasons.

Device Activities Definition

The most noticeable change in the UI is the new Device Activities Definition section.
This section represents a repository of all the updates available for the devices registered in the account.

Every tracked activity update is identified mainly by a name and description. There are few other customizable fields that can allow to better identify an update.

The activities definition list is obviously an extensible list customizable by the end customer.

When a new entry need to be created, a form like this needs to be filled by the user:

NOTE: This modal will be changed before release, the Supplier field will not be mandatory and/or not included for the time being. The App Name and App Version in this version will require manual insertion by the user as, respectively, ANSIBLE and V1 but in a later release the customer will just choose on a list based on the EC capabilities.

Ansible Playbook Examples

The first implementation of the activities model with ANSIBLE-V1 requires the Resource URL points to a zipped resource file.

To enable all the Device view functionalities the artifacts structure is the following:

.
├── roles
│   ├── eth-execution
│   │   ├── defaults
│   │   │   └── main.yml
│   │   ├── meta
│   │   │   └── main.yml
│   │   ├── tasks
│   │   │   └── main.yml
│   │   └── vars
│   │       └── main.yml
│   ├── eth-update
│   │   ├── callback_plugins
│   │   │   └── callback.py
│   │   ├── meta
│   │   │   └── main.yml
│   │   ├── tasks
│   │   │   └── main.yml
│   │   └── vars
│   │       └── main.yml
│   └── schedule-systemd
│       ├── defaults
│       │   └── main.yml
│       ├── meta
│       │   └── main.yml
│       ├── tasks
│       │   └── main.yml
│       ├── templates
│       │   └── ansible-execution.service.j2
│       └── vars
│           └── main.yml
└── site.yml

Please refer to the Ansible documentation for more details.

🚧

Resource playbook

The resource file must be a .zip file containing at least the site.yml playbook.

Eurotech provides a growing list of playbook examples that can be used as reference for the actual playbooks deployed in production by the customer.

Device View

The device view has been updated to support the new functionality.
For the devices that support ANSIBLE-V1 request handler a new Updates tab will be shown:

The Updates tab will show the list of activities update requests with their status and meaningful information.

When a specific request is selected, the user has the capability to resubmit the activity, for example in the case the request(s)/notification(s) got lost, cancel the selected activity or show the entry log.

Clicking on this last button will show a view like this:

where the user can explore the details of the update process.

Base Flow

The basic flow imagined counts the following steps:

• (optional) add a new Activity definition in the Device Activity Definitions section
• Access the specific device the update needs to be applied, in the Updates section, select New Update, specify the log level for the notifications provided by the device during the update and the update to apply, selecting from the list. After submitting a new entry should be available. The logs section can allow to get an immediate feedback of the status of the update. If the user selected to get no notification. The status of the update could be received (the feedback in this case can be not immediate) in the Device Logs section of the UI.