Edit

Share via

Tutorial: Create a solution with shared adapter dependency

In this tutorial, you use the workload orchestration via CLI to create a Factory Sensor Anomaly Detector (FSAD) solution which is dependent on a Shared Sync Adapter (SSA) solution. A shared sync adapter is a component used in various solutions to manage data synchronization between devices and servers.

The FSAD solution is deployed on a child target, while the SSA solution is deployed on a parent target. The FSAD solution uses the SSA solution to synchronize data between devices and servers.

Prerequisites

Note

You can reuse the global variables defined in Prepare the basics to run workload orchestration and the resource variables defined in Set up the resources of workload orchestration.

Description of the user scenario

The following example illustrates the user scenario of creating a solution with shared adapter dependency.

  1. A user creates an SSA instance, ssa-instance-1, using a portal or CLI. This instance is then added as a dependency to FSAD. This means FSAD relies on ssa-instance-1 for its configuration or functionality.

  2. When FSAD is deployed to a target, for example Chicago, the Chicago-specific configuration is injected into the SSA configuration of ssa-instance-1. If FSAD is later deployed to another target, for example Redmond, the Redmond-specific configuration is appended to the existing configuration of ssa-instance-1. SSA configurations are target-specific, which means they are not shared across different targets.

    • After deploying FSAD to Chicago, ssa-instance-1 has Chicago-specific settings.
    • After deploying FSAD to Redmond, ssa-instance-1 has both Chicago and Redmond configurations.

  3. The user creates a second SSA instance, ssa-instance-2, and adds it as a dependency for FSAD for specific targets. During deployment, the service only looks for configurations of FSAD that depend on ssa-instance-2. It ignores configurations related to ssa-instance-1. Dependencies are instance-specific. If FSAD is configured to depend on ssa-instance-2 for certain targets, only those targets inject configurations into ssa-instance-2.

  4. When FSAD is uninstalled from Chicago, the Chicago-specific configuration is removed from the SSA instance it depends on, which is ssa-instance-1. Uninstalling FSAD from a target cleans up the configurations injected into the SSA instance for that target.

    • If FSAD is uninstalled from Chicago, the Chicago-specific settings are removed from ssa-instance-1.
    • If FSAD is uninstalled from Redmond, the Redmond-specific settings are removed from ssa-instance-1.

Note

Service only updates the configmap of solution in K8s edge. It isn't restarting the FSAD if deployment is via Helm. If you want the solution to restart on every configuration change, you have to author the Helm chart in such a way to ensure application would restart on configuration update. For more information, see Kubernetes K8 guide

Configuration templating for FSAD and SSA

A configuration template is a YAML file that defines the configuration parameters for a solution. The configuration template is used to create a configuration schema, which is a JSON file that defines the structure of the configuration data.

Note

Check out Configuration template and Configuration schema for the list of rules used to define the template and schema for configurations and details to write conditional or nested expressions in the schema for custom validations.

Sample of a FSAD configuration template:

dependencies:
    - solutionTemplateId: <solution template id of SSA>
      configsToBeInjected:
          - from: AppConfig
            to:dependentAppConfigs                 
configs:
  AppConfig:
     TargetName: ${{$val(LineName)}}
     TargetTag: ${{$val(LineTag)}}     
     AppName: FSAD

Sample of an SSA configuration template:

configs:
  AppName: SSA
  DepedentAppConfigs: []   #It should be array or null

AppConfig of the FSAD configuration template changes at every target and target specific AppConfig gets injected into DependantAppConfigs of SSA configuration template.

Define the variables for solution templating

Create the template and schema YAML files by referring to shared-schema.yaml and app-config-template.yaml in the compressed folder from the GitHub repository.

The following variables are used in the commands. You can change the values of these variables as per your requirements.

# Create variables for schema
# Enter schema name
schemaName="SSAschema"
app2SchemaName="FSADschema"
# Enter schema file name
schemaFile="ssa-schema.yaml"
app2SchemaFile="fsad-schema.yaml"
# Enter value in x.x.x format
schemaVersion="1.0.0"
app2SchemaVersion="1.0.1"

# Create variables for application/solution
# Enter name of application
appName1="SSA"
appName2="FSAD"

# Enter description for application
desc="To manage data synchronization between devices and servers"
desc2="Factory Sensor Anomaly Detector"
# Enter capabilities of application
appCapList1="[soap,conditioner]"
appCapList2="[soap]"
# Enter configuration template file name for the application 
appConfig="ssa-config-template.yaml"
appConfig2="fsad-config-template.yaml"
# Enter value in x.x.x format
appVersion="1.0.0"
app2Version="1.0.1"

Note

Variables need to be defined each time a new terminal is opened up.

Create a target at parent level for SSA

  1. Create targetspecs.json file by referring to the targetspecs.json file in the GitHub repository.

  2. Look up the custom location details.

    customLocationName=$(az resource list --resource-type "Microsoft.ExtendedLocation/customLocations" --resource-group "$rg" --name "$clusterName-Location" --query "[].id" --output tsv)

  3. Create a target at parent level. Ensure custom-location.json is updated with the created custom location's ID.

    parentName="<parent_name>"
parentDesc="<parent_description>"
level1="<hierarchy_level>"
capParentList="<capabilities_list>"
parentScope="$parentName-scope"

