Déployer et supprimer des applications avec PowerShell

Article
10/15/2024

Après avoir packagé un type d’application, il peut être déployé sur un cluster Azure Service Fabric. Le déploiement implique les trois étapes suivantes :

Charger le package d’application dans le magasin d’images.
Inscrire le type d’application avec le chemin d’accès relatif du magasin d’images.
Créer l’instance d’application.

Une fois déployée, l’application n’est plus nécessaire, vous pouvez supprimer l’instance d’application et son type d’application. La suppression complète d’une application du cluster implique les étapes suivantes :

Supprimer l’instance d’application en cours d’exécution.
Désinscrire le type d’application si vous n’en avez plus besoin.
Supprimer le package d’application du magasin d’images.

Si vous utilisez Visual Studio pour déployer et déboguer des applications dans votre cluster de développement local, toutes les étapes précédentes sont gérées automatiquement à l’aide d’un script PowerShell. Ce script se trouve dans le dossier Scripts du projet d’application. Cet article fournit des précisions sur les actions de ce script afin que vous puissiez effectuer les mêmes opérations en dehors de Visual Studio.

Une autre façon de déployer une application consiste à utiliser un approvisionnement externe. Le package d’application peut être conditionné en tant que sfpkg et chargé dans un magasin externe. Dans ce cas, le chargement dans le magasin d’images n’est pas nécessaire. Le déploiement nécessite les étapes suivantes :

Charger le sfpkg dans un magasin externe. Le magasin externe peut être n’importe quel magasin qui expose un point de terminaison HTTP ou HTTPS REST.
Inscrire le type d’application à l’aide de l’URI de téléchargement externe et les informations sur le type d’application.
Créer l’instance d’application.

Pour le nettoyage, supprimez les instances de l’application et annulez l’inscription du type d’application. Le package n’ayant pas été copié dans le magasin d’images, il n’existe aucun emplacement temporaire à nettoyer. L’approvisionnement à partir d’un magasin externe est possible avec Service Fabric version 6.1.

Notes

Visual Studio ne prend actuellement pas en charge l’approvisionnement externe.

Se connecter au cluster

Avant d’exécuter des commandes PowerShell dans le cadre de cet article, commencez toujours par vous connecter au cluster Service Fabric à l’aide de la commande Connect-ServiceFabricCluster. Pour vous connecter au cluster de développement local, exécutez la commande suivante :

Connect-ServiceFabricCluster

Pour obtenir des exemples de connexion à un cluster distant ou à un cluster sécurisé à l’aide de Microsoft Entra ID, de certificats X509 ou de Windows Active Directory, consultez Se connecter à un cluster sécurisé.

Télécharger le package d'application

Quand vous chargez le package d’application, celui-ci est placé dans un dossier accessible aux composants internes de Service Fabric. Si vous souhaitez vérifier le package d’application en local, utilisez l’applet de commande Test-ServiceFabricApplicationPackage.

La commande Copy-ServiceFabricApplicationPackage charge le package d’application dans le magasin d’images du cluster.

Supposons que vous génériez une application nommée MyApplication et que vous créiez un package pour cette application dans Visual Studio 2015. Par défaut, le nom du type application répertorié dans le fichier ApplicationManifest.xml est « MyApplicationType ». Le package d’application, qui contient le manifeste de l’application, les manifestes de service et les packages de code / configuration / données requis, se trouve sous C:\Users<username>\Documents\Visual Studio 2015\Projects\MyApplication\MyApplication\pkg\Debug.

La commande suivante répertorie le contenu du package d’application :

$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

Si le package d’application est volumineux ou contient de nombreux fichiers, vous pouvez le compresser. La compression réduit la taille et le nombre de fichiers. Cela permet d’accélérer l’inscription et la désinscription du type d’application. Actuellement, le chargement peut demander plus de temps, notamment si vous incluez le temps nécessaire à la compression du package.

Pour compresser un package, utilisez la même commande Copy-ServiceFabricApplicationPackage. La compression peut être effectuée indépendamment du chargement, en utilisant l’indicateur SkipCopy, ou conjointement avec l’opération de chargement. L’application d’une compression sur un package compressé n’a aucun effet. Pour décompresser un package compressé, utilisez la même commande Copy-ServiceFabricApplicationPackage avec le commutateur UncompressPackage.

