Use Update Parameters

Learn how to maximize the flexibility of your software updates. In this page, you will learn how to create update parameters when building an update flow and fill in values when deploying the update.

Overview

When you use an update parameter in an update flow, you do not have to commit (i.e., hard code) to a specific value in an action block field. Instead, the field is parameterized, and you can enter the value upon deployment of your software update. This is a powerful tool because it enables you to create a single update workflow and then reuse it for several deployments. In each deployment, JFrog Connect prompts you to fill in the values, but the underlying workflow remains the same.

One of the strengths of Update Parameters is the combination of use with the Deploy Update API call. This enables the complete automation of continuous releases of new versions by using a standardized flow for every new application version.

When you use this method, you can know that your software updates are consistent over your software versions and across your device fleets. The examples below illustrate some typical uses of update parameters. Once you get going with JFrog Connect, you will find that there are many more ways to use the update parameters that will result in consistent and easy-to-use software update workflows.

Example A: Docker Compose Versions

You are building a workflow to update the applications on your edge devices. You know in advance that the application versions will change frequently, but you want to use exactly the same workflow over again for each version.

Solution:

You will use a parameter in the JFrog Artifactory Path to take a different version of the Docker Compose YAML for each new deployment. This method is illustrated in the steps below.

Step 1: Organize your Folders in Artifactory

In Artifactory, keep your Docker Compose files in version folders (one per folder) as shown below.

Step 2: Define the Parameter in the Workflow

In Connect, build a workflow that uses the Deploy Containers action block, and for Deployment Type, choose Docker Compose.

In Artifactory Path, which is the path of the Docker Compose YAML, enter the following:

generic-repo/app-files/{{version}}/docker-compose-file.yaml

Note that only part of the path, e.g., the version, is parameterized. The rest is fixed text. You may parameterize all or part of the path.

Step 3: Enter the Value in Deployment

In the Connect list of update workflows, find the relevant workflow and deploy it. In the Deployment window, you are prompted to enter a value for the parameter called version. Enter the version for this release. Your value should be one of the folder names you created in Artifactory, e.g., v1, v2, v3.

When you need to deploy a new version of the same application, use the same update workflow. When you deploy workflow, you will just enter a new version value in the Deployment window.

Example B: Destination Path on Device

This example combines Connect’s Groups feature with the Update Parameters feature. You have a large fleet of devices and they do not all run the same application. You use the Groups feature to segment the devices into subgroups according to the application they use. You need a simple method of updating all the devices and you don’t want to build a separate workflow for each kind of device.

Solution:

You will build a single workflow that will be flexible enough to update all the different applications to all the different device groups.

Let’s assume you have App A, App B, and App C that get updated on Device Group A, Group B, and Group C respectively.

Step 1: Set up the Update Workflow

Create an update workflow that uses the Deploy Containers action block and configure it as follows:

1. For Deployment Type, choose Docker Compose.

2. For Artifactory Path and Destination Path on Device, enter parameters, e.g., {{artifactory-path}} and {{destination-path-on-device}}.

3. Complete the On Failure configuration and save your update flow.

Step 2: Create a Deployment for a single Group

Use the update workflow to create a deployment that will update App A on Device Group-A.

1. In the Deployment, choose Group A for the Group.

2. For artifactory-path, enter the path in Artifactory that has the App A files.

3. For destination-path-on-device, enter the path that goes with the file structure on Device Group-A.

4. Complete your deployment configuration and create the deployment.

Step 3: Reuse your Workflow for the other Groups

For the other apps and device groups, complete the procedure in Step 2 as follows:

1. Using the same update workflow, create a new deployment.

2. In the Deployment, choose Group B or the relevant group for that deployment.

3. For artifactory-path and destination-path-on-device, enter the paths that correspond to the device group you are updating.

Default Values

It is important to remember that Update Parameters do not have default values. Once you have configured update parameters, you must specify values for them upon deployment of the software update.

Deploy Update Values using the API

Update Parameters can also be defined in the Deploy Update API call. In order to configure a deployment with an existing Update Parameter, use the lines below as an example to add the parameter values in your API call.

    "deployment_configuration":  {
        "flow_id": "f-dd0c-73b9",
        "parameters_mapping": {
            "username": "ubuntu",
            "conf_path": "/etc/app/settings.conf"
        }
    }

What’s Next?

Learn more about how you Deploy an Update Flow.