4.2. Deploying an App to a Gateway

In the Overview section An Example Workflow, we introduced the basic steps of how to install an application on a gateway. This document will discuss this process in more detail. Not all of the steps in this process will apply to every deployment situation, so at the end of this document there are a few example scenarios laid out referencing the steps required.

4.2.1. Review of Concepts

Note

The information here is meant to supplement a previous section: Key Concepts.

In order for an application to be installed on a gateway, a few pieces need to be in the right place.

  1. The app must have a revision assigned to a channel.
  2. The bundle must subscribe to that app in that channel.
  3. The gateway and bundle must both have the same tags.

The different channels represent different levels of risk. The “edge” channel is the riskiest, followed by “beta”, “candidate”, and finally “stable”. When a bundle subscribes to an app channel, it will receive all new revisions assigned to that channel, from that app. This way, a bundle can represent a group of apps each at specific levels of risk. For example, if you’re creating a new application to run alongside an existing one, you could set up the bundle with the following subscriptions:

App Channel
MyNewApplication Edge
MyExistingApplication Candidate
ThirdPartyDependency Stable

This way, any gateway receiving this bundle would have your latest in-development changes of the new application, a stable version of the third-party dependency, and release candidates of your existing in-house application.

4.2.2. Steps to Install a new Application on a Gateway

Create the application and upload a revision

  1. In the   app-icon-sm   apps page, click the create app button in the top-right corner.
  2. Fill in the name. App names must be unique across all of Edge Direct, and all of Snapcraft. We recommend prefixing your app name with a company domain (e.g. acme-sensor-app instead of sensor-app). Click the REGISTER button.
  3. When an application is first created, its detail view will show a large button to upload the first revision. Click this button.
  4. Either drag a .snap file from your file explorer to the new dialog, or click the dialog to open a file picker. The snap in the .snap file must match the name of the application you registered previously. If the names do not match, the upload will not be accepted. If necessary, rebuild the snap with the correct name, then upload the new .snap file.

Release the new revision to a channel

  1. Determine which channel is most applicable for the new revision to be released to.
    • Edge is meant for applications in active development. It is for testing new features, checking for bugs, and contains untested code.
    • Beta is meant for in-house testing and QA processes. There may still be bugs in the code, but it has gone through some testing already.
    • Candidate is meant for a more wide-spread vetting process, or perhaps it could be used to allow some users to have access to “pre-release” or “release-candidate” builds.
    • Stable is the end goal of all applications. Features are complete, tested, and have gone through any necessary QA steps.
  2. Assign the new revision to a channel. If the revision upload dialog is still showing, you can do it from there. Otherwise, open the app details view and use the dropdown in the corresponding channel to select the new revision.

Create a new bundle, and subscribe to the app channel

  1. If you do not already have a   bundle-icon-sm   bundle in mind to release the app to, you may want to create a new one. On the bundles page, click the + button to create a new one. Give it a name and short description and click SAVE.
  2. In the details view of the bundle (whether the one you just created, or an existing bundle), click the EDIT button in the top-right corner. Click add an app, then select your app from the dropdown. Then, select the channel you wish to subscribe to, and click ADD. Finally, click SAVE in the top-right corner, and confirm any resulting dialogs. The bundle detail view should now show your new app, in the chosen channel.

Create any necessary tags, and tag the bundle and gateway

  1. Tagging can be quite powerful. It can enable you to have many separate groups of gateways subscribed to various bundles of apps. For now we’ll set up the bundle and gateway with one matching tag, to keep it simple.
  2. On the   tag-icon-sm   tags page, click the add tags key button. Enter the key for the new tag, and click SAVE.
  3. On the   gateway-icon-sm   gateways page, select the gateway you wish to release the bundle to, and click the TAGS tab in the detail view. Click the add a tag button. Select your tag from the dropdown, and give it a value, then click SAVE. Repeat this with any other gateways you wish to release the bundle to.
  4. On the   bundle-icon-sm   bundles page, select your app bundle. Click the EDIT button in the top-right corner. Click the TAGS tab in the detail view, then the add a tag button. Select your tag, and enter the same value you gave the gateway(s).

Important

It is imperative that the gateway have all the same tags that the bundle has. The gateway may also have other tags the bundles does not have. For instance:

Gateway tags Bundle tags Result
location=floor
location=floor
match
location=wall
location=floor
no match (“location” value mismatch)
location=floor
client=acme
location=floor
match
location=floor
location=floor
client=acme
no match (gateway missing “client” tag)

4.2.3. Common Scenarios

The steps above illustrate the process used to install a brand new application to a gateway. However, over the course of using Cascade Edge-as-a-Service you will likely run into many other scenarios in deploying your apps. Below are some common ones, with differences from the above process noted.

Updating an Application

After you have installed an application on a gateway, updating to a new version of that application requires much less setup:

  1. Upload the new snap file
  2. Assign the revision it creates to the applicable channel

Once this assignment is done, the gateway(s) will fetch the new revision.

Promoting an Existing Revison to a Higher Channel

In this scenario, you have an application on the “edge” channel, but now it’s ready for someone else to test and you want to promote it to “beta”.

  1. Open the app detail view
  2. In the Beta section, change the revision using the dropdown
  3. Confirm the change in the resulting dialog

Any gateways following the “beta” channel will automatically update.

Rolling-Back Versions

Let’s say you release a revision to a channel that wasn’t quite ready for primetime. Rolling back to the previously-released revision is similar to releasing a new revision:

  1. Open the app detail view
  2. Look at the Revisions table. Revisions that have been released to each channel have check-marks, either green for being the latest release, or grey for being a previous release
  3. Find the revision you want to roll-back to
  4. Use the dropdowns at the top of the detail view to assign that revision to the applicable channel.
  5. Confirm the change in the resulting dialog

Any gateways following that channel will automatically update to the newly-assigned revision.