L’applet de commande suivante permet de compresser le package sans le copier dans le magasin d’images. Le package inclut désormais les fichiers compressés pour les packages Code et Config. Les manifestes de l’application et de service ne sont pas compressés, car ils sont requis pour de nombreuses opérations internes (comme le partage de package ou l’extraction du nom du type de l’application et de la version pour certaines validations). La compression des manifestes rendrait ces opérations inefficaces.

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

Pour les packages d’application volumineux, la compression demande un certain temps. Pour obtenir de meilleurs résultats, utilisez un disque SSD rapide. Le temps de compression et la taille du package compressé varient également selon le contenu du package. Par exemple, voici les statistiques de compression pour certains packages, qui indiquent la taille initiale et la taille du package compressé, avec le temps de compression.

Taille initiale (Mo)	Nombre de fichiers	Temps de compression	Taille du package compressé (Mo)
100	100	00:00:03.3547592	60
512	100	00:00:16.3850303	307
1 024	500	00:00:32.5907950	615
2 048	1 000	00:01:04.3775554	1231
5012	100	00:02:45.2951288	3074

Une fois qu’un package est compressé, il peut être chargé dans un ou plusieurs clusters Service Fabric suivant les besoins. Le mécanisme de déploiement est le même pour les packages compressés et non compressés. Les packages compressés sont stockés tels quels dans le magasin d’images du cluster. Les packages sont décompressées sur le nœud, avant l’exécution de l’application.

L’exemple suivant charge le package dans le magasin d’images, dans un dossier nommé « MyApplicationV1 » :

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

Si vous ne spécifiez pas le paramètre -ApplicationPackagePathInImageStore, le package d’application est copié dans le dossier « Debug » du magasin d’images.

Notes

Copy-ServiceFabricApplicationPackage détecte automatiquement la chaîne de connexion du magasin d’images appropriée si la session PowerShell est connectée à un cluster Service Fabric. Pour les versions de Service Fabric antérieures à la version 5.6, l’argument -ImageStoreConnectionString doit être fourni explicitement.

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

L’applet de commande Get-ImageStoreConnectionStringFromClusterManifest , qui fait partie du module PowerShell du SDK de Service Fabric, sert à obtenir la chaîne de connexion au magasin d’images. Pour importer le module du kit SDK, exécutez :

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

Pour plus d’informations sur le magasin d’images et sur ImageStoreConnectionString, consultez la page Comprendre la chaîne de connexion du magasin d’images.

Le temps nécessaire pour charger un package varie selon plusieurs facteurs : nombre de fichiers dans le package, taille du package, taille des fichiers, etc. La vitesse de la connexion réseau entre l’ordinateur source et le cluster Service Fabric a également un impact sur le temps de chargement. Le délai d’expiration par défaut pour la commande Copy-ServiceFabricApplicationPackage est de 30 minutes. En fonction des facteurs décrits, il se peut que vous deviez augmenter ce délai. Si vous compressez le package dans l’appel de copie, vous devez également prendre en compte le temps de compression.

Enregistrer le package d'application

Le type et la version de l’application déclarés dans le manifeste de l’application deviennent utilisables à l’inscription du package d’application. Le système lit le package chargé à l’étape précédente, vérifie le package, traite le contenu du package et copie le package traité dans un emplacement système interne.

Exécutez l’applet de commande Register-ServiceFabricApplicationType pour inscrire le type d’application dans le cluster et le rendre disponible pour le déploiement :

Inscrire le package d’application copié dans le magasin d’images

Lorsqu’un package a précédemment été copié dans le magasin d’images, l’opération d’inscription spécifie le chemin d’accès relatif dans le magasin d’images.

Register-ServiceFabricApplicationType -ApplicationPathInImageStore MyApplicationV1

Register application type succeeded

« MyApplicationV1 » est le dossier du magasin d’images qui contient le package d’application. Le type d’application présentant le nom « MyApplicationType » et la version « 1.0.0 » (ces deux valeurs se trouvent dans le manifeste de l’application) est à présent inscrit dans le cluster.

Inscrire le package d’application copié dans un magasin externe

