Implantar e remover aplicativos usando o PowerShell

  • Artigo

Depois que um tipo de aplicativo for empacotado, ele estará pronto para implantação em um cluster do Azure Service Fabric. A implantação envolve as três etapas a seguir:

  1. Carregue o pacote do aplicativo para o armazenamento de imagens.
  2. Registre o tipo de aplicativo com o caminho relativo do armazenamento de imagens.
  3. Crie a instância do aplicativo.

Quando o aplicativo implantado não for mais necessário, você poderá excluir a instância do aplicativo e seu tipo de aplicativo. Para remover completamente um aplicativo do cluster envolve as seguintes etapas:

  1. Remova (ou exclua) a instância do aplicativo em execução.
  2. Cancele o registro do tipo de aplicativo se não precisar mais dele.
  3. Remova o pacote do aplicativo do armazenamento de imagens.

Se você usar o Visual Studio para implantar e depurar aplicativos em seu cluster de desenvolvimento local, todas as etapas anteriores serão tratadas automaticamente por meio de um script do PowerShell. Esse script é encontrado na pasta Scripts do projeto de aplicativo. Este artigo fornece informações básicas sobre o que esse script está fazendo para que você possa executar as mesmas operações fora do Visual Studio.

Outra maneira de implantar um aplicativo é usando o provisionamento externo. O pacote do aplicativo pode ser empacotado como sfpkg e carregado em uma loja externa. Neste caso, o upload para a loja de imagens não é necessário. A implantação precisa das seguintes etapas:

  1. Carregue o sfpkg para uma loja externa. O armazenamento externo pode ser qualquer armazenamento que exponha um ponto de extremidade REST http ou https.
  2. Registre o tipo de aplicativo usando o URI de download externo e as informações de tipo de aplicativo.
  3. Crie a instância do aplicativo.

Para limpeza, remova as instâncias do aplicativo e cancele o registro do tipo de aplicativo. Como o pacote não foi copiado para o armazenamento de imagens, não há nenhum local temporário para limpeza. O provisionamento do repositório externo está disponível a partir do Service Fabric versão 6.1.

Nota

Visual Studio atualmente não oferece suporte a provisionamento externo.

Ligar ao cluster

Antes de executar qualquer comando do PowerShell neste artigo, sempre comece usando Connect-ServiceFabricCluster para se conectar ao cluster do Service Fabric. Para se conectar ao cluster de desenvolvimento local, execute o seguinte:

Connect-ServiceFabricCluster

Para obter exemplos de conexão a um cluster remoto ou cluster protegido usando o Microsoft Entra ID, certificados X509 ou Windows Ative Directory, consulte Conectar-se a um cluster seguro.

Carregue o pacote de candidatura

O carregamento do pacote de aplicativos o coloca em um local acessível por componentes internos do Service Fabric. Se quiser verificar o pacote do aplicativo localmente, use o cmdlet Test-ServiceFabricApplicationPackage .

O comando Copy-ServiceFabricApplicationPackage carrega o pacote do aplicativo no repositório de imagens do cluster.

Suponha que você crie e empacote um aplicativo chamado MyApplication no Visual Studio 2015. Por padrão, o nome do tipo de aplicativo listado no ApplicationManifest.xml é "MyApplicationType". O pacote do aplicativo, que contém o manifesto do aplicativo necessário, manifestos de serviço e pacotes de código/config/dados, está localizado em C:\Users<username>\Documents\Visual Studio 2015\Projects\MyApplication\MyApplication\pkg\Debug.

O comando a seguir lista o conteúdo do pacote do aplicativo:

$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

Se o pacote do aplicativo for grande e/ou tiver muitos arquivos, você poderá compactá-lo. A compactação reduz o tamanho e o número de arquivos. Isso resulta em um registro mais rápido e cancelamento do registro do tipo de aplicativo. O tempo de upload pode ser mais lento atualmente, especialmente se você incluir o tempo para compactar o pacote.

Para compactar um pacote, use o mesmo comando Copy-ServiceFabricApplicationPackage . A compressão pode ser feita separadamente do upload, usando o SkipCopy sinalizador ou juntamente com a operação de upload. A aplicação de compactação em um pacote compactado é no-op. Para descompactar um pacote compactado, use o mesmo comando Copy-ServiceFabricApplicationPackage com o UncompressPackage switch.