az workload-orchestration target create \
    --resource-group "$rg" \
    --location "$l" \
    --name "$parentName" \
    --display-name "$parentName" \
    --hierarchy-level "$level1" \
    --capabilities "$capParentList" \
    --description "$parentDesc" \
    --solution-scope "$parentScope" \
    --target-specification "@targetspecs.json" \
    --extended-location "@custom-location.json" \
    --context-id "/subscriptions/$subId/resourceGroups/$rg/providers/private.edge/contexts/$contextParentName"

Create a schema for Shared Sync Adapter (SSA)

Create the shared solution schema. The following command takes version input from CLI argument:

az workload-orchestration schema create --resource-group "$rg" --location "$l" --schema-name "$schemaName" --version "$schemaVersion" --schema-file "$schemaFile"

Create a Shared Sync Adapter (SSA) solution template

  1. Create a specs.json file by referring to specs.json in the compressed folder from the GitHub repository.

  2. In your specs.json file, update the helm url, for example, contosocm.azurecr.io/helm/app, and chart version in x.x.x format, for example, 0.5.0. Update the app-config-template.yaml file with proper reference to your schema which you created in the previous step.

  3. Create the SSA solution template using the following command. The following command takes version input from CLI argument:

    az workload-orchestration solution-template create --resource-group "$rg" --location "$l" --solution-template-name "$appName1" --description "$desc" --capabilities "$appCapList1" --config-template-file "$appConfig" --specification "@specs.json" --version "$appVersion"

Create a target at child level for FSAD

Create a target at child level. Ensure custom-location.json is updated with the created custom location's ID.

az workload-orchestration target create --resource-group $rg --location $l --name $childName --display-name $childName --hierarchy-level $level2 --capabilities $capChildList --description "$childDesc" --solution-scope "$childName-scope" --target-specification '@targetspecs.json' --extended-location '@custom-location.json' --context-id "/subscriptions/$subId/resourceGroups/$rg/providers/private.edge/contexts/$contextChildName"

Note

Update the parameter solutionTemplateId under dependencies section of FSAD configuration template and schema with the SSA solution template ID. The ``solution-template create` command displays the ID along with solution template version.

solutionTemplateId="/subscriptions/$subId/resourceGroups/$rg/providers/Microsoft.Edge/solutiontemplates/$appName1"

Create a schema for FSAD

Create the shared solution schema. The following command takes version input from CLI argument:

az workload-orchestration schema create --resource-group "$rg" --location "$l" --schema-name "$app2SchemaName" --version "$app2SchemaVersion" --schema-file "$app2SchemaFile"

Create a FSAD solution template

  1. Create a fsad-specs.json file by referring to fsad-specs.json in the compressed folder from the GitHub repository.

  2. In your fsad-specs.json file, update the helm url, for example, contosocm.azurecr.io/helm/app, and chart version in x.x.x format, for example, 0.5.0.

  3. Create the FSAD solution template using the following command:

    # Any modifications to solution files will necessitate version update.

az workload-orchestration solution-template create --resource-group "$rg" --location "$l" --solution-template-name "$appName2" --description "$desc2" --capabilities "$appCapList2" --config-template-file "$appConfig2" --specification "@fsad-specs.json" --version "$app2Version"

Set the configuration values for the solution

  1. View parameters of FSAD at child level.

    az workload-orchestration configuration show --resource-group "$rg" --target-name "$childName" --solution-template-name "$appName2"

  2. Edit parameters of FSAD at child level.

    az workload-orchestration configuration set --resource-group "$rg" --target-name "$childName" --solution-template-name "$appName2"

Tip

You can also set the configuration values for the solution using the Configure tab in Workload orchestration portal

Review the configuration values

  1. Run target review command for SSA with dependencies.

    # Fetch the appVersion from SSA solution create command
az workload-orchestration target review --resource-group "$rg" --solution-name "$appName1" --solution-version "$appVersion" --target-name "$parentName"

  2. Update the solution version ID, Id, from the output of previous command in the dependencies.json file.

  3. Run target review command for FSAD with dependencies. Ensure that the FSAD solution version has dependencies listed in the CLI output.

    # Fetch the appVersion from FSAD solution create command
az workload-orchestration target review --resource-group "$rg" --solution-name "$appName2" --solution-version "$app2Version" --target-name "$childName" --solution-dependencies "@dependencies.json"

  4. Copy the solutionTemplateVersionId from solutionDependencies in the output. Execute the az rest command and ensure FSAD configuration is injected.

    solutionTemplateVersionId="<solutionTemplateVersionId>"
az rest --uri "$solutionTemplateVersionId?api-version=2025-01-01-preview" --method GET

  5. In the CLI response, check reviewId and name values. The name displays the new solution template version.

Deploy the solution

  1. Run target publish to publish FSAD solution with dependencies. The command publishes the FSAD solution with dependencies to SSA. Enter the reviewId from the previous command response.

    reviewId="<reviewId>"
az workload-orchestration target publish --resource-group "$rg" --target-name "$childName" --solution-version-id /subscriptions/$subId/resourceGroups/$rg/providers/private.edge/targets/$childName/solutions/$appName2/versions/$app2Version

  2. Run target install command to deploy the solution.

    az workload-orchestration target install --resource-group "$rg" --target-name "$childName" --solution-version-id /subscriptions/$subId/resourceGroups/$rg/providers/private.edge/targets/$childName/solutions/$appName2/versions/$app2Version

Tip

You can also deploy the solution using the Deploy tab in Workload orchestration portal