Depuis Service Fabric version 6.1, l’approvisionnement prend en charge le téléchargement du package à partir d’un magasin externe. L’URI de téléchargement représente le chemin d’accès au sfpkgpackage d’application à partir duquel le package d’application peut être téléchargé à l’aide des protocoles HTTP ou HTTPS. Le package doit avoir été précédemment chargé dans cet emplacement externe. L’URI doit autoriser un accès en lecture pour que Service Fabric puisse télécharger le fichier. Le fichier sfpkg doit avoir l’extension « .sfpkg ». L’opération d’approvisionnement doit inclure les informations sur le type d’application, telles que trouvées dans le manifeste de l’application.

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

La commande Register-ServiceFabricApplicationType ne renvoie un résultat que lorsque le package d’application a été correctement inscrit par le système. La durée de l’enregistrement dépend de la taille et du contenu du package de l’application. Si nécessaire, le paramètre -TimeoutSec peut être utilisé pour fournir un délai d’expiration plus long (le délai d’expiration par défaut est de 60 secondes).

Si vous disposez d’un package d’application volumineux et que vous rencontrez des problèmes d’expiration du délai, utilisez le paramètre -Async. La commande s’exécute lorsque le cluster accepte la commande d’inscription. L’opération d’inscription se poursuit suivant les besoins. La commande Get-ServiceFabricApplicationType répertorie toutes les versions de types d’applications et l’état de leur inscription. Vous pouvez utiliser cette commande pour déterminer quand l’inscription est effectuée.

Get-ServiceFabricApplicationType

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

Supprimer un package d’application du magasin d’images

Si un package a été copié dans le magasin d’images, vous devez le supprimer de l’emplacement temporaire une fois l’application inscrite avec succès. La suppression de packages d’application du magasin d’images libère des ressources système. La conservation des packages d’application inutilisés consomme du stockage sur disque et affecte le niveau de performance des applications.

Remove-ServiceFabricApplicationPackage -ApplicationPackagePathInImageStore MyApplicationV1

Création de l'application

Vous pouvez instancier une application à partir de n’importe quelle version de type d’application correctement inscrite à l’aide de l’applet de commande New-ServiceFabricApplication. Le nom de chaque application doit commencer par le schéma « fabric: » et être unique pour chaque instance d’application. Les éventuels services par défaut définis dans le manifeste de l’application du type de l’application cible sont également créés.

New-ServiceFabricApplication fabric:/MyApp MyApplicationType 1.0.0

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

Plusieurs instances d'application peuvent être créées pour une version donnée d'un type d'application enregistré. Chaque instance de l’application s’exécute en isolement, avec ses propres répertoire de travail et processus.

Pour connaître les applications et services nommés en cours d’exécution dans le cluster, exécutez les applets de commande Get-ServiceFabricApplication et Get-ServiceFabricService :

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

Supprimer une application

Lorsque vous n’avez plus besoin d’une instance d’application, vous pouvez la supprimer définitivement à l’aide de son nom en utilisant l’applet de commande Remove-ServiceFabricApplication. Remove-ServiceFabricApplication supprime également automatiquement tous les services qui appartiennent à l’application, supprimant ainsi définitivement tous les états de service.

Avertissement

Cette opération ne peut pas être annulée et l’état de l’application ne peut pas être récupéré.

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

Désinscrire un type d’application

Lorsque vous n’avez plus besoin d’un type d’application, il est recommandé de le désinscrire à l’aide de l’applet de commande Unregister-ServiceFabricApplicationType. La désinscription des types d’applications inutilisés libère l’espace de stockage utilisé par le magasin d’images par la suppression les fichiers de type d’application. La désinscription d’un type d’application ne supprime pas le package d’application copié dans l’emplacement temporaire du magasin d’image si la copie dans le magasin d’images a été utilisée. Vous pouvez désinscrire un type d’application s’il ne contient aucune instance d’application et s’il n’est référencé par aucune mise à niveau d’application en attente.

Pour afficher les types d’applications actuellement inscrits dans le cluster, exécutez Get-ServiceFabricApplicationType :

Get-ServiceFabricApplicationType

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

Pour désinscrire un type d’application spécifique, exécutez Unregister-ServiceFabricApplicationType :

