Manage applications and services as Azure Resource Manager resources

You can deploy applications and services onto your Service Fabric cluster via Azure Resource Manager. This means that instead of deploying and managing applications via PowerShell or CLI after waiting for the cluster to be ready, you can now express applications and services in JSON and deploy them in the same Resource Manager template as your cluster. The process of application registration, provisioning, and deployment all happens in one step.

This is the recommended way for you to deploy any setup, governance, or cluster management applications that you require in your cluster. This includes the Patch Orchestration Application, Watchdogs, or any applications that need to be running in your cluster before other applications or services are deployed.

When applicable, manage your applications as Resource Manager resources to improve:

  • Audit trail: Resource Manager audits every operation and keeps a detailed Activity Log that can help you trace any changes made to these applications and your cluster.
  • Azure role-based access control (Azure RBAC): Managing access to clusters and applications deployed on the cluster can be done via the same Resource Manager template.
  • Azure Resource Manager (via Azure portal) becomes a one-stop-shop for managing your cluster and critical application deployments.

The following snippet shows the different kinds of resources that can be managed via a template:

{
    "apiVersion": "2019-03-01",
    "type": "Microsoft.ServiceFabric/clusters/applicationTypes",
    "name": "[concat(parameters('clusterName'), '/', parameters('applicationTypeName'))]",
    "location": "[variables('clusterLocation')]",
},
{
    "apiVersion": "2019-03-01",
    "type": "Microsoft.ServiceFabric/clusters/applicationTypes/versions",
    "name": "[concat(parameters('clusterName'), '/', parameters('applicationTypeName'), '/', parameters('applicationTypeVersion'))]",
    "location": "[variables('clusterLocation')]",
},
{
    "apiVersion": "2019-03-01",
    "type": "Microsoft.ServiceFabric/clusters/applications",
    "name": "[concat(parameters('clusterName'), '/', parameters('applicationName'))]",
    "location": "[variables('clusterLocation')]",
},
{
    "apiVersion": "2019-03-01",
    "type": "Microsoft.ServiceFabric/clusters/applications/services",
    "name": "[concat(parameters('clusterName'), '/', parameters('applicationName'), '/', parameters('serviceName'))]",
    "location": "[variables('clusterLocation')]"
}

