Cumulocity IoT Streaming Analytics 10.18.0.5+ or 24+
Introduction
Cumulocity IoT Streaming Analytics allows users to create real-time analytics applications within the platform to process messages being generated by IoT devices. These applications can be developed within the platform directly using EPL apps, or externally using the Apama Streaming Analytics tooling. When developing within the platform, however, you lack many of the normal tools for developing software such as version control, testing, quality gates, promotion, and deployment. This blog post introduces a new tool that you can deploy to your Cumulocity IoT tenant which enables more enterprise development workflows: EPL Apps GitHub Sync.
mjj29 / streaminganalytics-github-sync
Automatically synchronize assets from Cumulocity IoT Streaming Analytics with github
EPL Apps GitHub sync
This repository provides a tool to do bidirectional syncing between GitHub and Cumulocity Streaming Analytics EPL apps.
To use this you will need a Cumulocity tenant with the ability to run EPL apps, running at least Streaming Analytics 10.18.0.5, or any CD train (versions starting 24+).
To deploy it:
- Set the following tenant options in your tenant
-
streaminganalytics.github/owner
- The owner of the repository you want to sync to (the organization) -
streaminganalytics.github/repo
- The name of the repository in that organization you want to sync to -
streaminganalytics.github/branch
- The branch in the repository that you want to sync to -
streaminganalytics.github/PAT
- A Personal Access Token which has permissions to write to the repository -
streaminganalytics.github/githubAPIURL
- Optionally, if this repository is not hosted on github.com, override the URL to the github API endpoint
-
- Upload the contents of
syncapp/SyncToGithub.mon
to your tenant as an EPL App.
This will:
- …
EPL Apps GitHub Sync (referred to below as just GitHub Sync) is a tool to do bidirectional syncing between GitHub and Cumulocity IoT Streaming Analytics EPL apps.
Setting up GitHub Sync in your tenant
To use GitHub Sync you will need a Cumulocity IoT tenant with the ability to run EPL apps, running at least Streaming Analytics 10.18.0.5 or a 24 or later version from continuous deployment. Currently, it supports public or private repos on github.com, but not separate GitHub Enterprise Server instances. Access is managed via the GitHub REST API and not direct Git access.
You will need to set several tenant options in your tenant. You can set tenant options using the REST API or the Cumulocity IoT Tenant Option Management plugin. For example, if you want to synchronize to the main
branch of the repository at github.com/myorg/eplapps-repo
you would set the following tenant options:
streaminganalytics.github/owner = myorg
streaminganalytics.github/repo = eplapps-repo
streaminganalytics.github/branch = main
streaminganalytics.github/PAT = <a personal access token with write access to that repository>
Lastly, just upload SyncToGithub.mon as a new EPL app in your tenant.
This will:
- Write all EPL apps that exist at that moment in the tenant to the
epl/
directory of the GitHub repository (overwriting any earlier versions in the repository) - Deploy any already-existing apps under
epl/
from the GitHub repository to the tenant as new EPL apps - Watch for updates to EPL apps going forward and write any changes / remove any deleted EPL apps from the GitHub repository
- Watch for new commits to the GitHub repository and make any changes to match in EPL apps
Suggested workflows
Here are a few ideas of enterprise development workflows which are enabled by GitHub Sync.
Backup and history for EPL apps development
The simplest option you have is to just continue EPL apps development in the web UI as normal and let it be synchronized to GitHub. This gives you a backup of your code automatically on each change in the GitHub repository. If you ever need to restore from the backup, simply add SyncToGithub.mon
to a new blank tenant and all your EPL apps will automatically be restored. This also gives you a complete history of all your development changes via GitHub history.
Development to Production tenant promotion
A step up from just using GitHub as a backup, while still only using the Cumulocity IoT cloud development facilities, is to work with multiple tenants for different stages of development. It’s very common to have a tenant for development, another for quality assurance (QAL) and another for actual production. Having each of those tenants tracking a different branch in a repository allows you to promote code between the different stages using pull requests in GitHub. Development on the development tenant syncs to a development branch. Once it’s ready to test that on QAL then a pull request (PR) is used to bring the development version onto the branch for that tenant. Once the code change has been validated on QAL, then you can use another pull request to merge onto the production branch. At each stage, deployment is automatically managed by GitHub Sync, so you never have to have developers manually log into your production tenants and make changes to the code there. If they do, then any changes will be tracked in GitHub and won’t be overwritten by the next release from development, but instead merged by GitHub during the PR merge.
External development with automatic deployment
Some people are using the desktop Apama Streaming Analytics tooling to do local off-line development, and only deploying to the Cumulocity IoT cloud once the code is ready. With GitHub Sync you can do that development locally, committing the changes to GitHub and then rely on GitHub Sync to publish the code out of GitHub into the cloud automatically. As with the previous workflow it allows you to protect production from direct developer access and record any changes made directly to production.
Continuous deployment with automatic quality gates
Lastly, we can also include continuous quality with tests using EPL Apps Tools in PR checks to ensure continuous quality in a full CI/CD pipeline. GitHub Sync provides the final piece for automatic deployment once all the tests have passed and the code change has merged.
Conclusions and more information
As you can see, GitHub Sync provides support for these and other enterprise development workflows. For more information about the things mentioned in this post see:
- GitHub - mjj29/streaminganalytics-github-sync: Automatically synchronize assets from Cumulocity IoT Streaming Analytics with github
- GitHub - SoftwareAG/apama-eplapps-tools: Tooling for uploading apps and testing apps within Apama EPL Apps
- GitHub - SoftwareAG/cumulocity-tenant-option-management-plugin: Easily create, edit and delete tenant options. You can configure an option as encrypted and can decided between text or JSON input.
- https://www.apamacommunity.com/
- https://www.cumulocity.com/
Top comments (0)