Update Image

In JFrog Connect, you can use the Update Image step type to update edge device images at scale.

The Update Image step type enables you to easily update device images at scale. JFrog Connect integrates SWUpdate functionality to provide a robust and scalable method of deploying image updates.

Connect uses JFrog Artifactory as the image repository and employs update flow mechanisms such as on-failure and rollback, retries, and status monitoring.

When you create a Deployment that uses Update Image in an update flow, you can configure the deployment to update the image on a single device or use Connect’s robust filter mechanism to update images on any subset of devices in your fleet.

Availability: This feature is available to customers by feature flag.

Usage: You can use the Update Image step type only once in an update flow, and it must be the last step in the flow.

Prerequisites

• SWUpdate installed on the devices.

• Familiarity with the SWUpdate methodology described in SWUpdate: software update for embedded system and Update strategy examples.

• SWUpdate image file (*.SWU) uploaded to the Artifactory repository. The SWU file includes the IMG file and sw-description file.

• The default upload limit in Artifactory is 100 MG. You may need to change this if your IMG file is larger.

• In the Create Update Flow procedure, completed through Step 3.

SWUpdate File Example

The following is an example of an SWU file configured for a double-copy update.

software =
{
    version = "1.0";
    raspberrypi3 = {
        hardware-compatibility: ["1.0"];
        stable = {
            copy1 : {
                images: (
                    {
                        filename = "rootfs.img.gz";
                        sha256 = <sha256>;
                        type = "raw";
                        compressed = "zlib";
                        device = "/dev/mmcblk0p2";
                    }
                );
            };
            copy2 : {
                images: (
                    {
                        filename = "rootfs.img.gz";
                        sha256 = <sha256>;
                        type = "raw";
                        compressed = "zlib";
                        device = "/dev/mmcblk0p3";
                    }
                );
            };
        }
    }
}

• filename: The name of your compressed IMG file.

• sha256: The sha256 attribute of the IMG file. This can be obtained by running sha256sum <path_to_img> on linux machines. You can find a description of the attribute in the Attribute Reference table.

• type: SWUpdate has several options for the handler. (See Handler List.) The type is the string identifier for the handler, as it is set by the handler when it registers itself. For example: ubivol, raw, rawfile. The type you use depends on the handler you choose.

• compressed: String to indicate that the file indicated by filename is compressed and must be decompressed before being installed. The value denotes the compression type. The currently supported values are zlib and zstd.

• device: device: Device node as found in /dev or a symlink to it. This can be specified as an absolute path or a name in the /dev folder. For example, if /dev/mtd-dtb is a link to /dev/mtd3, then mtd3, mtd-dtb, /dev/mtd3, and /dev/mtd-dtb are valid names. For Raspberry Pi, the rootfs is usually /dev/mmcblck0p2. Usage depends on the handler. For files, this attribute indicates on which device the filesystem must be mounted. If not specified, the current rootfs will be used.

To install double-copy using this file, you would need to run the command:

swupdate - i stable,copy1

or

swupdate - i stable,copy2

For additional examples and explanations, see SWUpdate: syntax and tags with the default parser.

Add a Step and Configure the Step Type

To add a step and configure the step type you have chosen, do the following:

1. In the Create New Flow page, click Add Step.

2. In the Step Type dropdown list, choose Update Image, give the step a Step Name, and create the step. You can change the step name afterwards if you need to.

3. Choose the JFrog Registry where your image is stored. If the registry does not appear in the list, go to Add JFrog Registry to add yours to the list. Then return to this configuration and the added registry will appear in the list.

   Tip: If you want the step to pull content from an Artifactory Edge account, complete the procedure in Add JFrog Registry, and then choose that registry as your JFrog Registry.

1. Enter the Artifactory Path (.swu file), for example, generic-repo/1.0/file.swu. You can also make all or part of the path a parameter. For example, you could make the version folder a parameter: generic-repo/{{version}}/file.swu. Then you enter the version value when the actual deployment is run.

Tip: If you need help finding the Artifactory Path in JFrog Platform, see Get Artifactory Path.

Agent Installation and Registration

Complete the following information for agent installation and registration:

• Retain Device Credentials: Mark this to keep the current device credentials in the new image. If you leave it unmarked, you will need to register the device again after the deployment is completed. This option is recommended if you want to install a new agent version and keep the previous device credentials.

• Install Agent: Mark this to back up your current agent and reinstall it in the new image. When you choose this, the device credentials will also be backed up and used with the new image. You don't need to mark this if the agent is embedded in the new image.

Install Agent is the recommended setting for most cases. Generally, a recommended best practice is to use a separate partition (double copy strategy) for the image update. If you do the image update using a single partition, the agent and its credentials will not be backed up.

Tip: If you leave both options unmarked, then the result will be that all the devices will have the same credentials.

• Partition Name: Enter the name of the new partition. (The name will look like a path, as shown below.)

SWUpdate Command (Optional)

1. The step runs SWUpdate CLI commands like the default command shown below. You can enter additional commands and run options for the step to run on the device. For each additional command, click Add and choose the Command and Run options. The display at the bottom enables you to review the full command that will be run before you save the step.

1. Save your step configuration.

Check Status of the Software Update

To check the progress of the software update, do the following:

1. Go to Deployments in the left menu. In the Runs tab, click in the Status column of the relevant deployment.

2. In the list of devices that appears for that deployment, choose the device you want to see and open the Update Image step.

What’s Next?

Learn more about Update Parameters and find out how they can be useful in your workflows.