Create a Service Fabric cluster using Azure Resource Manager

  • Article

An Azure Service Fabric cluster is a network-connected set of virtual machines into which your microservices are deployed and managed. A Service Fabric cluster running in Azure is an Azure resource and is deployed using the Azure Resource Manager. This article describes how to deploy a secure Service Fabric cluster in Azure using the Resource Manager. You can use a default cluster template or a custom template. If you don't already have a custom template, you can learn how to create one.

The type of security chosen to secure the cluster (i.e.: Windows identity, X509 etc.) must be specified for the initial creation of the cluster, and cannot be changed thereafter. Before setting up a cluster, read Service Fabric cluster security scenarios. In Azure, Service Fabric uses x509 certificate to secure your cluster and its endpoints, authenticate clients, and encrypt data. Microsoft Entra ID is also recommended to secure access to management endpoints. For more information, read Set up Microsoft Entra ID to authenticate clients.

If you are creating a production cluster to run production workloads, we recommend you first read through the production readiness checklist.

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Prerequisites

In this article, use the Service Fabric RM PowerShell or Azure CLI modules to deploy a cluster:

You can find the reference documentation for the Service Fabric modules here:

Sign in to Azure

Before running any of the commands in this article, first sign in to Azure.

Connect-AzAccount -Environment AzureChinaCloud
Set-AzContext -SubscriptionId <subscriptionId>

az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.
az account set --subscription $subscriptionId

Create a new cluster using a system generated self-signed certificate

Use the following commands to create a cluster secured with a system generated self-signed certificate. This command sets up a primary cluster certificate that is used for cluster security and to set up admin access to perform management operations using that certificate. Self-signed certificates are useful for securing test clusters. Production clusters should be secured with a certificate from a certificate authority (CA).

Use the default cluster template that ships in the module

You can use either the following PowerShell or Azure CLI commands to create a cluster quickly using the default template.

The default template used is available here for Windows and here for Ubuntu.

The following commands can create either Windows or Linux clusters, depending on how you specify the OS parameter. Both PowerShell/CLI commands output the certificate in the specified CertificateOutputFolder (make sure the certificate folder location you specify already exists before running the command!).

Note

The following PowerShell command only works with the Azure PowerShell Az module. To check the current version of Azure Resource Manager PowerShell version, run the following PowerShell command "Get-Module Az". Follow this link to upgrade your Azure Resource Manager PowerShell version.

Deploy the cluster using PowerShell:

$resourceGroupLocation="chinanorth"
$resourceGroupName="mycluster"
$vaultName="myvault"
$vaultResourceGroupName="myvaultrg"
$CertSubjectName="mycluster.chinanorth.cloudapp.chinacloudapi.cn"
$certPassword="Password123!@#" | ConvertTo-SecureString -AsPlainText -Force 
$vmpassword="Password4321!@#" | ConvertTo-SecureString -AsPlainText -Force
$vmuser="myadmin"
$os="WindowsServer2016DatacenterwithContainers"
$certOutputFolder="c:\certificates"

New-AzServiceFabricCluster -ResourceGroupName $resourceGroupName -Location $resourceGroupLocation -CertificateOutputFolder $certOutputFolder -CertificatePassword $certpassword -CertificateSubjectName $CertSubjectName -OS $os -VmPassword $vmpassword -VmUserName $vmuser

Deploy the cluster using Azure CLI:

declare resourceGroupLocation="chinanorth"
declare resourceGroupName="mylinux"
declare vaultResourceGroupName="myvaultrg"
declare vaultName="myvault"
declare CertSubjectName="mylinux.chinanorth.cloudapp.chinacloudapi.cn"
declare vmpassword="Password!1"
declare certpassword="Password!4321"
declare vmuser="myadmin"
declare vmOs="UbuntuServer1804"
declare certOutputFolder="c:\certificates"

