Deploy and remove applications using PowerShell

Once an application type has been packaged, it's ready for deployment into an Azure Service Fabric cluster. Deployment involves the following three steps:

1. Upload the application package to the image store.
2. Register the application type with image store relative path.
3. Create the application instance.

Once the deployed application is no longer required, you can delete the application instance and its application type. To completely remove an application from the cluster involves the following steps:

1. Remove (or delete) the running application instance.
2. Unregister the application type if you no longer need it.
3. Remove the application package from the image store.

If you use Visual Studio for deploying and debugging applications on your local development cluster, all the preceding steps are handled automatically through a PowerShell script. This script is found in the Scripts folder of the application project. This article provides background on what that script is doing so that you can perform the same operations outside of Visual Studio.

Another way to deploy an application is by using external provision. The application package can be packaged as sfpkg and uploaded to an external store. In this case, upload to the image store is not needed. Deployment needs the following steps:

1. Upload the sfpkg to an external store. The external store can be any store that exposes a REST http or https endpoint.
2. Register the application type using the external download URI and the application type information.
3. Create the application instance.

For cleanup, remove the application instances and unregister the application type. Because the package was not copied to the image store, there is no temporary location to cleanup. Provisioning from external store is available starting with Service Fabric version 6.1.

Connect to the cluster

Before you run any PowerShell commands in this article, always start by using Connect-ServiceFabricCluster to connect to the Service Fabric cluster. To connect to the local development cluster, run the following:

Connect-ServiceFabricCluster

For examples of connecting to a remote cluster or cluster secured using Microsoft Entra ID, X509 certificates, or Windows Active Directory see Connect to a secure cluster.

Upload the application package

Uploading the application package puts it in a location that's accessible by internal Service Fabric components. If you want to verify the application package locally, use the Test-ServiceFabricApplicationPackage cmdlet.

The Copy-ServiceFabricApplicationPackage command uploads the application package to the cluster image store.

Suppose you build and package an application named MyApplication in Visual Studio 2015. By default, the application type name listed in the ApplicationManifest.xml is "MyApplicationType". The application package, which contains the necessary application manifest, service manifests, and code/config/data packages, is located in C:\Users<username>\Documents\Visual Studio 2015\Projects\MyApplication\MyApplication\pkg\Debug.

The following command lists the contents of the application package:

$path = 'C:\Users\<user\>\Documents\Visual Studio 2015\Projects\MyApplication\MyApplication\pkg\Debug'
tree /f $path

Folder PATH listing for volume OSDisk
Volume serial number is 0459-2393
C:\USERS\USER\DOCUMENTS\VISUAL STUDIO 2015\PROJECTS\MYAPPLICATION\MYAPPLICATION\PKG\DEBUG
│   ApplicationManifest.xml
│
└───Stateless1Pkg
    │   ServiceManifest.xml
    │
    ├───Code
    │       Microsoft.ServiceFabric.Data.dll
    │       Microsoft.ServiceFabric.Data.Interfaces.dll
    │       Microsoft.ServiceFabric.Internal.dll
    │       Microsoft.ServiceFabric.Internal.Strings.dll
    │       Microsoft.ServiceFabric.Services.dll
    │       ServiceFabricServiceModel.dll
    │       Stateless1.exe
    │       Stateless1.exe.config
    │       Stateless1.pdb
    │       System.Fabric.dll
    │       System.Fabric.Strings.dll
    │
    └───Config
            Settings.xml

If the application package is large and/or has many files, you can compress it. The compression reduces the size and the number of files. This results in faster registering and unregistering of the application type. Upload time may be slower currently, especially if you include the time to compress the package.

To compress a package, use the same Copy-ServiceFabricApplicationPackage command. Compression can be done separate from upload, by using the SkipCopy flag, or together with the upload operation. Applying compression on a compressed package is no-op. To uncompress a compressed package, use the same Copy-ServiceFabricApplicationPackage command with the UncompressPackage switch.

The following cmdlet compresses the package without copying it to the image store. The package now includes zipped files for the Code and Config packages. The application and the service manifests are not zipped, because they are needed for many internal operations (like package sharing, application type name and version extraction for certain validations). Zipping the manifests would make these operations inefficient.

Copy-ServiceFabricApplicationPackage -ApplicationPackagePath $path -CompressPackage -SkipCopy
tree /f $path

Folder PATH listing for volume OSDisk
Volume serial number is 0459-2393
C:\USERS\USER\DOCUMENTS\VISUAL STUDIO 2015\PROJECTS\MYAPPLICATION\MYAPPLICATION\PKG\DEBUG
|   ApplicationManifest.xml
|
└───Stateless1Pkg
       Code.zip
       Config.zip
       ServiceManifest.xml

For large application packages, the compression takes time. For best results, use a fast SSD drive. The compression times and the size of the compressed package also differ based on the package content. For example, here is compression statistics for some packages, which show the initial and the compressed package size, with the compression time.

Once a package is compressed, it can be uploaded to one or multiple Service Fabric clusters as needed. The deployment mechanism is the same for compressed and uncompressed packages. Compressed packages are stored as such in the cluster image store. The packages are uncompressed on the node, before the application is run.