O cmdlet a seguir compacta o pacote sem copiá-lo para o armazenamento de imagens. O pacote agora inclui arquivos compactados para os Code e Config pacotes. Os manifestos do aplicativo e do serviço não são compactados, porque são necessários para muitas operações internas (como compartilhamento de pacotes, nome do tipo de aplicativo e extração de versão para determinadas validações). Compactar os manifestos tornaria essas operações ineficientes.

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

Para pacotes de aplicativos grandes, a compactação leva tempo. Para obter melhores resultados, utilize uma unidade SSD rápida. Os tempos de compressão e o tamanho do pacote compactado também diferem com base no conteúdo do pacote. Por exemplo, aqui estão as estatísticas de compressão para alguns pacotes, que mostram o tamanho inicial e o tamanho do pacote compactado, com o tempo de compactação.

Tamanho inicial (MB) Contagem de ficheiros Tempo de compressão Tamanho da embalagem compactada (MB)
100 100 00:00:03.3547592 60
512 100 00:00:16.3850303 307
1024 500 00:00:32.5907950 615
2048 1000 00:01:04.3775554 1231
5012 100 00:02:45.2951288 3074

Depois que um pacote é compactado, ele pode ser carregado em um ou vários clusters do Service Fabric, conforme necessário. O mecanismo de implantação é o mesmo para pacotes compactados e não compactados. Os pacotes compactados são armazenados como tal no armazenamento de imagens do cluster. Os pacotes são descompactados no nó, antes que o aplicativo seja executado.

O exemplo a seguir carrega o pacote para o armazenamento de imagens, em uma pasta chamada "MyApplicationV1":

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

Se você não especificar o parâmetro -ApplicationPackagePathInImageStore, o pacote do aplicativo será copiado para a pasta "Debug" no armazenamento de imagens.

Nota

O Copy-ServiceFabricApplicationPackage detetará automaticamente a cadeia de conexão de armazenamento de imagens apropriada se a sessão do PowerShell estiver conectada a um cluster do Service Fabric. Para versões do Service Fabric anteriores à 5.6, o argumento -ImageStoreConnectionString deve ser fornecido explicitamente.

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

O cmdlet Get-ImageStoreConnectionStringFromClusterManifest , que faz parte do módulo PowerShell do SDK do Service Fabric, é usado para obter a cadeia de conexão do armazenamento de imagens. Para importar o módulo SDK, execute:

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

Consulte Compreender a cadeia de conexão do armazenamento de imagens para obter informações complementares sobre o armazenamento de imagens e a cadeia de conexão do armazenamento de imagens.

O tempo que leva para carregar um pacote difere dependendo de vários fatores. Alguns desses fatores são o número de arquivos no pacote, o tamanho do pacote e os tamanhos dos arquivos. A velocidade da rede entre a máquina de origem e o cluster do Service Fabric também afeta o tempo de carregamento. O tempo limite padrão para Copy-ServiceFabricApplicationPackage é de 30 minutos. Dependendo dos fatores descritos, você pode ter que aumentar o tempo limite. Se você estiver compactando o pacote na chamada de cópia, você também precisa considerar o tempo de compactação.

Registar o pacote de candidaturas

O tipo e a versão do aplicativo declarados no manifesto do aplicativo ficam disponíveis para uso quando o pacote do aplicativo é registrado. O sistema lê o pacote carregado na etapa anterior, verifica o pacote, processa o conteúdo do pacote e copia o pacote processado para um local interno do sistema.

Execute o cmdlet Register-ServiceFabricApplicationType para registrar o tipo de aplicativo no cluster e disponibilizá-lo para implantação:

Registrar o pacote do aplicativo copiado para o armazenamento de imagens

Quando um pacote foi copiado anteriormente para o armazenamento de imagens, a operação de registro especifica o caminho relativo no armazenamento de imagens.

Register-ServiceFabricApplicationType -ApplicationPathInImageStore MyApplicationV1

Register application type succeeded

"MyApplicationV1" é a pasta no armazenamento de imagens onde o pacote do aplicativo está localizado. O tipo de aplicativo com nome "MyApplicationType" e versão "1.0.0" (ambos são encontrados no manifesto do aplicativo) agora está registrado no cluster.

Registrar o pacote do aplicativo copiado para um armazenamento externo

