The tool is installed as a dotnet global line tool via NuGet:

dotnet tool install HyperFabric.Client --global

Note that this installs the latest. Add --version X.Y.Z for a specific version.

You run the tool at the command line:

hyperfabric --json "c:\temp\manifest1.json" --loggers "Console"

Note that you can also add a File logger as well. Example:

hyperfabric --json "c:\temp\manifest1.json" --loggers "Console,File"

gives you both console and file output. The file is written to the current directory as out.json.

There are only two options - the json and logging option. For more information, type:

hyperfabric --help

Uninstall the tool from the command line:

dotnet tool uninstall HyperFabric.Client --global

This tool allows you to deploy multiple packages into a cluster via a single deployment manifest json description. It will deploy packages in parallel and also allows you to deploy dependencies in groups. It provides the option for pre and post cluster health checks so that you can check that your cluster is healthy before deployment as well as afterwards.

It also gives you the option to remove existing applications and types before deployment - which might be useful in certain development scenarios. Packages take up space plus upgrades are slower than clean deployments with the upgrade domain health checks that take place - which are omiited for clean installs.

The kind of usecases for this tool could be automated deployments via pipelines, testers setting up local manifests to build their cluster for service fabric testing or live deployments into production clusters.

It provides a json output to the console and/or file, which can be queried to check for errors.

There is a pre-deployment manifest validation to try and pick up basic errors before deployment to a cluster along with a cluster connection check.

The deployment of applications into service fabric is achieved via a Deployment Manifest. This is a json structure that contains a list of packages to be deployed, and in what order.

Ordering is handled via groups. Any package within a group is deemed suitable for parallel deployment. The order you place the groups in, determines the deployment order.

There is a section for the cluster details. The connection is required. If you are connecting to a cluster over https then you will need to provide certificate details such as a thumbprint or common name and the appropriate search option.

They are also common deployment options such as NumberOfParallelDeployments or CheckClusterHealthWaitTime. These have defaults which are detailed below.

• NumberOfParallelDeployments determines how many actual parallel deployments can take place at any one time. If a group contains more packages than this value then the tool will start new deployments as threads become available. This is optional and has a default of 5 but is bounded with a range of 1 to 10.
• CheckClusterHealthWaitTime determines the amount of time in seconds to wait for the cluster to become healthy during health checks. Optional with a range of 10 to 300 seconds.
• WorkingDirectory is the local directory where packages are copied to before being uploaded. Optional with a default of the current working directory where the tool runs.

• Connection is the connection to the cluster such as http://localhost:19080. A required value.
• FindByValue is used to search for a certificate in the store when connecting to a secured cluster. Required if connecting over https.
• Location is the store where the certificate resides. These match the standard .NET enum StoreLocation with values like LocalMachine. Defaults to CurrentUser.
• FindBy is the lookup to use in conjunction with the FindByValue. The values match the .NET X509FindType enum with values like FindByThumbprint or FindBySubjectName. Defaults to FindByThumbprint. Note that you can omit the FindBy text e.g. FindByThumbprint becomes Thumbprint.

These are containers for packages that can be deployed in parallel. Once one group is complete, it will move onto the next group. The packages themselves are defined in the Items section.

List of packages for the group to be deployed.

• PackagePath is the path to the package. A required field.
• ParameterFile is the path to the cloud parameter file for the package with its settings for deployment. A required field.
• RemoveApplicationFirst sets a flag indicating if the existing application type should be removed before deployment. Optional and has a default of false.
• CompressPackage sets a flag indicating if the package should be compressed before copying to the image store. Optional and has a default of false.
• MaxApplicationReadyWaitTime determines the amount of time (in seconds) to wait for an application to be ready once deployed. This is an optional, bounded value of between 5 and 300 seconds, default of 10.
• UpgradeMode determines how the cluster monitors an upgrade. This is optional but if upgrading, it will use UnmonitoredAuto unless set with one of the UnmonitoredAuto, UnmonitoredManual and Monitored values.

{
  "clusterDetails": {
    "connection": "http://localhost:19080"
  },
  "groups": [
    {
      "items": [
        {
          "packagePath": "c:\\temp\\app1",
          "parameterFile": "C:\\temp\\app1\\cloud.xml",
          "removeApplicationFirst": true
        }
      ]
    }
  ]
}

The above example will deploy a single package to an unsecured cluster. If the application type exists then it will be removed first - along with its applications.