The following example uploads the package to the image store, into a folder named "MyApplicationV1":

Copy-ServiceFabricApplicationPackage -ApplicationPackagePath $path -ApplicationPackagePathInImageStore MyApplicationV1 -TimeoutSec 1800

If you do not specify the -ApplicationPackagePathInImageStore parameter, the application package is copied into the "Debug" folder in the image store.

PS C:\> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath $path -ApplicationPackagePathInImageStore MyApplicationV1 -ImageStoreConnectionString (Get-ImageStoreConnectionStringFromClusterManifest(Get-ServiceFabricClusterManifest)) -TimeoutSec 1800

Import-Module "$ENV:ProgramFiles\Microsoft SDKs\Service Fabric\Tools\PSModule\ServiceFabricSDK\ServiceFabricSDK.psm1"

The time it takes to upload a package differs depending on multiple factors. Some of these factors are the number of files in the package, the package size, and the file sizes. The network speed between the source machine and the Service Fabric cluster also impacts the upload time. The default timeout for Copy-ServiceFabricApplicationPackage is 30 minutes. Depending on the described factors, you may have to increase the timeout. If you are compressing the package in the copy call, you need to also consider the compression time.

Register the application package

The application type and version declared in the application manifest become available for use when the application package is registered. The system reads the package uploaded in the previous step, verifies the package, processes the package contents, and copies the processed package to an internal system location.

Run the Register-ServiceFabricApplicationType cmdlet to register the application type in the cluster and make it available for deployment:

Register the application package copied to image store

When a package was previously copied to the image store, the register operation specifies the relative path in the image store.

Register-ServiceFabricApplicationType -ApplicationPathInImageStore MyApplicationV1

Register application type succeeded

"MyApplicationV1" is the folder in the image store where the application package is located. The application type with name "MyApplicationType" and version "1.0.0" (both are found in the application manifest) is now registered in the cluster.

Register the application package copied to an external store

Starting with Service Fabric version 6.1, provision supports downloading the package from an external store. The download URI represents the path to the sfpkg application package from where the application package can be downloaded using HTTP or HTTPS protocols. The package must have been previously uploaded to this external location. The URI must allow READ access so Service Fabric can download the file. The sfpkg file must have the extension ".sfpkg". The provision operation should include the application type information, as found in the application manifest.

Register-ServiceFabricApplicationType -ApplicationPackageDownloadUri "https://sftestresources.blob.core.chinacloudapi.cn:443/sfpkgholder/MyAppPackage.sfpkg" -ApplicationTypeName MyApp -ApplicationTypeVersion V1 -Async

The Register-ServiceFabricApplicationType command returns only after the system has successfully registered the application package. How long registration takes depends on the size and contents of the application package. If needed, the -TimeoutSec parameter can be used to supply a longer timeout (the default timeout is 60 seconds).

If you have a large application package or if you are experiencing timeouts, use the -Async parameter. The command returns when the cluster accepts the register command. The register operation continues as needed. The Get-ServiceFabricApplicationType command lists the application type versions and their registration status. You can use this command to determine when the registration is done.

Get-ServiceFabricApplicationType

ApplicationTypeName    : MyApplicationType
ApplicationTypeVersion : 1.0.0
Status                 : Available
DefaultParameters      : { "Stateless1_InstanceCount" = "-1" }

Remove an application package from the image store

If a package was copied to the image store, you should remove it from the temporary location after the application is successfully registered. Deleting application packages from the image store frees up system resources. Keeping unused application packages consumes disk storage and leads to application performance issues.

Remove-ServiceFabricApplicationPackage -ApplicationPackagePathInImageStore MyApplicationV1

Create the application

You can instantiate an application from any application type version that has been registered successfully by using the New-ServiceFabricApplication cmdlet. The name of each application must start with the "fabric:" scheme and must be unique for each application instance. Any default services defined in the application manifest of the target application type are also created.

New-ServiceFabricApplication fabric:/MyApp MyApplicationType 1.0.0

ApplicationName        : fabric:/MyApp
ApplicationTypeName    : MyApplicationType
ApplicationTypeVersion : 1.0.0
ApplicationParameters  : {}

Multiple application instances can be created for any given version of a registered application type. Each application instance runs in isolation, with its own work directory and process.

To see which named apps and services are running in the cluster, run the Get-ServiceFabricApplication and Get-ServiceFabricService cmdlets:

Get-ServiceFabricApplication  

ApplicationName        : fabric:/MyApp
ApplicationTypeName    : MyApplicationType
ApplicationTypeVersion : 1.0.0
ApplicationStatus      : Ready
HealthState            : Ok
ApplicationParameters  : {}

Get-ServiceFabricApplication | Get-ServiceFabricService

ServiceName            : fabric:/MyApp/Stateless1
ServiceKind            : Stateless
ServiceTypeName        : Stateless1Type
IsServiceGroup         : False
ServiceManifestVersion : 1.0.0
ServiceStatus          : Active
HealthState            : Ok

Remove an application

