Github Action to push desired state to Cisco RoomOS and MPP/PhoneOS devices using app.device-view.com Api
This repository provides a solution for managing Cisco RoomOS and MPP/PhoneOS device configuration using Infrastructure as Code (IaC) principles. It uses a Github action to push the desired state to Cisco devices, with device-view.com as the integration service with Webex xApi. Github actions can be triggered when a commit is made to a repository, on a schedule or manually triggered.
The Github action requires the following information in order to deploy Cisco devices:
- Api Token to device-view.com Api
- List of target devices (i.e. Mac Addresses)
- List of commands (i.e. xCommand's) to send
To use this Github action the simplest approach is to Fork this repository (can be made private), add/update the relevant target and command files and set an ApiToken within the Repository Action Secrets.
Once the repository is setup and an appropriate commit is made (or at a specified time/schedule) all the commands will be sent to all the specified targets. This provides the ability to have a Desired State specified within the command file(s) and have that state pushed automatically (or manually triggered) to the specified target devices.
In order to use this Github Action you will need to obtain a Api Token from identity.device-view.com. You will need to store your Api Token as a repository secret (Settings > Secrets and Variables > Actions). The default name for this secret is API_TOKEN.
Note: Currently the Api Token available from identity.device-view.com is a short lived (90min) JWT Access Token. In the future device-view.com will provide a way to create/rotate/revoke Api Tokens with a custom duration.
.
+-- .github/workflows/main.yml # Github Action Workflow, runs on repo commit
+-- device-view-deploy-action/* # Custom Github Action called by main.yml
+-- src # Source files, contains all target and command files
+-- example-group # Desired state group
+-- targets.csv # Target device list
+-- commands.txt # Comamnd listThe included main.yml & device-view-deploy-action/* files do not need to be modified for most scenarios. Only the main.yml file would be modified to override defaults such as the target and command file names to search for.
The src/ folder contains the desired state files, these are saved in their own folder(s) (any folder name can be used). You can consider each folder (within src/) as a Desired State Group effectively a set of devices that will be given the same state by running the provided commands within the commands.txt file.
By default the Github Action searches the src/ folder for files with the file name 'target*.csv'. Some examples this matches:
- target1.csv
- target2.csv
- target-location1.csv
- target-location2.csv
This allows multiple targets files within a single Desired State Group folder, the contents of the files are combined to a single list of targets (duplicates are skipped). This makes it easier to manage target files by saving a group of targets to a single file (i.e. for a location/site) and manage which groups of targets are assigned to their relevant desired state.
The target files contain a simple list of device Mac addresses with one device per line, refer to the sample targets.csv file as an example.
By default the Github Action searches the src/ folder for files with the file name 'command*.txt'. Some examples this matches:
- command1.txt
- command2.txt
- command-Users.txt
- command-Video.txt
This allows for commands to be split across multiple files i.e. grouped by feature/setting they configure. Again this allows for command files to be copied to other Desired State Group folders for re-use and makes managing large sets of commands easier.
The command file contains a simple list of commands (i.e. xCommand) with a single command per line, refer to the sample commands.txt file as an example.
Command files support parameterized commands, this allows for inserting/interpolating values into the commands for each target device. By including additional columns in the target.csv file these columns can be used to insert values into the command. Interpolation uses the Mustache templating language, the following target.csv file includes a systemUnitName column:
id,systemUnitName
CC5A535FEA2F,DemoUnit1The command file can then use the systemUnitName column to insert the value into the command:
xConfiguration SystemUnit Name: {{systemUnitName}}
This would result in the following command being sent to the CC5A535FEA2F device:
xConfiguration SystemUnit Name: DemoUnit1
Note: The column name is case sensitive and must match exactly and the first column must be 'id' as this is used to match the target device. Note: The advanced sample targets.csv and commands.txt files includes examples of using parameterized commands. Note: In the future a global set of parameters will be available to all commands, this will allow for a single parameter to be used across all commands. This is ideal for passwords to be passed from GitHub Secrets so they are not stored in the repository.
As this is a git repository you can take advantage of branches to scope what updates/states are deployed. For example you could create a 'test' branch and only include targets for test devices. Once changes are complete you can merge the 'test' branch back into 'main' to add in the updated commands to then deploy to production targets.
Running locally requires nodejs to be installed, this can be downloaded from nodejs.org.
To run the Github Action locally you can use the device-view-deploy-action nodejs script. This accepts the same parameters as the Github Action and will run the same logic locally. The following example will run the script with the default parameters:
cd device-view-deploy-action
node index.js --api-token <API_TOKEN>In the future the device-view.com platform/Api will incorporate a device filter feature. When filters are available if the Desired State Group folder name matches a filter name then a target file is not required as the devices that match the filter will become the targets. Therefore only command file(s) will be necessary eliminating the need to manipulate device Mac addresses and enables dynamic matching i.e. a new device added will be updated the next time the Github Action is triggered.
In the future support will be added for RoomOS macros, this will be a case of saving the macro (ie. index.js file) to a 'macros' subfolder within a Desired State Group folder. The javascript file must be saved in its own folder, the folder name that contains the javascript file will be used as the name of the macro.
Here is an example of the folder structure with a macro called 'macro1':
.
+-- src # Source files, contains all target and command files
+-- example-group # Desired state group
+-- targets.csv # Target device list
+-- commands.txt # Comamnd list
+-- macros # Macros folder
+-- macro1 # Individual macro folder, folder name is used as macro name
+-- index.js # Macro javascript file to upload to target RoomOS devicesSome xCommands (i.e. uploading a Macro) are multi-line, the device-view.com Api supports multiline commands however a way to handle them in the commands.txt file has not been implemented as yet.
Currently the device-view.com Api will return an error if a device is offline, this would mean the device would not be updated until it is next online and the Github Action is triggered. In the future we shall look at updating the device-view.com Api to allow offline devices to be retried at a later time. This will most likely use an optional field i.e. 'deployment-tag' that would hold a unique identifier for the deployment such as the commit hash. The device-view.com Api would then be able to track the deployment and retry any offline devices when they come back online. Any subsequent deployment with a different 'deployment-tag' would be considered a new deployment and any previous commands with a different 'deployment-tag' would be removed.
The device-view.com Api is designed to consolidate and simplify operations with Cisco RoomOS and MPP/PhoneOS devices. As part of this simplification it is possible to send xConfiguration and xStatus commands to the device-view.com Api. A Github action is best suited for pushing configuration/state however we think there would be merit if we could also use this action to query device information and save/export.
As this is a new project we would welcome any feedback, please feel free to raise an issue or contact us directly.