Unregister-ServiceFabricApplicationType MyApplicationType 1.0.0

Dépannage

Copy-ServiceFabricApplicationPackage demande un ImageStoreConnectionString

L'environnement du SDK Service Fabric doit déjà être configuré avec les valeurs par défaut correctes. Toutefois, si besoin, l’ImageStoreConnectionString de toutes les commandes doit correspondre à celui utilisé par le cluster Service Fabric. ImageStoreConnectionString se trouve dans le manifeste de cluster récupéré à l’aide des commandes Get-ServiceFabricClusterManifest et Get-ImageStoreConnectionStringFromClusterManifest :

Get-ImageStoreConnectionStringFromClusterManifest(Get-ServiceFabricClusterManifest)

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

ImageStoreConnectionString se trouve dans le manifeste de cluster :

<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>

    [...]

Pour plus d’informations sur le magasin d’images et sur ImageStoreConnectionString, consultez la page Comprendre la chaîne de connexion du magasin d’images.

Déployer un package d’application volumineux

Problème : la commande Copy-ServiceFabricApplicationPackage expire pour un package d’application volumineux (de l’ordre du gigaoctet). Essayez de procéder comme suit :

Spécifiez un délai d’expiration supérieur pour la commandeCopy-ServiceFabricApplicationPackage avec le paramètre TimeoutSec. Par défaut, le délai d’expiration est de 30 minutes.
Vérifiez la connexion réseau entre votre ordinateur source et le cluster. Si la connexion est lente, envisagez d’utiliser un ordinateur offrant une meilleure connexion réseau. Si l’ordinateur client se trouve dans une autre région que le cluster, envisagez d’utiliser un ordinateur client se trouvant dans la région du cluster ou dans une région plus proche de celle-ci.
Vérifiez si vous êtes confronté à des limitations externes. Par exemple, lorsque le magasin d’images est configuré pour utiliser le stockage Azure, le chargement peut être limité.

Problème : le chargement du package s’est terminé avec succès, mais la commande Register-ServiceFabricApplicationType expire. Essayez de procéder comme suit :

Compressez le package avant de le copier dans le magasin d’images. La compression réduit la taille et le nombre de fichiers, ce qui a pour effet de réduire la quantité de trafic et la charge de travail pour Service Fabric. L’opération de chargement peut demander plus de temps (surtout si vous incluez le temps de compression), mais l’inscription et la désinscription du type d’application sont plus rapides.
Spécifiez un délai d’expiration supérieur pour la commandeRegister-ServiceFabricApplicationType avec le paramètre TimeoutSec.
Spécifiez le commutateur Async pour la commande Register-ServiceFabricApplicationType. La commande procède au renvoi lorsque le cluster accepte la commande et l’inscription du type d’application se poursuit de façon asynchrone. Par conséquent, il est inutile de spécifier un délai d’expiration plus élevé dans ce cas. La commande Get-ServiceFabricApplicationType répertorie toutes les versions de types d’applications correctement inscrites et l’état de leur inscription. Vous pouvez utiliser cette commande pour déterminer quand l’inscription est effectuée.

Get-ServiceFabricApplicationType

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

Déployer un package d’application contenant de nombreux fichiers

Problème : la commande Register-ServiceFabricApplicationType expire pour un package d’application contenant un grand nombre de fichiers (de l’ordre de plusieurs milliers). Essayez de procéder comme suit :

Compressez le package avant de le copier dans le magasin d’images. La compression réduit le nombre de fichiers.
Spécifiez un délai d’expiration supérieur pour la commandeRegister-ServiceFabricApplicationType avec le paramètre TimeoutSec.
Spécifiez le commutateur Async pour la commande Register-ServiceFabricApplicationType. La commande procède au renvoi lorsque le cluster accepte la commande et l’inscription du type d’application se poursuit de façon asynchrone. Par conséquent, il est inutile de spécifier un délai d’expiration plus élevé dans ce cas. La commande Get-ServiceFabricApplicationType répertorie toutes les versions de types d’applications correctement inscrites et l’état de leur inscription. Vous pouvez utiliser cette commande pour déterminer quand l’inscription est effectuée.

Get-ServiceFabricApplicationType

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