Add a new application to your Resource Manager template

  1. Prepare your cluster's Resource Manager template for deployment. For more information, see Create a Service Fabric cluster by using Azure Resource Manager.

  2. Think about some of the applications you plan on deploying in the cluster. Are there any that will always be running that other applications may take dependencies on? Do you plan on deploying any cluster governance or setup applications? These sorts of applications are best managed via a Resource Manager template, as discussed above.

  3. Once you have figured out what applications you want to be deployed this way, the applications have to be packaged, zipped, and placed on a storage share. The share needs to be accessible through a REST endpoint for Azure Resource Manager to consume during deployment. See Create a storage account for details.

  4. In your Resource Manager template, below your cluster declaration, describe each application's properties. These properties include replica or instance count and any dependency chains between resources (other applications or services). Note that this doesn't replace the Application or Service manifests, but rather describes some of what is in them as part of the cluster's Resource Manager template. Here's a sample template that includes deploying a stateless service Service1 and a stateful service Service2 as part of Application1:

    {
     "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "clusterName": {
         "type": "string",
         "defaultValue": "Cluster",
         "metadata": {
           "description": "Name of your cluster - Between 3 and 23 characters. Letters and numbers only."
         }
       },
       "applicationTypeName": {
         "type": "string",
         "defaultValue": "ApplicationType",
         "metadata": {
           "description": "The application type name."
         }
       },
       "applicationTypeVersion": {
         "type": "string",
         "defaultValue": "1",
         "metadata": {
           "description": "The application type version."
         }
       },
       "appPackageUrl": {
         "type": "string",
         "metadata": {
           "description": "The URL to the application package sfpkg file."
         }
       },
       "applicationName": {
         "type": "string",
         "defaultValue": "Application1",
         "metadata": {
           "description": "The name of the application resource."
         }
       },
       "serviceName": {
         "type": "string",
         "defaultValue": "Application1~Service1",
         "metadata": {
           "description": "The name of the service resource in the format of {applicationName}~{serviceName}."
         }
       },
       "serviceTypeName": {
         "type": "string",
         "defaultValue": "Service1Type",
         "metadata": {
           "description": "The name of the service type."
         }
       },
       "serviceName2": {
         "type": "string",
         "defaultValue": "Application1~Service2",
         "metadata": {
           "description": "The name of the service resource in the format of {applicationName}~{serviceName}."
         }
       },
       "serviceTypeName2": {
         "type": "string",
         "defaultValue": "Service2Type",
         "metadata": {
           "description": "The name of the service type."
         }
       }
     },
     "variables": {
       "clusterLocation": "[resourcegroup().location]"
     },
     "resources": [
       {
         "apiVersion": "2019-03-01",
         "type": "Microsoft.ServiceFabric/clusters/applicationTypes",
         "name": "[concat(parameters('clusterName'), '/', parameters('applicationTypeName'))]",
         "location": "[variables('clusterLocation')]",
         "dependsOn": [],
         "properties": {
           "provisioningState": "Default"
         }
       },
       {
         "apiVersion": "2019-03-01",
         "type": "Microsoft.ServiceFabric/clusters/applicationTypes/versions",
         "name": "[concat(parameters('clusterName'), '/', parameters('applicationTypeName'), '/', parameters('applicationTypeVersion'))]",
         "location": "[variables('clusterLocation')]",
         "dependsOn": [
           "[concat('Microsoft.ServiceFabric/clusters/', parameters('clusterName'), '/applicationTypes/', parameters('applicationTypeName'))]"
         ],
         "properties": {
           "provisioningState": "Default",
           "appPackageUrl": "[parameters('appPackageUrl')]"
         }
       },
       {
         "apiVersion": "2019-03-01",
         "type": "Microsoft.ServiceFabric/clusters/applications",
         "name": "[concat(parameters('clusterName'), '/', parameters('applicationName'))]",
         "location": "[variables('clusterLocation')]",
         "dependsOn": [
           "[concat('Microsoft.ServiceFabric/clusters/', parameters('clusterName'), '/applicationTypes/', parameters('applicationTypeName'), '/versions/', parameters('applicationTypeVersion'))]"
         ],
         "properties": {
           "provisioningState": "Default",
           "typeName": "[parameters('applicationTypeName')]",
           "typeVersion": "[parameters('applicationTypeVersion')]",
           "parameters": {},
           "upgradePolicy": {
             "upgradeReplicaSetCheckTimeout": "01:00:00.0",
             "forceRestart": "false",
             "rollingUpgradeMonitoringPolicy": {
               "healthCheckWaitDuration": "00:02:00.0",
               "healthCheckStableDuration": "00:05:00.0",
               "healthCheckRetryTimeout": "00:10:00.0",
               "upgradeTimeout": "01:00:00.0",
               "upgradeDomainTimeout": "00:20:00.0"
             },
             "applicationHealthPolicy": {
               "considerWarningAsError": "false",
               "maxPercentUnhealthyDeployedApplications": "50",
               "defaultServiceTypeHealthPolicy": {
                 "maxPercentUnhealthyServices": "50",
                 "maxPercentUnhealthyPartitionsPerService": "50",
                 "maxPercentUnhealthyReplicasPerPartition": "50"
               }
             }
           }
         }
       },
       {
         "apiVersion": "2019-03-01",
         "type": "Microsoft.ServiceFabric/clusters/applications/services",
         "name": "[concat(parameters('clusterName'), '/', parameters('applicationName'), '/', parameters('serviceName'))]",
         "location": "[variables('clusterLocation')]",
         "dependsOn": [
           "[concat('Microsoft.ServiceFabric/clusters/', parameters('clusterName'), '/applications/', parameters('applicationName'))]"
         ],
         "properties": {
           "provisioningState": "Default",
           "serviceKind": "Stateless",
           "serviceTypeName": "[parameters('serviceTypeName')]",
           "instanceCount": "-1",
           "partitionDescription": {
             "partitionScheme": "Singleton"
           },
           "correlationScheme": [],
           "serviceLoadMetrics": [],
           "servicePlacementPolicies": []
         }
       },
       {
         "apiVersion": "2019-03-01",
         "type": "Microsoft.ServiceFabric/clusters/applications/services",
         "name": "[concat(parameters('clusterName'), '/', parameters('applicationName'), '/', parameters('serviceName2'))]",
         "location": "[variables('clusterLocation')]",
         "dependsOn": [
           "[concat('Microsoft.ServiceFabric/clusters/', parameters('clusterName'), '/applications/', parameters('applicationName'))]"
         ],
         "properties": {
           "provisioningState": "Default",
           "serviceKind": "Stateful",
           "serviceTypeName": "[parameters('serviceTypeName2')]",
           "targetReplicaSetSize": "3",
           "minReplicaSetSize": "2",
           "replicaRestartWaitDuration": "00:01:00.0",
           "quorumLossWaitDuration": "00:02:00.0",
           "standByReplicaKeepDuration": "00:00:30.0",
           "partitionDescription": {
             "partitionScheme": "UniformInt64Range",
             "count": "5",
             "lowKey": "1",
             "highKey": "5"
           },
           "hasPersistedState": "true",
           "correlationScheme": [],
           "serviceLoadMetrics": [],
           "servicePlacementPolicies": [],
           "defaultMoveCost": "Low"
         }
       }
     ]
    }
    

    Note

    Refer to the Service Fabric Azure Resource Manager reference to find usage and details on individual template properties.

  5. Deploy!

