In the last post I outlined the three major updates that we were releasing at that time. One part of that update was a new version of the Antidote platform, which is what powers NRE Labs. In this post, I’d like to dive a bit deeper into this update specifically, as it included a number of important new features and fixes.
Antidote v0.4.0 is the first major platform update to take place since we established our formal community standup meetings, and related community engagement channels. As a result, this release includes a lot of features and enhancements that originated from the community. As of v0.4.0 we’re also moving to a more formal process for planning releases of the curriculum. This was done for the express purpose of making it easier to get involved with ongoing development activities. I say all this to further underscore the fact that if you want to get involved, the time is now. It’s still really early and there’s a lot of work left to do. If you are interested in working on the Antidote core platform, please reach out and let us know - we’ll help you get started.
As we mentioned in the last post, the NRE Labs curriculum and the Antidote platform are now on different release cycles. The Antidote development efforts will - starting now - be done independently. Once a stable version of the platform is released, the curriculum planning process will determine the work required to release a compatible version of the curriculum and update the site.
Redesigned Endpoint Abstraction
“Endpoint” is the Antidote term for “something that runs in a lesson”. Basically a container that runs some kind of software that you want to run inside a lesson environment to illustrate a topic.
One of the biggest problems with the Antidote platform to date was the very awkward and at times rigid way
that lesson Endpoints were defined within a lesson
definition. There was this type called
utilities that you would use if you just wanted a regular SSH session
to a container, but then there was
devices which added on automatic configurations to that with NAPALM. Obviously this didn’t work for anything NAPALM didn’t support.
In addition, there was
blackbox which was meant to indicate that Endpoint was supposed to exist in the lesson,
but not presented to the user in any way. We’re thinking some kind of API that a learner could call with Python,
as an example. The problem with this one was mainly that the other options had more to do with how the Endpoints were configured, and this one had to do with how they were presented. Very confusing.
On top of all that, we tried to bolt-on a way to present web content within the Antidote Web UI using iframes. This is very useful if the Endpoint you want to show doesn’t have a CLI, so the intention was honorable, but the way it was manifested inside the lesson definition was pretty bad, and we didn’t talk about it that much.
So we threw all of that hot mess out. In v0.4.0, your lesson definitions have one high-level key called
endpoints, and everything is defined there. From there you have ways to define not only how your Endpoints are configured, but also how they’re Presented to the user, and we feel like both have greatly improved over the previous model.
While the immutability of Docker images for lesson Endpoints has its advantages, there are some things you just have to be able to do at run time. For instance in Stage 1 of a lesson, you might want to have a webserver configured one way, and in the next stage, have it configured differently.
We took the concept that we originally implemented through NAPALM for network devices and made it much more generic, so that you have a variety of choices for performing Endpoint configuration. The currently supported options are:
- Ansible Playbooks
- Python Scripts
- NAPALM (the existing method for network devices)
Not all Endpoints need to be configured at runtime, and that’s okay - using these options is…..ahem…..optional. We feel this not only makes the overall abstraction behind configuration much easier to deal with, but now you can perform configuration tasks for any Endpoint. This extends lesson authors’ ability to keep the learner focused only on the task at hand.
Please see the Endpoint Configuration docs for more info on how to use this in a lesson definition.
In addition, we wanted to address the other aspect that was previously a bolt-on to the prior version of the lesson definition format, and that is how Endpoints are presented to the learner. As is fairly common in infratsructure education, a CLI option is a must. That’s why we launched with that
However, not everything is best shown in the CLI. Some things don’t even have a CLI. For intance, some lessons may want to show the benefits of self-service automation using an off-the-shelf web portal.
To provide the flexibility of being able to show a variety of content types while keeping everything within the Antidote Web UI for simplicity, every Endpoint in a lesson definition has a list of
presentations. This list can contain:
- A single entry - the usual example of presenting a single tab for an Endpoint.
- Multiple entries - useful for showing an Endpoint multiple ways. Maybe one tab with a CLI, and another to the same Endpoint’s web UI?
- Zero entries - as mentioned before, maybe you want an Endpoint to simply run in the environment and provide an API to the other Endpoints, but otherwise not be shown explicitly to the user.
Each entry can have either
http as its type, though more options will soon be supported. The former will show the traditional CLI, the latter will show an embedded Web UI via an iframe in its own tab. Soon, we’re hoping to support options like VNC, which will allow us to really cool stuff like show desktop applications (e.g. Wireshark) in the browser as part of a lesson!
You as the lesson author know how best to provide access to the Endpoints you place in your lesson, and the new
Presentations abstraction should give you the tools you need to do that - your way. Please see the Endpoint Presentation docs for more info on how to use this in a lesson definition.
The existing categorization functionality within Antidote is always something we’re looking to improve. Clearly there’s more to content than fitting into one of three buckets: “Fundamentals”, “Tools”, and “Workflows”. We’re always thinking about and seeking ideas for ways to improve this.
However, there are even higher-level, more nontechnical ways that content can be grouped. For instance, at a glance, it would be helpful to see all content contributed by a certain organization. Similarly, if there are lessons that only work in a particular environment, it would be useful to see those as well.
Lastly, sometimes it’s useful to just provide a place for folks to go further than what’s contained in the Web UI. For the NRE Labs curriculum that focuses on NRE and network automation principles, while we do our best to convey the concepts well, there is a limit to what can be taught in a bite-sized lesson. For true mastery, it’s useful to know where to go “next”.
For these considerations, we introduced the concept of a “Collection”. As a minimum, a Collection is some metadata for describing some kind of Entity. This could be a company, group of people, or even an idea, around which content can be organized. Not all collections have content at first, though this can always change.
For instance, take a look at the Collections within the NRE Labs curriculum. There, we added several Collections, not all of which have lessons today. For our purposes, the idea is to make good on the promise of NRE Labs as a community-focused automation initiative - and for that, we want to make sure that all of the other great resources for going even further are shown properly there.
Curriculum Version and Image Tagging
One of the biggest operational challenges with running Antidote in production to power the NRE Labs site has been the fact that curriculum images were not managed through any release process. This meant that all curriculum images used
latest tag in production. This made it incredibly challenging to change images without breaking production.
As part of the new release process for the curriculum (which we’ll dive into more deeply in a future post), we are now creating tags for all curriculum images when a version of the curriciulum is released. In short, when we released v1.0.0 of the curriculum, after tagging that Git repo and adding the appropriate Github release, we also built every image in the curriculum and tagged it with
As a result, the Antidote platform (specifically Syringe) has been updated so that it knows the version of the curriculum that’s been deployed. When using images referenced in a lesson definition, it will use the corresponding version for that image based on the curriculum version that’s loaded. By doing this, images can be worked on at any time, and pushed to
latest through our automated CI/CD processes, without fear of breaking production - production will only ever used stable, tagged image versions.
Similarly, all images that comprise the platform (yes Syringe and Antidote-web but also the
githelper images and the like) will be versioned and released simultaneously for the same effect. We created the antidote-images repo to house the source for these, so that they’re not mixed in with the curriculum images like they were before.
Full Antidote v0.4.0 Changelog
As always, I like to include a combined CHANGELOG. Since Antidote is now released separately from the curriculum, we’ll omit the curriculum updates, and only cover platform updates - specifically Antidote-web and Syringe:
- Redesigned Endpoint Abstraction (Configuration and Presentation) #114
- Use the more appropriate lesson.meta.yaml instead of syringe.yaml #101
- Center API and Configuration on Curriculum #98
- Collections Feature and API #104
- Limit volume mount to lesson directory #109
- Add configuration options to influxdb export #108
- Add config flag to permit egress traffic #119
- Enhanced granularity for image privileges and versions #123
- Fixed bug with ‘allow egress’ variable and added tests #125
- Specify version for all platform-related docker images #126
- Opened networkpolicy to all RFC1918 for the time being #127
- Fix bug in jupyter version tagging #128
- Added option to pass number or ‘this’ object as the argument to runSnippetInTab() function in lesson guide #45
- Update client-side to handle lessondef endpoint rename #61
- Added collections feature #62
- Adjust Jupyter path based on syringe changes #67
- Updates to handle new presentations abstraction #68
- Add dialog explaining jupyter notebooks and link to docs #77
- Minor updates to collections verbiage and nav layout #78
Please stay tuned to the platform project management community topic, and attend our weekly standup for more information on the next planned release for the Antidote platform.