Tutorial: Deploy a Service Fabric Windows cluster into an Azure virtual network

This tutorial is part one of a series. You learn how to deploy a Service Fabric cluster running Windows into an Azure virtual network (VNET) and network security group using PowerShell and a template. When you're finished, you have a cluster running in the cloud that you can deploy applications to. To create a Linux cluster using Azure CLI, see Create a secure Linux cluster on Azure.

This tutorial describes a production scenario. If you want to quickly create a smaller cluster for testing purposes, see Create a test cluster.

In this tutorial, you learn how to:

  • Create a VNET in Azure using PowerShell
  • Create a key vault and upload a certificate
  • Create a secure Service Fabric cluster in Azure PowerShell
  • Secure the cluster with an X.509 certificate
  • Connect to the cluster using PowerShell
  • Remove a cluster

In this tutorial series you learn how to:

Prerequisites

Before you begin this tutorial:

The following procedures create a five-node Service Fabric cluster. To calculate cost incurred by running a Service Fabric cluster in Azure use the Azure Pricing Calculator.

Key concepts

A Service Fabric cluster is a network-connected set of virtual or physical machines into which your microservices are deployed and managed. Clusters can scale to thousands of machines. A machine or VM that is part of a cluster is called a node. Each node is assigned a node name (a string). Nodes have characteristics such as placement properties.

A node type defines the size, number, and properties for a set of virtual machines in the cluster. Every defined node type is set up as a virtual machine scale set, an Azure compute resource you use to deploy and manage a collection of virtual machines as a set. Each node type can then be scaled up or down independently, have different sets of ports open, and can have different capacity metrics. Node types are used to define roles for a set of cluster nodes, such as "front end" or "back end". Your cluster can have more than one node type, but the primary node type must have at least five VMs for production clusters (or at least three VMs for test clusters). Service Fabric system services are placed on the nodes of the primary node type.

The cluster is secured with a cluster certificate. A cluster certificate is an X.509 certificate used to secure node-to-node communication and authenticate the cluster management endpoints to a management client. The cluster certificate also provides an SSL for the HTTPS management API and for Service Fabric Explorer over HTTPS. Self signed certificates are useful for test clusters. For production clusters, use a certificate from a certificate authority (CA) as the cluster certificate.

The cluster certificate must:

  • contain a private key.
  • be created for key exchange, which is exportable to a Personal Information Exchange (.pfx) file.
  • have a subject name that matches the domain that you use to access the Service Fabric cluster. This matching is required to provide SSL for the cluster's HTTPS management endpoints and Service Fabric Explorer. You cannot obtain an SSL certificate from a certificate authority (CA) for the .cloudapp.azure.com domain. You must obtain a custom domain name for your cluster. When you request a certificate from a CA, the certificate's subject name must match the custom domain name that you use for your cluster.

Azure Key Vault is used to manage certificates for Service Fabric clusters in Azure. When a cluster is deployed in Azure, the Azure resource provider responsible for creating Service Fabric clusters pulls certificates from Key Vault and installs them on the cluster VMs.

This tutorial displays a cluster with five nodes in a single node type. For any production cluster deployment, however, capacity planning is an important step. Here are some things to consider as a part of that process.

  • The number of nodes and node types that your cluster needs
  • The properties of each of node type (for example size, primary, internet facing, and number of VMs)
  • The reliability and durability characteristics of the cluster

Download and explore the template

Download the following Resource Manager template files:

This template deploys a secure cluster of five virtual machines and a single node type into a virtual network and a network security group. Other sample templates can be found on GitHub. The azuredeploy.json deploys a number resources, including the following.

Service Fabric cluster

In the Microsoft.ServiceFabric/clusters resource, a Windows cluster is configured with the following characteristics:

  • a single node type
  • five nodes in the primary node type (configurable in the template parameters)
  • OS: Windows Server 2016 Datacenter with Containers (configurable in the template parameters)
  • certificate secured (configurable in the template parameters)
  • reverse proxy is enabled
  • DNS service is enabled
  • Durability level of Bronze (configurable in the template parameters)
  • Reliability level of Silver (configurable in the template parameters)
  • client connection endpoint: 19000 (configurable in the template parameters)
  • HTTP gateway endpoint: 19080 (configurable in the template parameters)