A partir da versão 6.1 do Service Fabric, a provisão oferece suporte ao download do pacote de um repositório externo. O URI de download representa o caminho para o pacote do aplicativo de onde o sfpkg pacote do aplicativo pode ser baixado usando protocolos HTTP ou HTTPS. O pacote deve ter sido previamente carregado para este local externo. O URI deve permitir o acesso READ para que o Service Fabric possa baixar o arquivo. O sfpkg arquivo deve ter a extensão ".sfpkg". A operação de fornecimento deve incluir as informações sobre o tipo de aplicação, tal como constam do manifesto da aplicação.

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

O comando Register-ServiceFabricApplicationType retorna somente depois que o sistema registrou com êxito o pacote do aplicativo. O tempo de registo depende da dimensão e do conteúdo do pacote de candidaturas. Se necessário, o parâmetro -TimeoutSec pode ser usado para fornecer um tempo limite maior (o tempo limite padrão é de 60 segundos).

Se você tiver um pacote de aplicativo grande ou se estiver enfrentando tempos limites, use o parâmetro -Async . O comando retorna quando o cluster aceita o comando register. A operação de registo continua conforme necessário. O comando Get-ServiceFabricApplicationType lista as versões de tipo de aplicativo e seu status de registro. Você pode usar esse comando para determinar quando o registro é concluído.

Get-ServiceFabricApplicationType

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

Remover um pacote de aplicativo do armazenamento de imagens

Se um pacote foi copiado para o armazenamento de imagens, você deve removê-lo do local temporário depois que o aplicativo for registrado com êxito. A exclusão de pacotes de aplicativos do armazenamento de imagens libera recursos do sistema. Manter pacotes de aplicativos não utilizados consome armazenamento em disco e leva a problemas de desempenho do aplicativo.

Remove-ServiceFabricApplicationPackage -ApplicationPackagePathInImageStore MyApplicationV1

Criar a aplicação

Você pode instanciar um aplicativo de qualquer versão de tipo de aplicativo que tenha sido registrada com êxito usando o cmdlet New-ServiceFabricApplication . O nome de cada aplicativo deve começar com o esquema "fabric:" e deve ser exclusivo para cada instância do aplicativo. Todos os serviços padrão definidos no manifesto do aplicativo do tipo de aplicativo de destino também são criados.

New-ServiceFabricApplication fabric:/MyApp MyApplicationType 1.0.0

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

Várias instâncias de aplicativo podem ser criadas para qualquer versão de um tipo de aplicativo registrado. Cada instância de aplicativo é executada isoladamente, com seu próprio diretório de trabalho e processo.

Para ver quais aplicativos e serviços nomeados estão sendo executados no cluster, execute os cmdlets Get-ServiceFabricApplication e 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

Remover uma aplicação

Quando uma instância de aplicativo não é mais necessária, você pode removê-la permanentemente pelo nome usando o cmdlet Remove-ServiceFabricApplication . Remove-ServiceFabricApplication remove automaticamente todos os serviços que pertencem ao aplicativo também, removendo permanentemente todo o estado do serviço.

Aviso

Essa operação não pode ser revertida e o estado do aplicativo não pode ser recuperado.

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

Cancelar o registro de um tipo de aplicativo

Quando uma versão específica de um tipo de aplicativo não for mais necessária, você deverá cancelar o registro do tipo de aplicativo usando o cmdlet Unregister-ServiceFabricApplicationType . Cancelar o registro de tipos de aplicativos não utilizados libera espaço de armazenamento usado pelo armazenamento de imagens removendo os arquivos de tipo de aplicativo. Cancelar o registro de um tipo de aplicativo não remove o pacote de aplicativo copiado para o local temporário do armazenamento de imagens, se a cópia para o armazenamento de imagens tiver sido usada. Um tipo de aplicativo pode ser cancelado, desde que nenhum aplicativo seja instanciado em relação a ele e nenhuma atualização pendente de aplicativo esteja fazendo referência a ele.

Execute Get-ServiceFabricApplicationType para ver os tipos de aplicativo atualmente registrados no cluster:

Get-ServiceFabricApplicationType

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

Execute Unregister-ServiceFabricApplicationType para cancelar o registro de um tipo de aplicativo específico:

Unregister-ServiceFabricApplicationType MyApplicationType 1.0.0

