1.5. Edge Direct: Orchestration Tools

Edge Direct lets you quickly orchestrate updates and deploy builds on gateways. In other words, it schedules, manages, and deploys updates for you. It’s secure — all software is cryptographically signed and the gateway will verify that the software that got installed is what you think it is. And Edge Direct can tell you how your gateway is performing with metrics like CPU load and connectivity, and even enable you to set up alerts about performance problems with third-party alerting systems.

Rigado is pioneering the brand new discipline of DeviceOps. Simply put, this is DevOps for IoT. In DeviceOps, IoT operations and development engineers work together through the entire software service lifecycle. Edge Direct is designed to make it easy to put DeviceOps into practice.

You can interact with Edge Direct through the web interface, a command line interface, or a REST API.

1.5.1. Key Concepts

Now let’s dive into the all the things that make up Edge Direct so that you can manage your DeviceOps process:

  • Gateways: The software representation of the physical gateway
  • Apps: Edge applications packaged in edge-optimized containers called snaps that run on the gateway
  • App Revisions: Individual revisions of apps, uploaded as snap revisions
  • Channels: DeviceOps delivery categories for app revisions
  • Bundles: Collections of app and channel pairs to install automatically on gateways
  • Tags: Key/value pairs to connect bundles to gateways

gateway-icon    Gateways

In Edge Direct, a gateway is the software representation of a Cascade-500 IoT Gateway device. Edge Direct will connect to and handle software for that gateway device.

How does Edge Direct know about your gateway device? When you subscribe to Edge-as-a-Service and receive one or more gateway devices, each of those devices has been provisioned into Edge Direct using its unit serial number as a unique identifier. Each device is programmed to communicate directly with Edge Direct. Gateways stay in contact with Edge Direct once per minute.

app-icon    Apps

Apps are the software units that you can install on gateways. Apps have app revisions. An app revision is also a snap revision.

For example, an app might make calls to Edge Connect API to get beacon data, then do some processing on the data, and then send that data to your server through your own REST API so that you can collect it. Because apps run inside snap containers, they can be used for practically anything.

You create an app by registering its name with Edge Direct. The app’s name is the same as the snap name. Just be aware that the app name has to be globally unique because registering in Edge Direct also registers the snap name in the Ubuntu Snap Store.

revision-icon    App revisions

As you work on your app, you’re going to create many app revisions. Each app revision is essentially a snap revision. When you have either your first revision or a new revision of your snap ready to upload and install on gateways, you upload the snap revision into the app as an app revision. As an app is developed, you will be uploading multiple revisions for each app.

App revisions have an attribute, called the “revision number”, that is incremented every time a new revision is uploaded. The system identifies each revision by this key. Note that the revision number is not editable. If you need an editable, user-controlled identifier, use the version attribute. It can be edited in the YAML file that is used by Snapcraft to build the snap for the app revision.

channel-icon    Channels

Channels are the routes through which individual app revisions get installed onto gateways. Each app has four channels available to it, and each channel can have exactly one app revision in it at a time. Think of channels as deployment conduits or flows through which the app revisions get installed to gateways. A gateway “subscribes” to a channel to receive its app revisions. Available channels and their intended uses are:

  • Edge: For your most recent changes, probably untested, and with no guarantees attached
  • Beta: Used to provide preview releases of tested changes
  • Candidate: Used to vet uploads that should require no further code changes before moving to stable
  • Stable: What most users will consume and, as the name suggests, should represent your most polished, stable, and tested versions

These channels correspond to the channels on the Ubuntu Snap Store, and releasing app revisions to them in Edge Direct will also automatically release those revisions to the same channels in the Snap Store.

Note

If you release a revision to a channel and there is already another, different revision in that channel, then the original revision will be removed from the channel and the new revision will replace it as the revision assigned to the channel. Also, although you can have an app revision that isn’t released to any channels, you cannot install it on a gateway until it is released to a channel.

Apps are added to bundles with channels, as described in the next section. Edge Direct enables the bundle to subscribe to the app and desired channel to figure out which app revision will be installed on applicable gateways.

bundle-icon    Bundles

Bundles are collections of app and channel pairs. These collections are then matched with a gateway through tags, as described in the next section. Once matched, the bundles will be automatically installed and updated on the gateway.

For example, let’s say you have three apps you wish to deploy to a specific gateway: CloudSync, SensorCollector, and UpdateTimer. CloudSync and SensorCollector are considered stable, but you have a new version of UpdateTimer that is in the beta stage. You would create a bundle with these apps subsribed to these channels:

Table 1.1 Example bundle
App Channel
CloudSync Stable
SensorCollector Stable
UpdateTimer Beta

If multiple bundles match on the same gateway, then all app/channel pairs that are subscribed to by the bundles will be applied (and installed) on the gateway. If any matched bundles have the same app as another matched bundle, but the two have differing channels subscribed to for that app, then the riskiest channel will be applied to the gateway. Therefore, the app revision in the riskiest channel subscribed to by the applied bundles will be installed on the gateway. (See the Tags section for more details.)

Note

Edge Direct has a default bundle that is automatically applied to all gateways. This bundle contains apps that will be installed in all gateways. It cannot be tagged or deleted. (Though it can be completely empty and not applying any apps)

tag-icon    Tags

Tags are used to apply bundles to gateways. It does this by “matching” gateways and bundles. Tags are simple key/value pairs that you can add or modify through the Edge Direct interfaces. For example: {company: rigado}, {region: east}, or {customer: acme}.

You can assign tags to bundles and gateways. When a gateway checks in to the Edge Direct service, Edge Direct looks for all bundles with tags that exactly match the tags assigned to the gateway. If all of a bundle’s tags are contained in the gateway’s tags, it’s a match. Put another way, it’s a match if the bundle’s tags are a subset of the gateway’s tags. If installations or updates are required, Edge Direct handles it automatically and sends new app revisions to be installed.

Note

The ability to manage update timing is a pending feature of Edge Direct and, when implemented, will give the ability to limit when automatic installations may or may not be installed by an Edge Direct administrator.

In some cases, more than one bundle will match the gateway’s tags. When this happens, the following rules are applied:

  1. All apps in the matched bundles are applied. For example, let’s say Bundle1, Bundle2, and a gateway all have a tag of {location: basement}. Bundle1 contains MyApp1 and MyApp2 and Bundle2 contains MyApp2 and MyApp3. Then the gateway will subscribe to MyApp1, MyApp2, and MyApp3.

  2. If there are conflicting channels, then the most risky channel is used. (From least risk to most risk, the channels are: Stable, Candidate, Beta, Edge) In the previous example, let’s say that in Bundle1, MyApp2 has a channel of Candidate and in Bundle2, MyApp has a channel of Edge. Then the revision of MyApp2 that the gateway subscribes to is the one that is in the Edge channel (from Bundle2), since that is the more risky channel.

    Table 1.2 Multiple bundles assigned to a gateway
    Bundle App Channel Subscribed
    Bundle1 MyApp1 Stable yes
    MyApp2 Candidate no
    Bundle2 MyApp2 Edge yes
    MyApp3 Stable yes

1.5.2. An Example Workflow

Here’s what your workflow might look like to install your first app:

iconflow1 Create a snap by making a snapcraft.yaml file and using Snapcraft on your development host machine to turn it into a .snap file. Be sure NOT to register your snap name with Snapcraft! (We’ll do this through Edge Direct in the next step)
iconflow2 Register an app in Edge Direct with the same name as the snap you created (this will register and reserve the name for you in the snap global context).
iconflow3 Upload your snap as the first App Revision for that App.
iconflow4 Release your Revision to a Channel (most likely Edge, since you haven’t tested it yet).
iconflow5 Create a Bundle with that App and Channel.
iconflow6 Add a Tag to the Bundle with a unique key and value.
iconflow7 Add a Tag with the same key and value to the Gateway.

At this point, Edge Direct will notice that the gateway and bundle have the same tag and will automatically install the app revision on the gateway without you having to do anything else.

../_images/R-IconsFLOWV2c-blue2x.png

Figure 1.3 The workflow of publishing snaps to a gateway

Here’s what your workflow might look like when you want to replace your snap with a new revision:

  1. Make changes in your snapcraft.yaml file and/or in the files that build your snap and use Snapcraft to turn it into a new .snap file.

    Note

    It is not necessary to change the version in the snapcraft.yaml file. This parameter is for your benefit only and not used by the Edge Direct system.

  2. Upload your snap as the next revision for your app in Edge Direct.

  3. Release your revision to the same channel as the previous revision. Note that it removes your previous revision from the channel.

This is all that it takes. Because the tags still match, Edge Direct will automatically install your new revision on the gateway.

For a more detailed guide on the ins and outs of installing apps, see Deploying an App to a Gateway.