Azure load balancer

In the Microsoft.Network/loadBalancers resource, a load balancer is configured and probes and rules are setup for the following ports:

  • client connection endpoint: 19000
  • HTTP gateway endpoint: 19080
  • application port: 80
  • application port: 443
  • Service Fabric reverse proxy: 19081

If any other application ports are needed, then you will need to adjust the Microsoft.Network/loadBalancers resource and the Microsoft.Network/networkSecurityGroups resource to allow the traffic in.

Virtual network, subnet, and network security group

The names of the virtual network, subnet, and network security group are declared in the template parameters. Address spaces of the virtual network and subnet are also declared in the template parameters and configured in the Microsoft.Network/virtualNetworks resource:

  • virtual network address space: 172.16.0.0/20
  • Service Fabric subnet address space: 172.16.2.0/23

The following inbound traffic rules are enabled in the Microsoft.Network/networkSecurityGroups resource. You can change the port values by changing the template variables.

  • ClientConnectionEndpoint (TCP): 19000
  • HttpGatewayEndpoint (HTTP/TCP): 19080
  • SMB : 445
  • Internodecommunication - 1025, 1026, 1027
  • Ephemeral port range – 49152 to 65534 (need a min of 256 ports )
  • Ports for application use: 80 and 443
  • Application port range – 49152 to 65534 (used for service to service communication and unlike are not opened on the Load balancer )
  • Block all other ports

If any other application ports are needed, then you will need to adjust the Microsoft.Network/loadBalancers resource and the Microsoft.Network/networkSecurityGroups resource to allow the traffic in.

Set template parameters

The azuredeploy.parameters.json parameters file declares many values used to deploy the cluster and associated resources. Some of the parameters that you might need to modify for your deployment:

Parameter Example value Notes
adminUserName vmadmin Admin username for the cluster VMs.Username requirements for VM
adminPassword Password#1234 Admin password for the cluster VMs. Password requirements for VM
clusterName mysfcluster123 Name of the cluster. Can contain letters and numbers only. Length can be between 3 and 23 characters.
location southcentralus Location of the cluster.
certificateThumbprint

Value should be empty if creating a self-signed certificate or providing a certificate file.

To use an existing certificate previously uploaded to a key vault, fill in the certificate SHA1 thumbprint value. For example, "6190390162C988701DB5676EB81083EA608DCCF3"

.
certificateUrlValue

Value should be empty if creating a self-signed certificate or providing a certificate file.

To use an existing certificate previously uploaded to a key vault, fill in the certificate URL. For example, "https://mykeyvault.vault.azure.net:443/secrets/mycertificate/02bea722c9ef4009a76c5052bcbf8346".

sourceVaultValue

Value should be empty if creating a self-signed certificate or providing a certificate file.

To use an existing certificate previously uploaded to a key vault, fill in the source vault value. For example, "/subscriptions/333cc2c84-12fa-5778-bd71-c71c07bf873f/resourceGroups/MyTestRG/providers/Microsoft.KeyVault/vaults/MYKEYVAULT".

Deploy the virtual network and cluster

Next, set up the network topology and deploy the Service Fabric cluster. The azuredeploy.json Resource Manager template creates a virtual network (VNET) and also a subnet and network security group (NSG) for Service Fabric. The template also deploys a cluster with certificate security enabled. For production clusters, use a certificate from a certificate authority (CA) as the cluster certificate. A self-signed certificate can be used to secure test clusters.

Create a cluster using an existing certificate

The following script uses the New-AzureRmServiceFabricCluster cmdlet and a template to deploy a new cluster in Azure. The cmdlet also creates a new key vault in Azure and uploads your certificate.

# Variables.
$groupname = "sfclustertutorialgroup"
$clusterloc="southcentralus"  # must match the location parameter in the template
$templatepath="C:\temp\cluster"

$certpwd="q6D7nN%6ck@6" | ConvertTo-SecureString -AsPlainText -Force
$clustername = "mysfcluster123"  # must match the clusterName parameter in the template
$vaultname = "clusterkeyvault123"
$vaultgroupname="clusterkeyvaultgroup123"
$subname="$clustername.$clusterloc.cloudapp.azure.com"