Remove Service Fabric Resource Provider Application resource

The following will trigger the app package to be unprovisioned from the cluster, and this will clean up the disk space used:

$resourceGroup = 'sftestcluster'
$cluster = $resourceGroup
$applicationType = 'VotingType'
$application = 'Voting'
$applicationVersion = '1.0.0'

$sf = Get-AzResource -ResourceGroupName $resourceGroup -ResourceName $cluster
$app = Get-AzResource -ResourceId "$($sf.Id)/applications/$application"
$appType = Get-AzResource -ResourceId "$($sf.Id)/applicationTypes/$applicationType"
$appTypeVersion = Get-AzResource -ResourceId "$($appType.Id)/versions/$applicationVersion"

# remove application
Remove-AzResource -ResourceId $app.Id

# remove application type version
Remove-AzResource -ResourceId $appTypeVersion.Id

# remove application type 
# Remove-AzResource -ResourceId $appType.Id

Simply removing Microsoft.ServiceFabric/clusters/application from your ARM template won't unprovision the Application. PowerShell command Remove-AzResource as shown above or performing a REST DELETE Application Type Versions - Delete directly are two options that can be used.

Note

Once the removal is complete you should not see the package version in SFX or ARM anymore. You cannot delete the application type version resource that the application is running with; ARM/SFRP will prevent this. If you try to unprovision the running package, SF runtime will prevent it.

Manage an existing application via Resource Manager

If your cluster is already up and some applications that you would like to manage as Resource Manager resources are already deployed on it, instead of removing the applications and redeploying them, you can use a PUT call using the same APIs to have the applications get acknowledged as Resource Manager resources. For additional information, see What is the Service Fabric application resource model?

Note

To allow a cluster upgrade to ignore unhealthy apps the customer can specify “maxPercentUnhealthyApplications: 100” in the “upgradeDescription/healthPolicy” section; detailed descriptions for all settings are in Service Fabrics REST API Cluster Upgrade Policy documentation.

Next steps