Resolução de problemas

Copy-ServiceFabricApplicationPackage solicita um ImageStoreConnectionString

O ambiente do SDK do Service Fabric já deve ter os padrões corretos configurados. Mas, se necessário, o ImageStoreConnectionString para todos os comandos deve corresponder ao valor que o cluster do Service Fabric está usando. Você pode encontrar o ImageStoreConnectionString no manifesto do cluster, recuperado usando os comandos Get-ServiceFabricClusterManifest e Get-ImageStoreConnectionStringFromClusterManifest:

Get-ImageStoreConnectionStringFromClusterManifest(Get-ServiceFabricClusterManifest)

O cmdlet Get-ImageStoreConnectionStringFromClusterManifest , que faz parte do módulo PowerShell do SDK do Service Fabric, é usado para obter a cadeia de conexão do armazenamento de imagens. Para importar o módulo SDK, execute:

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

O ImageStoreConnectionString é encontrado no manifesto do 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>

    [...]

Consulte Compreender a cadeia de conexão do armazenamento de imagens para obter informações complementares sobre o armazenamento de imagens e a cadeia de conexão do armazenamento de imagens.

Implantar pacote de aplicativos grande

Problema: o tempo limite do Copy-ServiceFabricApplicationPackage para um pacote de aplicativo grande (ordem de GB). Experimente:

  • Especifique um tempo limite maior para o comando Copy-ServiceFabricApplicationPackage , com TimeoutSec parâmetro. Por padrão, o tempo limite é de 30 minutos.
  • Verifique a conexão de rede entre a máquina de origem e o cluster. Se a conexão for lenta, considere usar uma máquina com uma conexão de rede melhor. Se a máquina cliente estiver em outra região que não o cluster, considere usar uma máquina cliente em uma região mais próxima ou igual à do cluster.
  • Verifique se você está atingindo a limitação externa. Por exemplo, quando o armazenamento de imagens está configurado para usar o armazenamento azure, o carregamento pode ser limitado.

Problema: o pacote de carregamento foi concluído com êxito, mas o tempo limite de Register-ServiceFabricApplicationType expira. Experimente:

  • Comprima o pacote antes de copiar para o armazenamento de imagens. A compactação reduz o tamanho e o número de arquivos, o que, por sua vez, reduz a quantidade de tráfego e trabalho que o Service Fabric deve executar. A operação de upload pode ser mais lenta (especialmente se você incluir o tempo de compactação), mas registrar e cancelar o registro do tipo de aplicativo são mais rápidos.
  • Especifique um tempo limite maior para Register-ServiceFabricApplicationType com TimeoutSec parâmetro.
  • Especifique Async a opção para Register-ServiceFabricApplicationType. O comando retorna quando o cluster aceita o comando e o registro do tipo de aplicativo continua de forma assíncrona. Por esse motivo, não há necessidade de especificar um tempo limite maior neste caso. O comando Get-ServiceFabricApplicationType lista todas as versões de tipo de aplicativo registradas com êxito e seu status de registro. Você pode usar esse comando para determinar quando o registro é concluído.
Get-ServiceFabricApplicationType

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

Implante o pacote de aplicativos com muitos arquivos

Problema: o tempo limite de Register-ServiceFabricApplicationType para um pacote de aplicativo com muitos arquivos (ordem de milhares). Experimente:

  • Comprima o pacote antes de copiar para o armazenamento de imagens. A compressão reduz o número de ficheiros.
  • Especifique um tempo limite maior para Register-ServiceFabricApplicationType com TimeoutSec parâmetro.
  • Especifique Async a opção para Register-ServiceFabricApplicationType. O comando retorna quando o cluster aceita o comando e o registro do tipo de aplicativo continua de forma assíncrona. Por esse motivo, não há necessidade de especificar um tempo limite maior neste caso. O comando Get-ServiceFabricApplicationType lista todas as versões de tipo de aplicativo registradas com êxito e seu status de registro. Você pode usar esse comando para determinar quando o registro é concluído.
Get-ServiceFabricApplicationType

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

Próximos passos

Criar pacote de uma aplicação

Atualização do aplicativo Service Fabric

Introdução à integridade do Service Fabric

Diagnosticar e solucionar problemas de um serviço do Service Fabric

Modelar um aplicativo no Service Fabric