{
  "options": {
    "numberOfParallelDeployments": 2,
    "checkClusterHealthWaitTime": 30
  },
  "clusterDetails": {
    "connection": "http://localhost:19080"
  },
  "groups": [
    {
      "items": [
        {
          "packagePath": "c:\\temp\\app1",
          "parameterFile": "C:\\temp\\app1\\cloud.xml",
          "removeApplicationFirst": true
        }
      ]
    }
  ]
}

The above shows an example of using the CheckClusterHealthWaitTime to check that the cluster is healthy before beginning a deployment.

{
  "options": {
    "numberOfParallelDeployments": 2,
    "CheckClusterHealthWaitTime": 45
  },
  "clusterDetails": {
    "connection": "http://localhost:19080"
  },
  "groups": [
    {
      "items": [
        {
          "packagePath": "c:\\temp\\app1",
          "parameterFile": "c:\\temp\\app1\\cloud.xml",
          "removeApplicationFirst": true
        },
        {
          "packagePath": "c:\\temp\\app2",
          "parameterFile": "c:\\temp\\app2\\cloud.xml",
          "removeApplicationFirst": true
        },
        {
          "packagePath": "c:\\temp\\app3",
          "parameterFile": "c:\\temp\\app3\\cloud.xml",
          "removeApplicationFirst": true
        },
        {
          "packagePath": "c:\\temp\\app4",
          "parameterFile": "c:\\temp\\app4\\cloud.xml",
          "removeApplicationFirst": true
        },
        {
          "packagePath": "c:\\temp\\app5",
          "parameterFile": "c:\\temp\\app5\\cloud.xml",
          "removeApplicationFirst": true
        }
      ]
    }
  ]
}

The above will deploy the packages in parallel, albeit honouring the overriden numberOfParallelDeployments value of 2. This is useful so avoid using too much resource on your deployment cluster.

{
  "clusterDetails": {
    "connection": "https://localhost:19080",
    "findBy": "Thumbprint",
    "findByValue": "69DDF57D6CC2795A6FCAAA26EE8EDC11866E275F",
    "location": "LocalMachine"
  },
  "groups": [
    {
      "items": [
        {
          "packagePath": "c:\\temp\\app1",
          "parameterFile": "C:\\temp\\app1\\cloud.xml"
        }
      ]
    }
  ]
}

This shows how to setup the secured cluster connection details.

Given an existing application has been deployed:

{
  "clusterDetails": {
    "connection": "http://localhost:19080"
  },
  "groups": [
    {
      "items": [
        {
          "packagePath": "c:\\temp\\app1",
          "parameterFile": "C:\\temp\\app1\\cloud.xml"
        }
      ]
    }
  ]
}

The following will upgrade the application to a new version:

{
  "clusterDetails": {
    "connection": "http://localhost:19080"
  },
  "groups": [
    {
      "items": [
        {
          "packagePath": "c:\\temp\\app1",
          "parameterFile": "C:\\temp\\app1\\cloud.xml",
          "upgradeMode": "Monitored",
          "maxApplicationReadyWaitTime": 180
        }
      ]
    }
  ]
}

Note that you may have to increase the MaxApplicationReadyWaitTime to a higher value (default is 10sec) as the time to stabilize will depend on the UpgradeMode used.

The available upgrade modes match the UpgradeMode enum (UnmonitoredAuto, UnmonitoredManual and Monitored). In the above example, the upgrade will stop after completing each upgrade domain and automatically monitor health before proceeding.

From the root, to build, run:

dotnet build --configuration Release 

To run all the unit and integration tests, run:

dotnet test --no-build --configuration Release

To create a package for the tool, run:

cd src/HyperFabric.Client
dotnet pack --no-build --configuration Release 

To publish the package to the nuget feed on nuget.org:

dotnet nuget push ./bin/Release/HyperFabric.Client.1.0.0.nupkg -k [THE API KEY] -s https://api.nuget.org/v3/index.json 

dotnet tool install HyperFabric.Client --version 1.0.0 --add-source "c:\work\nuget\packages" --global

hyperfabric --json "c:\temp\manifest1.json" --loggers "Console"

dotnet tool uninstall HyperFabric.Client --global

To setup your local cluster (windows) as a secured cluster:

cd "C:\Program Files\Microsoft SDKs\Service Fabric\ClusterSetup"
.\DevClusterSetup.ps1 -PathToClusterDataRoot "c:\SFDevCluster\Data" -PathToClusterLogRoot "c:\SFDevCluster\Log" -AsSecureCluster -CreateOneNodeCluster

Note the service fabric explorer will not work. Not sure how to get this working!

• GitFlow https://datasift.github.io/gitflow/IntroducingGitFlow.html