az sf cluster create --resource-group $resourceGroupName --location $resourceGroupLocation  \
	--certificate-output-folder $certOutputFolder --certificate-password $certpassword  \
	--vault-name $vaultName --vault-resource-group $resourceGroupName  \
	--template-file $templateFilePath --parameter-file $parametersFilePath --vm-os $vmOs  \
	--vm-password $vmpassword --vm-user-name $vmuser

Use your own custom template

If you need to author a custom template to suit your needs, it is highly recommended that you start with one of the templates that are available on the Azure Service Fabric template samples. Learn how to customize your cluster template.

If you already have a custom template, double-check that all the three certificate related parameters in the template and the parameter file are named as follows and values are null as follows:

   "certificateThumbprint": {
      "value": ""
    },
    "sourceVaultValue": {
      "value": ""
    },
    "certificateUrlValue": {
      "value": ""
    },

Deploy the cluster using PowerShell:

$resourceGroupLocation="chinanorth"
$resourceGroupName="mycluster"
$CertSubjectName="mycluster.chinanorth.cloudapp.chinacloudapi.cn"
$certPassword="Password!1" | ConvertTo-SecureString -AsPlainText -Force 
$certOutputFolder="c:\certificates"

$parameterFilePath="c:\mytemplates\mytemplateparm.json"
$templateFilePath="c:\mytemplates\mytemplate.json"

New-AzServiceFabricCluster -ResourceGroupName $resourceGroupName -CertificateOutputFolder $certOutputFolder -CertificatePassword $certpassword -CertificateSubjectName $CertSubjectName -TemplateFile $templateFilePath -ParameterFile $parameterFilePath

Deploy the cluster using Azure CLI:

declare certPassword=""
declare resourceGroupLocation="chinanorth"
declare resourceGroupName="mylinux"
declare certSubjectName="mylinuxsecure.chinanorth.cloudapp.chinacloudapi.cn"
declare parameterFilePath="c:\mytemplates\linuxtemplateparm.json"
declare templateFilePath="c:\mytemplates\linuxtemplate.json"
declare certOutputFolder="c:\certificates"

az sf cluster create --resource-group $resourceGroupName --location $resourceGroupLocation  \
	--certificate-output-folder $certOutputFolder --certificate-password $certPassword  \
	--certificate-subject-name $certSubjectName \
	--template-file $templateFilePath --parameter-file $parametersFilePath

Create a new cluster using your own X.509 certificate

You can use the following command to specify an existing certificate to create and secure a new cluster with.

If this is a CA signed certificate that you will end up using for other purposes as well, then it is recommended that you provide a distinct resource group specifically for your key vault. We recommend that you put the key vault into its own resource group. This action lets you remove the compute and storage resource groups, including the resource group that contains your Service Fabric cluster, without losing your keys and secrets. The resource group that contains your key vault must be in the same region as the cluster that is using it.

Use the default five nodes, one node type template that ships in the module

The default template used is available here for Windows and here for Ubuntu.

Deploy the cluster using PowerShell:

$resourceGroupLocation="chinanorth"
$resourceGroupName="mycluster"
$vaultName="myvault"
$vaultResourceGroupName="myvaultrg"
$certPassword="Password!1" | ConvertTo-SecureString -AsPlainText -Force 
$vmpassword=("Password!4321" | ConvertTo-SecureString -AsPlainText -Force) 
$vmuser="myadmin"
$os="WindowsServer2016DatacenterwithContainers"

New-AzServiceFabricCluster -ResourceGroupName $resourceGroupName -Location $resourceGroupLocation -KeyVaultResourceGroupName $vaultResourceGroupName -KeyVaultName $vaultName -CertificateFile C:\MyCertificates\chackocertificate3.pfx -CertificatePassword $certPassword -OS $os -VmPassword $vmpassword -VmUserName $vmuser

Deploy the cluster using Azure CLI:

declare vmPassword="Password!1"
declare certPassword="Password!1"
declare vmUser="myadmin"
declare resourceGroupLocation="chinanorth"
declare resourceGroupName="mylinux"
declare vaultResourceGroupName="myvaultrg"
declare vaultName="myvault"
declare certificate-file="c:\certificates\mycert.pem"
declare vmOs="UbuntuServer1804"

