アプリケーションをパッケージ化するPackage an application

この記事では、Service Fabric アプリケーションをパッケージ化し、デプロイの準備をする方法について説明します。This article describes how to package a Service Fabric application and make it ready for deployment.

パッケージのレイアウトPackage layout

アプリケーション マニフェスト、1 つまたは複数のサービス マニフェスト、その他の必要なパッケージ ファイルをデプロイ用の特定のレイアウトで Service Fabric クラスターにまとめる必要があります。The application manifest, one or more service manifests, and other necessary package files must be organized in a specific layout for deployment into a Service Fabric cluster. この記事のマニフェスト例は、次のディレクトリ構造でまとめる必要があります。The example manifests in this article would need to be organized in the following directory structure:

tree /f .\MyApplicationType
D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat

フォルダーには、それぞれの対応する要素の Name 属性と一致する名前が付けられます。The folders are named to match the Name attributes of each corresponding element. たとえば、MyCodeAMyCodeB という名前の付いた 2 つのコード パッケージがサービス マニフェストに含まれている場合、各コード パッケージと同じ名前のフォルダーにそれぞれのコード パッケージに必要なバイナリが含まれます。For example, if the service manifest contained two code packages with the names MyCodeA and MyCodeB, then two folders with the same names would contain the necessary binaries for each code package.

SetupEntryPoint の使用Use SetupEntryPoint

SetupEntryPoint を使用する際の一般的なシナリオは、サービス開始前に実行可能ファイルを実行する必要がある場合や、昇格した特権で操作を実行する必要がある場合になります。Typical scenarios for using SetupEntryPoint are when you need to run an executable before the service starts or you need to perform an operation with elevated privileges. 次に例を示します。For example:

  • サービス実行可能ファイルが使用する可能性がある環境変数の設定と初期化などです。Setting up and initializing environment variables that the service executable needs. これは、Service Fabric のプログラミング モデルによって記述された実行可能ファイルだけに限定されません。It is not limited to only executables written via the Service Fabric programming models. たとえば、npm.exe は node.js アプリケーションのデプロイに構成されているいくつかの環境変数が必要です。For example, npm.exe needs some environment variables configured for deploying a node.js application.
  • セキュリティ証明書のインストールによるアクセス制御の設定Setting up access control by installing security certificates.

SetupEntryPoint の構成方法について詳しくは、エントリ ポイント セットアップ サービスのポリシーの構成に関するページをご覧くださいFor more information on how to configure the SetupEntryPoint, see Configure the policy for a service setup entry point

[構成]Configure

Visual Studio を使用したパッケージ構築Build a package by using Visual Studio

Visual Studio 2015 を使用して、アプリケーションを作成する場合、パッケージのコマンドを使用して、前述のレイアウトと一致するパッケージを自動的に作成できます。If you use Visual Studio 2015 to create your application, you can use the Package command to automatically create a package that matches the layout described above.

パッケージを作成するには、次のように、ソリューション エクスプローラーでアプリケーション プロジェクトを右クリックして [パッケージ] コマンドを選択します。To create a package, right-click the application project in Solution Explorer and choose the Package command, as shown below:

Visual Studio でアプリケーションをパッケージングする

パッケージ化が完了したら、 [出力] ウィンドウにパッケージの場所が表示されます。When packaging is complete, you can find the location of the package in the Output window. アプリケーションを Visual Studio でデプロイまたはデバッグする場合、パッケージ化の手順は自動で行われます。The packaging step occurs automatically when you deploy or debug your application in Visual Studio.

コマンド ラインを使用したパッケージ構築Build a package by command line

msbuild.exe を使用して、アプリケーションをプログラムによってパッケージ化することもできます。It is also possible to programmatically package up your application using msbuild.exe. これは内部的には Visual Studio で実行されているため、出力は同じです。Under the hood, Visual Studio is running it so the output is same.

D:\Temp> msbuild HelloWorld.sfproj /t:Package

パッケージのテストTest the package

パッケージ構造を PowerShell の Test-ServiceFabricApplicationPackage コマンドを使用して、ローカルで検証することができます。You can verify the package structure locally through PowerShell by using the Test-ServiceFabricApplicationPackage command. このコマンドは、マニフェストの解析の問題をチェックし、すべての参照を検証します。This command checks for manifest parsing issues and verify all references. このコマンドは、パッケージ内のディレクトリとファイルの構造的な正確性を検証するだけです。This command only verifies the structural correctness of the directories and files in the package. コードやデータ パッケージのコンテンツのいずれについても検証は行われず、それらがすべてそろっているかどうかは確認されません。It doesn't verify any of the code or data package contents beyond checking that all necessary files are present.

Test-ServiceFabricApplicationPackage .\MyApplicationType
False
Test-ServiceFabricApplicationPackage : The EntryPoint MySetup.bat is not found.
FileName: C:\Users\servicefabric\AppData\Local\Temp\TestApplicationPackage_7195781181\nrri205a.e2h\MyApplicationType\MyServiceManifest\ServiceManifest.xml

このエラーは、 SetupEntryPoint サービス マニフェストで参照される MySetup.bat ファイルがコード パッケージに見つからないことを示しています。This error shows that the MySetup.bat file referenced in the service manifest SetupEntryPoint is missing from the code package. 不足しているファイルを追加すると、アプリケーションの検証に合格します。After the missing file is added, the application verification passes:

tree /f .\MyApplicationType
D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │       MySetup.bat
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat
Test-ServiceFabricApplicationPackage .\MyApplicationType
True

アプリケーションでアプリケーション パラメーターが定義されている場合、それらのパラメーターを Test-ServiceFabricApplicationPackage に渡して適切に検証できます。If your application has application parameters defined, you can pass them in Test-ServiceFabricApplicationPackage for proper validation.

アプリケーションがデプロイされるクラスターが明らかな場合は、ImageStoreConnectionString パラメーターを渡すことをお勧めします。If you know the cluster where the application will be deployed, it is recommended you pass in the ImageStoreConnectionString parameter. この場合、パッケージは、既にクラスターで実行されている以前のバージョンのアプリケーションに対しても検証されます。In this case, the package is also validated against previous versions of the application that are already running in the cluster. たとえば、この検証によって、バージョンは同じでコンテンツが異なるパッケージが既にデプロイされているかどうかを検出できます。For example, the validation can detect whether a package with the same version but different content was already deployed.

アプリケーションが正常にパッケージ化され、検証に合格したら、デプロイ操作を迅速化するためにパッケージを圧縮することを検討してください。Once the application is packaged correctly and passes validation, consider compressing the package for faster deployment operations.

パッケージを圧縮するCompress a package

パッケージが大きい場合や多数のファイルを含む場合は、短時間でデプロイできるようにこのパッケージを圧縮できます。When a package is large or has many files, you can compress it for faster deployment. 圧縮により、ファイル数を減らし、ファイルのサイズを小さくすることができます。Compression reduces the number of files and the package size. 圧縮されたアプリケーション パッケージの場合は、圧縮されていないパッケージと比較して、(圧縮がコピーの一部として実行される場合は特に) パッケージのアップロードに時間がかかる場合があります。For a compressed application package, uploading the application package may take longer compared to uploading the uncompressed package, especially if compression is done as part of copy. 圧縮されたパッケージの場合、アプリケーションの種類の登録登録解除が高速になります。With compression, registering and un-registering the application type are faster.

デプロイのメカニズムは、圧縮されているパッケージでも圧縮されていないパッケージでも変わりません。The deployment mechanism is same for compressed and uncompressed packages. パッケージが圧縮されている場合、パッケージはクラスター イメージ ストアに格納され、アプリケーションが実行される前にノード上で圧縮が解除されます。If the package is compressed, it is stored as such in the cluster image store and it's uncompressed on the node before the application is run. 圧縮によって、有効な Service Fabric パッケージが、圧縮されたバージョンで置き換えられます。The compression replaces the valid Service Fabric package with the compressed version. フォルダーへの書き込みのアクセス許可を与える必要があります。The folder must allow write permissions. 既に圧縮済みのパッケージの圧縮を実行しても、変化はありません。Running compression on an already compressed package yields no changes.

Copy-ServiceFabricApplicationPackage Powershell コマンドを CompressPackage スイッチで実行して、パッケージを圧縮することができます。You can compress a package by running the Powershell command Copy-ServiceFabricApplicationPackage with CompressPackage switch. UncompressPackage スイッチを使用して同じコマンドを実行すると、パッケージの圧縮を解除することができます。You can uncompress the package with the same command, using UncompressPackage switch.