# sign in to your Azure account and select your subscription
Connect-AzureRmAccount
Get-AzureRmSubscription
Set-AzureRmContext -SubscriptionId <guid>

# Create a new resource group for your deployment and give it a name and a location.
New-AzureRmResourceGroup -Name $groupname -Location $clusterloc

# Create the Service Fabric cluster.
New-AzureRmServiceFabricCluster  -ResourceGroupName $groupname -TemplateFile "$templatepath\azuredeploy.json" `
-ParameterFile "$templatepath\azuredeploy.parameters.json" -CertificatePassword $certpwd `
-KeyVaultName $vaultname -KeyVaultResourceGroupName $vaultgroupname -CertificateFile $certpath

Create a cluster using a new, self-signed certificate

The following script uses the New-AzureRmServiceFabricCluster cmdlet and a template to deploy a new cluster in Azure. The cmdlet also creates a new key vault in Azure, adds a new self-signed certificate to the key vault, and downloads the certificate file locally.

# Variables.
$groupname = "sfclustertutorialgroup"
$clusterloc="southcentralus"  # must match the location parameter in the template
$templatepath="C:\temp\cluster"

$certpwd="q6D7nN%6ck@6" | ConvertTo-SecureString -AsPlainText -Force
$certfolder="c:\mycertificates\"
$clustername = "mysfcluster123"
$vaultname = "clusterkeyvault123"
$vaultgroupname="clusterkeyvaultgroup123"
$subname="$clustername.$clusterloc.cloudapp.azure.com"

# sign in to your Azure account and select your subscription
Connect-AzureRmAccount
Get-AzureRmSubscription
Set-AzureRmContext -SubscriptionId <guid>

# Create a new resource group for your deployment and give it a name and a location.
New-AzureRmResourceGroup -Name $groupname -Location $clusterloc

# Create the Service Fabric cluster.
New-AzureRmServiceFabricCluster  -ResourceGroupName $groupname -TemplateFile "$templatepath\azuredeploy.json" `
-ParameterFile "$templatepath\azuredeploy.parameters.json" -CertificatePassword $certpwd `
-CertificateOutputFolder $certfolder -KeyVaultName $vaultname -KeyVaultResourceGroupName $vaultgroupname -CertificateSubjectName $subname

Connect to the secure cluster

Connect to the cluster using the Service Fabric PowerShell module installed with the Service Fabric SDK. First, install the certificate into the Personal (My) store of the current user on your computer. Run the following PowerShell command:

$certpwd="q6D7nN%6ck@6" | ConvertTo-SecureString -AsPlainText -Force
Import-PfxCertificate -Exportable -CertStoreLocation Cert:\CurrentUser\My `
        -FilePath C:\mycertificates\mysfcluster20170531104310.pfx `
        -Password $certpwd

You are now ready to connect to your secure cluster.

The Service Fabric PowerShell module provides many cmdlets for managing Service Fabric clusters, applications, and services. Use the Connect-ServiceFabricCluster cmdlet to connect to the secure cluster. The certificate SHA1 thumbprint and connection endpoint details are found in the output from the previous step.

Connect-ServiceFabricCluster -ConnectionEndpoint mysfcluster123.southcentralus.cloudapp.azure.com:19000 `
          -KeepAliveIntervalInSec 10 `
          -X509Credential -ServerCertThumbprint C4C1E541AD512B8065280292A8BA6079C3F26F10 `
          -FindType FindByThumbprint -FindValue C4C1E541AD512B8065280292A8BA6079C3F26F10 `
          -StoreLocation CurrentUser -StoreName My

Check that you are connected and the cluster is healthy using the Get-ServiceFabricClusterHealth cmdlet.

Get-ServiceFabricClusterHealth

Clean up resources

The other articles in this tutorial series use the cluster you just created. If you're not immediately moving on to the next article, you might want to delete the cluster to avoid incurring charges.

Next steps

In this tutorial, you learned how to:

  • Create a VNET in Azure using PowerShell
  • Create a key vault and upload a certificate
  • Create a secure Service Fabric cluster in Azure using PowerShell
  • Secure the cluster with an X.509 certificate
  • Connect to the cluster using PowerShell
  • Remove a cluster

Next, advance to the following tutorial to learn how to scale your cluster.