az sf cluster create --resource-group $resourceGroupName --location $resourceGroupLocation  \
	--certificate-file $certificate-file --certificate-password $certPassword  \
	--vault-name $vaultName --vault-resource-group $vaultResourceGroupName  \
    --vm-os vmOs \
	--vm-password $vmPassword --vm-user-name $vmUser

Use your own custom cluster template

If you need to author a custom template to suit your needs, it is highly recommended that you start with one of the templates that are available on the Azure Service Fabric template samples. Learn how to customize your cluster template.

If you already have a custom template, then make sure to double check that all the three certificate related parameters in the template and the parameter file are named as follows and values are null as follows.

   "certificateThumbprint": {
      "value": ""
    },
    "sourceVaultValue": {
      "value": ""
    },
    "certificateUrlValue": {
      "value": ""
    },

Deploy the cluster using PowerShell:

$resourceGroupLocation="chinanorth"
$resourceGroupName="mycluster"
$vaultName="myvault"
$vaultResourceGroupName="myvaultrg"
$certPassword="Password!1" | ConvertTo-SecureString -AsPlainText -Force 
$os="WindowsServer2016DatacenterwithContainers"
$parameterFilePath="c:\mytemplates\mytemplateparm.json"
$templateFilePath="c:\mytemplates\mytemplate.json"
$certificateFile="C:\MyCertificates\chackonewcertificate3.pem"

New-AzServiceFabricCluster -ResourceGroupName $resourceGroupName -Location $resourceGroupLocation -TemplateFile $templateFilePath -ParameterFile $parameterFilePath -KeyVaultResourceGroupName $vaultResourceGroupName -KeyVaultName $vaultName -CertificateFile $certificateFile -CertificatePassword $certPassword

Deploy the cluster using Azure CLI:

declare certPassword="Password!1"
declare resourceGroupLocation="chinanorth"
declare resourceGroupName="mylinux"
declare vaultResourceGroupName="myvaultrg"
declare vaultName="myvault"
declare parameterFilePath="c:\mytemplates\linuxtemplateparm.json"
declare templateFilePath="c:\mytemplates\linuxtemplate.json"

az sf cluster create --resource-group $resourceGroupName --location $resourceGroupLocation  \
	--certificate-file $certificate-file --certificate-password $password  \
	--vault-name $vaultName --vault-resource-group $vaultResourceGroupName  \
	--template-file $templateFilePath --parameter-file $parametersFilePath

Use a pointer to a secret uploaded into a key vault

To use an existing key vault, the key vault must be enabled for deployment to allow the compute resource provider to get certificates from it and install it on cluster nodes.

Deploy the cluster using PowerShell:

Set-AzKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -EnabledForDeployment

$parameterFilePath="c:\mytemplates\mytemplate.json"
$templateFilePath="c:\mytemplates\mytemplateparm.json"
$secretID="https://test1.vault.azure.cn:443/secrets/testcertificate4/55ec7c4dc61a462bbc645ffc9b4b225f"

New-AzServiceFabricCluster -ResourceGroupName $resourceGroupName -SecretIdentifier $secretID -TemplateFile $templateFilePath -ParameterFile $parameterFilePath

Deploy the cluster using Azure CLI:

declare $resourceGroupName = "testRG"
declare $parameterFilePath="c:\mytemplates\mytemplate.json"
declare $templateFilePath="c:\mytemplates\mytemplateparm.json"
declare $secretID="https://test1.vault.azure.cn:443/secrets/testcertificate4/55ec7c4dc61a462bbc645ffc9b4b225f"

az sf cluster create --resource-group $resourceGroupName --location $resourceGroupLocation  \
	--secret-identifier $secretID  \
	--template-file $templateFilePath --parameter-file $parameterFilePath

Next steps

At this point, you have a secure cluster running in Azure. Next, connect to your cluster and learn how to manage application secrets.

For the JSON syntax and properties to use a template, see Microsoft.ServiceFabric/clusters template reference.