次のコマンドでは、パッケージをイメージ ストアにコピーせずに圧縮しています。The following command compresses the package without copying it to the image store. 必要に応じて、Copy-ServiceFabricApplicationPackageSkipCopy フラグを指定せずに実行して、圧縮されたパッケージを 1 つまたは複数の Service Fabric クラスターにコピーすることができます。You can copy a compressed package to one or more Service Fabric clusters, as needed, using Copy-ServiceFabricApplicationPackage without the SkipCopy flag. このパッケージには、codeconfigdata の各パッケージの zip 圧縮されたファイルが含まれています。The package now includes zipped files for the code, config, and data packages. アプリケーション マニフェストとサービス マニフェストは、多くの内部操作に必要なため、圧縮されません。The application manifest and the service manifests are not zipped, because they are needed for many internal operations. たとえば、パッケージ共有、特定の検証のためのアプリケーションの種類名とバージョンの抽出では、必ずマニフェストへのアクセスが必要になります。For example, package sharing, application type name and version extraction for certain validations all need to access the manifests. マニフェストを zip 圧縮すると、これらの操作が非効率的になります。Zipping the manifests would make these operations inefficient.

tree /f .\MyApplicationType
D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │       MySetup.bat
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat
Copy-ServiceFabricApplicationPackage -ApplicationPackagePath .\MyApplicationType -CompressPackage -SkipCopy
tree /f .\MyApplicationType
D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
       ServiceManifest.xml
       MyCode.zip
       MyConfig.zip
       MyData.zip

または、Copy-ServiceFabricApplicationPackage を使用して 1 ステップでパッケージを圧縮してコピーできます。Alternatively, you can compress and copy the package with Copy-ServiceFabricApplicationPackage in one step. パッケージのサイズが大きい場合は、パッケージの圧縮とクラスターへのアップロードの両方の時間を確保するのに十分な大きいタイムアウト値を指定してください。If the package is large, provide a high enough timeout to allow time for both the package compression and the upload to the cluster.

Copy-ServiceFabricApplicationPackage -ApplicationPackagePath .\MyApplicationType -ApplicationPackagePathInImageStore MyApplicationType -ImageStoreConnectionString fabric:ImageStore -CompressPackage -TimeoutSec 5400

内部的に、Service Fabric がアプリケーション パッケージのチェックサムを計算して検証を行います。Internally, Service Fabric computes checksums for the application packages for validation. 圧縮を使用すると、各パッケージの zip 圧縮バージョンでチェックサムが計算されます。When using compression, the checksums are computed on the zipped versions of each package. 同じアプリケーション パッケージから新しい zip を生成すると、異なるチェックサムが作成されます。Generating a new zip from the same application package creates different checksums. 検証エラーを防ぐには、diff プロビジョニングを使用します。To prevent validation errors, use diff provisioning. このオプションを使用する場合は、変更されていないパッケージを新しいバージョンに含めないでください。With this option, do not include the unchanged packages in the new version. 代わりに、新しいサービス マニフェストから直接参照してください。Instead, reference them directly from the new service manifest.

diff プロビジョニングが選択肢とならず、パッケージを含める必要がある場合は、チェックサムの不一致を避けるために codeconfig、および data の各パッケージの新しいバージョンを生成してください。If diff provisioning is not an option and you must include the packages, generate new versions for the code, config, and data packages to avoid checksum mismatch. 圧縮されたパッケージを使用する場合は、以前のバージョンで圧縮が使用されているかどうかを問わず、変更されていないパッケージの新しいバージョンを生成する必要があります。Generating new versions for unchanged packages is necessary when a compressed package is used, regardless of whether previous version uses compression or not.

これでパッケージは正しくパッケージ化、検証、および (必要に応じて) 圧縮されたため、1 つまたは複数の Service Fabric クラスターにデプロイする準備ができました。The package is now packaged correctly, validated, and compressed (if needed), so it is ready for deployment to one or more Service Fabric clusters.

Visual Studio を使ってデプロイするときにパッケージを圧縮するCompress packages when deploying using Visual Studio

