Service Fabric application resource model

You have multiple options for deploying Azure Service Fabric applications on your Service Fabric cluster. We recommend using Azure Resource Manager. If you use Resource Manager, you can describe applications and services in JSON, and then deploy them in the same Resource Manager template as your cluster. Unlike using PowerShell or Azure CLI to deploy and manage applications, if you use Resource Manager, you don't have to wait for the cluster to be ready; application registration, provisioning, and deployment can all happen in one step. Using Resource Manager is the best way to manage the application life cycle in your cluster. For more information, see Best practices: Infrastructure as code.

Managing your applications as resources in Resource Manager can help you gain improvements in these areas:

  • Audit trail: Resource Manager audits every operation and keeps a detailed activity log. An activity log can help you trace any changes made to the applications and to your cluster.
  • Role-based access control: You can manage access to clusters and to applications deployed on the cluster by using the same Resource Manager template.
  • Management efficiency: Using Resource Manager gives you a single location (the Azure portal) for managing your cluster and critical application deployments.

In this document, you will learn how to:

  • Deploy application resources by using Resource Manager.
  • Upgrade application resources by using Resource Manager.
  • Delete application resources.

Deploy application resources

The high-level steps you take to deploy an application and its services by using the Resource Manager application resource model are:

  1. Package the application code.
  2. Upload the package.
  3. Reference the location of the package in a Resource Manager template as an application resource.

For more information, view Package an application.

Then, you create a Resource Manager template, update the parameters file with application details, and deploy the template on the Service Fabric cluster. Explore samples.

Create a storage account

To deploy an application from a Resource Manager template, you must have a storage account. The storage account is used to stage the application image.

You can reuse an existing storage account or you can create a new storage account for staging your applications. If you use an existing storage account, you can skip this step.

Create a storage account

Configure your storage account

After the storage account is created, you create a blob container where the applications can be staged. In the Azure portal, go to the Azure Storage account where you want to store your applications. Select Blobs > Add Container.

Resources in your cluster can be secured by setting the public access level to private. You can grant access in multiple ways:

The example in the following screenshot uses anonymous read access for blobs.

Create blob

Stage the application in your storage account

Before you can deploy an application, you must stage the application in blob storage. In this tutorial, we create the application package manually. Keep in mind that this step can be automated. For more information, see Package an application.

In this tutorial, we use the Voting sample application.

  1. In Visual Studio, right-click the Voting project, and then select Package.

    Package Application

  2. Go to the .\service-fabric-dotnet-quickstart\Voting\pkg\Debug directory. Zip the contents into a file called Voting.zip. The ApplicationManifest.xml file should be at the root in the zip file.

    Zip Application

  3. Rename the file to change the extension from .zip to .sfpkg.

  4. In the Azure portal, in the apps container for your storage account, select Upload, and then upload Voting.sfpkg.

    Upload App Package

Now, the application is now staged and you can create the Resource Manager template to deploy the application.

Create the Resource Manager template

The sample application contains Azure Resource Manager templates you can use to deploy the application. The template file names are UserApp.json and UserApp.Parameters.json.

Note

The UserApp.Parameters.json file must be updated with the name of your cluster.

Parameter Description Example Comments
clusterName The name of the cluster you're deploying to sf-cluster123
application The name of the application Voting
applicationTypeName The type name of the application VotingType Must match ApplicationManifest.xml
applicationTypeVersion The version of the application type 1.0.0 Must match ApplicationManifest.xml
serviceName The name of the service Voting~VotingWeb Must be in the format ApplicationName~ServiceType
serviceTypeName The type name of the service VotingWeb Must match ServiceManifest.xml
appPackageUrl The blob storage URL of the application https://servicefabricapps.blob.core.chinacloudapi.cn/apps/Voting.sfpkg The URL of the application package in blob storage (the procedure to set the URL is described later in the article)
{
    "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/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/services",
    "name": "[concat(parameters('clusterName'), '/', parameters('applicationName'), '/', parameters('serviceName'))]",
    "location": "[variables('clusterLocation')]"
}

Deploy the application

Run the New-AzResourceGroupDeployment cmdlet to deploy the application to the resource group that contains your cluster:

New-AzResourceGroupDeployment -ResourceGroupName "sf-cluster-rg" -TemplateParameterFile ".\UserApp.Parameters.json" -TemplateFile ".\UserApp.json" -Verbose

Upgrade the Service Fabric application by using Resource Manager

Important

Any service being deployed via ARM JSON definition must be removed from the DefaultServices section of the corresponding ApplicationManifest.xml file.

You might upgrade an application that's already deployed to a Service Fabric cluster for one of these reasons:

  • A new service is added to the application. A service definition must be added to service-manifest.xml and application-manifest.xml files when a service is added to the application. To reflect a new version of an application, you also must change the application type version from 1.0.0 to 1.0.1 in UserApp.Parameters.json:

    "applicationTypeVersion": {
        "value": "1.0.1"
    },
    "serviceName2": {
        "value": "Voting~VotingData"
    },
    "serviceTypeName2": {
        "value": "VotingDataType"
    }
    
  • A new version of an existing service is added to the application. Examples include application code changes and updates to app type version and name. For this upgrade, update UserApp.Parameters.json like this:

     "applicationTypeVersion": {
        "value": "1.0.1"
    },
    

Delete application resources

To delete an application that was deployed by using the application resource model in Resource Manager:

  1. Use the Get-AzResource cmdlet to get the resource ID for the application:

    Get-AzResource  -Name <String> | f1
    
  2. Use the Remove-AzResource cmdlet to delete the application resources:

    Remove-AzResource  -ResourceId <String> [-Force] [-ApiVersion <String>]
    

Common questions and answers

Error: "Application name must be a prefix of service name" Answer: Make sure the service name is formatted as follows: ProfileVetSF~CallTicketDataWebApi.

Next steps

Get information about the application resource model: