Release Bundle

The Release Bundle action block utilizes JFrog’s packaged release cycle to deploy your entire application to your edge devices.

Release Bundle Overview

A release bundle groups together the contents that make up your release and provides the bill of materials for the release. For example, you can group together the different build artifacts, such as Docker images, that make up your release. The group of files can then be deployed as a single unit to your IoT devices.

A release bundle plays a central role in the distribution flow. It specifies the different files, packages, and metadata that comprise a release, and is created and managed in JFrog Distribution. Since all the files specified in a release bundle are required in order to keep the release coherent, a release bundle is immutable.

Release Bundle Versions

JFrog Connect supports Release Bundles v1 and v2.

Release Bundle Action Block

The release bundle action block enables you to deploy a versioned package of software artifacts to your edge devices. In addition, a release bundle has the ability to deploy Docker images using the Docker Compose engine.

Deployments using the release bundle action block overwrite the entirety of the files in the device folder. Therefore, a release bundle must include all of your released software, including all dependencies.

Release Versioning

As release bundles are a complete version of your software release, it is important to follow the best practices described below in order to properly version your releases and keep control over your artifacts.

Versioned Folders

When a bundle is created in Artifactory, your files get signed and become immutable. Therefore, it is important to organize your software into versioned folders in your Artifactory repository.

The versioned structure is a user-created hierarchy of folder and sub-folders. The hierarchy you create should not not impact your application dependencies, as this is an Artifactory-only configuration. For example, an application that is stored inside the app-files repository will be organized into version folders as follows:

Before creating the Release Bundle, create a folder under app-files that includes all of your applications and name it with a version that represents the entire application as a whole.

By using this structure, you may create a Release Bundle over your v2 application that makes the contents of the v1 folder immutable.

When a binary needs to be updated, you will create a new version folder, e.g., v2, to store the new files that will eventually be bound together as another Release Bundle.

On-Device Hierarchy Dependency

The device will contain only the latest deployed version of the release bundle. Any previous versions are deleted upon deployment.

In order to ensure your application reliability on your edge devices, keep in mind the following when you deploy a release bundle:

  • Connect Agent deletes the previous binary versions.

  • Connect Agent ignores the versioned folder.

This behavior allows the device to be unaware of the repository, version, and dependencies of your software. For example, when deploying v1 of app-files to /home/user/ the app-files/v1 hierarchy will be removed and the application will be stored as follows:

/home/user/<application binaries>

By removing the previous versions together with the Repository and V1 folders, the device will always run the latest release bundle version without relying on a dependency such as the version folder name.

Prerequisites

  • JFrog Artifactory on the Cloud (SaaS) platform with a Pro, Enterprise X, or Enterprise+ license, or on the Self-Hosted platform with a Pro, Pro X, Enterprise X, or Enterprise+ license.

    • Release Bundle v2 requires JFrog Distribution and Artifactory Enterprise+.

  • Connect Agent 6.0 or later and at least one device registered.

  • A release bundle that is ready for deployment.

Drag the Action Block

To include the Release Bundle action block in your update flow, do the following:

  1. Go to Updates in the left sidebar and click Create Update Flow.

  1. Drag the Deploy Files action block and drop it in the workflow.

Configure the Action Block

Click the action block to open and configure it.

  1. Enter a name for the action block.

  2. Enter your JFrog account in the dropdown box. If your account name does not appear in the list, click Add Account to add yours to the list.

Tip: If you want the action block to pull release bundles from Artifactory Edge, add the Artifactory Edge account information in this step and use that as your JFrog Account. If the account has been added already, just choose it from the dropdown list.

  1. Enter a name for your release bundle and the version of the release bundle that you used in Artifactory.

Tip: When you deploy the Release Bundle update flow with a v2 release bundle, Connect will automatically fill the Name and Version fields and use the release bundle name and version as the App name and version.

  1. Enter the Destination Path on Device. This is where the release bundle will be installed on the edge devices. The directory on the device must exist beforehand, otherwise, the update will fail. Connect does not automatically create directories when deploying updates. You may create a folder using the Run Command action block in the General Section.

  1. (Optional) If you have one or more files in your release bundle that need to go to different paths on the edge device, mark Custom Paths. Then specify the Release Bundle Path and the Destination Path on Device for each file.

  1. (Optional) If your Release Bundle includes Docker images, mark Docker Compose, then specify the Release Bundle Path and the Destination Path on Device for the Docker Compose YAML file.

  1. Configure your On Failure policy and instructions for rolling back, if necessary.

  2. Save your action block configuration.

On Failure and Rollback

For your On Failure policy, choose the actions for Connect to do in case the Git Repository action block fails.

  • Continue Update Flow: If the Git Repository action block fails, Connect will simply continue with the next action block in the update workflow.

  • Run General Rollback: The action block and the entire update workflow are rolled back.

  • Do Action: The action to do when this action block is rolled back. In this case, the action is to revert all files.

Revert all Files

As a general precaution, Connect Agent creates a backup of the relevant device folder in a temporary location. If a rollback is required, the agent restores the folder to its initial state.

Free Memory Requirement

In order to enable Rollback functionality, your device's free memory must be greater than the update size. To calculate the amount of free memory required, use the relationship below:

Free Memory Required > Current Folder Size + Update Size + 10MB

What’s Next?

Learn more about Update Parameters and find out how they might be useful for your Release Bundles workflow.

Last updated