CopyPackageParameters 要素を発行プロファイルに追加し、CompressPackage 属性を true に設定することで、デプロイ時にパッケージを圧縮するよう Visual Studio に指示できます。You can instruct Visual Studio to compress packages on deployment, by adding the CopyPackageParameters element to your publish profile, and set the CompressPackage attribute to true.

    <PublishProfile xmlns="http://schemas.microsoft.com/2015/05/fabrictools">
        <ClusterConnectionParameters ConnectionEndpoint="mycluster.westus.cloudapp.azure.com" />
        <ApplicationParameterFile Path="..\ApplicationParameters\Cloud.xml" />
        <CopyPackageParameters CompressPackage="true"/>
    </PublishProfile>

sfpkg の作成Create an sfpkg

バージョン 6.1 より、Service Fabric では外部ストアからのプロビジョニングが可能になりました。Starting with version 6.1, Service Fabric allows provisioning from an external store. この場合、アプリケーション パッケージをイメージ ストアにコピーする必要はありません。With this option, the application package doesn't have to be copied to the image store. 代わりに、sfpkg を作成して外部ストアにアップロードし、プロビジョニング時にダウンロード URI を Service Fabric に提供することができます。Instead, you can create an sfpkg and upload it to an external store, then provide the download URI to Service Fabric when provisioning. 同じパッケージを複数のクラスターにプロビジョニングできます。The same package can be provisioned to multiple clusters. 外部ストアからプロビジョニングすることにより、パッケージを各クラスターにコピーするのに要する時間を節約できます。Provisioning from the external store saves the time needed to copy the package to each cluster.

sfpkg ファイルは、初期アプリケーション パッケージを含む、拡張子が ".sfpkg" の zip です。The sfpkg file is a zip that contains the initial application package and has the extension ".sfpkg". zip には、圧縮されているアプリケーション パッケージと圧縮されていないアプリケーション パッケージのどちらも含めることができます。Inside the zip, the application package can be compressed or uncompressed. zip 内のアプリケーション パッケージの圧縮は、前述のように、コード、構成、およびデータ パッケージ レベルで行われます。The compression of the application package inside the zip is done at code, config, and data package levels, as mentioned earlier.

sfpkg を作成するには、圧縮されているかどうかにかかわらず、元のアプリケーション パッケージを含むフォルダーから開始します。To create an sfpkg, start with a folder that contains the original application package, compressed or not. その後、任意のユーティリティを使用してフォルダーを圧縮して、拡張子 ".sfpkg" を付けます。Then, use any utility to zip the folder with the extension ".sfpkg". たとえば、ZipFile.CreateFromDirectory を使用します。For example, use ZipFile.CreateFromDirectory.

ZipFile.CreateFromDirectory(appPackageDirectoryPath, sfpkgFilePath);

sfpkg は、Service Fabric の外部の帯域外の外部ストアにアップロードする必要があります。The sfpkg must be uploaded to the external store out of band, outside of Service Fabric. 外部ストアには、REST http または https エンドポイントを公開している任意のストアを指定できます。The external store can be any store that exposes a REST http or https endpoint. プロビジョニング中、Service Fabric は、GET 操作を実行して sfpkg アプリケーション パッケージをダウンロードします。そのため、ストアではパッケージの READ アクセスを許可する必要があります。During provisioning, Service Fabric executes a GET operation to download the sfpkg application package, so the store must allow READ access for the package.

パッケージをプロビジョニングするには、ダウンロード URI とアプリケーションの種類の情報を必要とする外部プロビジョニングを使用します。To provision the package, use external provision, which requires the download URI and the application type information.

注意

現在、イメージ ストアの相対パスに基づくプロビジョニングでは、sfpkg ファイルはサポートされていません。Provisioning based on image store relative path doesn't currently support sfpkg files. したがって、sfpkg をイメージ ストアにコピーしてはいけません。Therefore, the sfpkg should not be copied to the image store.

次のステップNext steps

アプリケーションのデプロイと削除」では、PowerShell を使用してアプリケーション インスタンスを管理する方法について説明していますDeploy and remove applications describes how to use PowerShell to manage application instances

複数の環境のアプリケーション パラメーターの管理」では、複数のアプリケーション インスタンスに対してパラメーターと環境変数を構成する方法について説明しています。Managing application parameters for multiple environments describes how to configure parameters and environment variables for different application instances.

アプリケーションのセキュリティ ポリシーの構成」では、セキュリティ ポリシーの下でサービスを実行して、アクセスを制限する方法について説明しています。Configure security policies for your application describes how to run services under security policies to restrict access.