When an application instance is no longer needed, you can permanently remove it by name using the Remove-ServiceFabricApplication cmdlet. Remove-ServiceFabricApplication automatically removes all services that belong to the application as well, permanently removing all service state.

Remove-ServiceFabricApplication fabric:/MyApp

Confirm
Continue with this operation?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):
Remove application instance succeeded

Get-ServiceFabricApplication

Unregister an application type

When a particular version of an application type is no longer needed, you should unregister the application type using the Unregister-ServiceFabricApplicationType cmdlet. Unregistering unused application types releases storage space used by the image store by removing the application type files. Unregistering an application type does not remove the application package copied to the image store temporary location, if copy to the image store was used. An application type can be unregistered as long as no applications are instantiated against it and no pending application upgrades are referencing it.

Run Get-ServiceFabricApplicationType to see the application types currently registered in the cluster:

Get-ServiceFabricApplicationType

ApplicationTypeName    : MyApplicationType
ApplicationTypeVersion : 1.0.0
Status                 : Available
DefaultParameters      : { "Stateless1_InstanceCount" = "-1" }

Run Unregister-ServiceFabricApplicationType to unregister a specific application type:

Unregister-ServiceFabricApplicationType MyApplicationType 1.0.0

Troubleshooting

Copy-ServiceFabricApplicationPackage asks for an ImageStoreConnectionString

The Service Fabric SDK environment should already have the correct defaults set up. But if needed, the ImageStoreConnectionString for all commands should match the value that the Service Fabric cluster is using. You can find the ImageStoreConnectionString in the cluster manifest, retrieved using the Get-ServiceFabricClusterManifest and Get-ImageStoreConnectionStringFromClusterManifest commands:

Get-ImageStoreConnectionStringFromClusterManifest(Get-ServiceFabricClusterManifest)

The Get-ImageStoreConnectionStringFromClusterManifest cmdlet, which is part of the Service Fabric SDK PowerShell module, is used to get the image store connection string. To import the SDK module, run:

Import-Module "$ENV:ProgramFiles\Microsoft SDKs\Service Fabric\Tools\PSModule\ServiceFabricSDK\ServiceFabricSDK.psm1"

The ImageStoreConnectionString is found in the cluster manifest:

<ClusterManifest xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" Name="Server-Default-SingleNode" Version="1.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">

    [...]

    <Section Name="Management">
      <Parameter Name="ImageStoreConnectionString" Value="file:D:\ServiceFabric\Data\ImageStore" />
    </Section>

    [...]

See Understand the image store connection string for supplementary information about the image store and image store connection string.

Deploy large application package

Issue: Copy-ServiceFabricApplicationPackage times out for a large application package (order of GB). Try:

• Specify a larger timeout for Copy-ServiceFabricApplicationPackage command, with TimeoutSec parameter. By default, the timeout is 30 minutes.
• Check the network connection between your source machine and cluster. If the connection is slow, consider using a machine with a better network connection. If the client machine is in another region than the cluster, consider using a client machine in a closer or same region as the cluster.
• Check if you are hitting external throttling. For example, when the image store is configured to use azure storage, upload may be throttled.

Issue: Upload package completed successfully, but Register-ServiceFabricApplicationType times out. Try:

• Compress the package before copying to the image store. The compression reduces the size and the number of files, which in turn reduces the amount of traffic and work that Service Fabric must perform. The upload operation may be slower (especially if you include the compression time), but register and un-register the application type are faster.
• Specify a larger timeout for Register-ServiceFabricApplicationType with TimeoutSec parameter.
• Specify Async switch for Register-ServiceFabricApplicationType. The command returns when the cluster accepts the command and the registration of the application type continues asynchronously. For this reason, there is no need to specify a higher timeout in this case. The Get-ServiceFabricApplicationType command lists all successfully registered application type versions and their registration status. You can use this command to determine when the registration is done.

Get-ServiceFabricApplicationType

ApplicationTypeName    : MyApplicationType
ApplicationTypeVersion : 1.0.0
Status                 : Available
DefaultParameters      : { "Stateless1_InstanceCount" = "-1" }

Deploy application package with many files

Issue: Register-ServiceFabricApplicationType times out for an application package with many files (order of thousands). Try:

• Compress the package before copying to the image store. The compression reduces the number of files.
• Specify a larger timeout for Register-ServiceFabricApplicationType with TimeoutSec parameter.
• Specify Async switch for Register-ServiceFabricApplicationType. The command returns when the cluster accepts the command and the registration of the application type continues asynchronously. For this reason, there is no need to specify a higher timeout in this case. The Get-ServiceFabricApplicationType command lists all successfully registered application type versions and their registration status. You can use this command to determine when the registration is done.

Get-ServiceFabricApplicationType

ApplicationTypeName    : MyApplicationType
ApplicationTypeVersion : 1.0.0
Status                 : Available
DefaultParameters      : { "Stateless1_InstanceCount" = "-1" }

Next steps

Package an application

Service Fabric application upgrade

Service Fabric health introduction

Diagnose and troubleshoot a Service Fabric service

Model an application in Service Fabric